Skip to main content

Utils

Miscellaneous utility functions for ApertureDB. This class contains a collection of helper functions to interact with the database.

Utils​

Utils(client: Connector, verbose=False)

Bases: object

Helper methods to get information from aperturedb, or affect it's state.

Parameters:

NameTypeDescriptionDefault
clientConnector

The underlying Connector.

required
verbosebool

Whether to print progress messages. Defaults to False.

False

execute​

execute(query, blobs=[], success_statuses=[0])

Execute a query.

Parameters:

NameTypeDescriptionDefault
querylist

The query to execute.

required
blobslist

The blobs to send with the query.

[]
success_statuseslist

The list of success statuses.

[0]

Returns:

NameTypeDescription
result

The result of the query.

blobs

The blobs returned by the query.

status​

status()

Executes a GetStatus query. See GetStatus in the ApertureDB documentation for more information.

get_schema​

get_schema(refresh=False)

Get the schema of the database. See GetSchema in the ApertureDB documentation for more information.

visualize_schema​

visualize_schema(filename: str = None, format: str = 'png') -> Source

Visualize the schema of the database. Optionally save the visualization to a file in the specified format.

The returned object can be rendered to a file as follows:

s = utils.visualize_schema()
s.render("schema", format="png")

It can also be displayed inline in a Jupyter notebook:

from IPython.display import display
s = utils.visualize_schema()
display(s)

Relies on graphviz to be installed.

Parameters:

NameTypeDescriptionDefault
filenamestr

The filename to save the visualization to. Default is None.

None
formatstr

The format to save the visualization to. Default is "png".

'png'

Returns:

NameTypeDescription
sourceSource

The visualization of the schema.

summary​

summary()

Print a summary of the database.

This is essentially a call to GetSchema, with the results formatted in a more human-readable way.

create_entity_index​

create_entity_index(class_name, property_key, property_type=None)

Create an index for an entity class. See CreateIndex in the ApertureDB documentation for more information.

create_connection_index​

create_connection_index(class_name, property_key, property_type=None, *, src_type=None, src_class=None, dst_type=None, dst_class=None)

Create an index for a connection class. See CreateIndex in the ApertureDB documentation for more information.

remove_entity_index​

remove_entity_index(class_name, property_key)

Remove an index for an entity class. See RemoveIndex in the ApertureDB documentation for more information.

remove_connection_index​

remove_connection_index(class_name, property_key, *, src_type=None, src_class=None, dst_type=None, dst_class=None)

Remove an index for a connection class. See RemoveIndex in the ApertureDB documentation for more information.

count_images​

count_images(constraints={}) -> int

Count the number of images in the database.

Parameters:

NameTypeDescriptionDefault
constraintsdict

The constraints to apply to the query. See the Constraints wrapper class for more information.

{}

Returns:

NameTypeDescription
countint

The number of images in the database.

count_bboxes​

count_bboxes(constraints=None) -> int

Count the number of bounding boxes in the database.

Parameters:

NameTypeDescriptionDefault
constraintsdict

The constraints to apply to the query. See the Constraints wrapper class for more information.

None

Returns:

NameTypeDescription
countint

The number of bounding boxes in the database.

count_entities​

count_entities(entity_class, constraints=None) -> int

Count the number of entities in the database.

Parameters:

NameTypeDescriptionDefault
constraintsdict

The constraints to apply to the query. See the Constraints wrapper class for more information.

None

Returns:

NameTypeDescription
countint

The number of entities in the database.

count_connections​

count_connections(connections_class, constraints=None) -> int

Count the number of connections in the database.

Parameters:

NameTypeDescriptionDefault
constraintsdict

The constraints to apply to the query. See the Constraints wrapper class for more information.

None

Returns:

NameTypeDescription
countint

The number of connections in the database.

create_vector_index​

create_vector_index(class_name: str, dimensions: int, metric='CS', engines=None, metadata=None, *, kind=None, params=None) -> bool

Create a vector index on a descriptor class.

Set kind to flat, ivf, hnsw (default), or acorn. Pass engine settings directly in params, such as {"nlist": 64} for IVF. Use metadata for application fields such as the model name.

add_descriptorset​

add_descriptorset(name: str, dim: int, metric=['CS'], engine=['HNSW'], properties: Optional[Dict] = None) -> bool

Create a descriptor search space on either supported server.

Each engine gets an index on the named descriptor class, with properties as index metadata.

Parameters:

NameTypeDescriptionDefault
namestr

The name of the descriptor set.

required
dimint

The dimension of the descriptors.

required
metricstr

The metric to use for the descriptors.

['CS']
enginestr

The engine to use for the descriptors, using default engine parameters.

['HNSW']
propertiesdict

The properties of the descriptor set.

None

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

get_vector_indexes​

get_vector_indexes(class_name: Optional[str] = None) -> List[dict]

Read the vector indexes on descriptor classes, one entry per index kind.

count_descriptorsets​

count_descriptorsets() -> int

Count distinct indexed descriptor classes.

Returns:

NameTypeDescription
countint

The number of descriptor sets in the database.

get_descriptorset_list​

get_descriptorset_list() -> List[str]

List the names of indexed descriptor classes.

Returns:

NameTypeDescription
setslist of str

The list of descriptor sets in the database.

remove_descriptorset​

remove_descriptorset(set_name: str) -> bool

Remove a descriptor search space and its descriptors.

Atomically remove the descriptors, their class and indexes, and dependent connection classes and indexes. See descriptor indexes.

Parameters:

NameTypeDescriptionDefault
set_namestr

The name of the descriptor set.

required

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

remove_entities​

remove_entities(class_name: str, batched: bool = False, batch_size: int = 10000) -> bool

Remove all entities of a given class from the database.

See DeleteEntity in the ApertureDB documentation for more information.

Parameters:

NameTypeDescriptionDefault
class_namestr

The class of the entities to remove.

required
batchedbool

Whether to batch the operation. Default is False.

False
batch_sizeint

The batch size to use. Default is 10000.

10000

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

remove_connections​

remove_connections(class_name, batched=False, batch_size=10000)

Remove all connections of a given class from the database.

See DeleteConnection in the ApertureDB documentation for more information.

Parameters:

NameTypeDescriptionDefault
class_namestr

The class of the connections to remove.

required
batchedbool

Whether to batch the operation. Default is False.

False
batch_sizeint

The batch size to use. Default is 10000.

10000

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

remove_all_descriptorsets​

remove_all_descriptorsets() -> bool

Remove all descriptor sets from the database, together with descriptors, indexes and connections.

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

get_indexed_props​

get_indexed_props(class_name: str, type='entities') -> List[str]

Returns all the indexed properties for a given class.

Parameters:

NameTypeDescriptionDefault
class_namestr

The class name.

required
typestr

The type of the class. Default is "entities".

'entities'

Returns:

NameTypeDescription
indexed_propslist of str

The list of indexed properties.

count_descriptors_in_set​

count_descriptors_in_set(set_name: str) -> int

Count the number of descriptors in a descriptor set.

Parameters:

NameTypeDescriptionDefault
set_namestr

The name of the descriptor set.

required

Returns:

NameTypeDescription
totalint

The number of descriptors in the set.

get_indexes​

get_indexes(target=None, class_name: Optional[str] = None, property_key: Optional[str] = None, kind: Optional[str] = None, *, src_class=None, dst_class=None) -> List[dict]

List index definitions, optionally filtered. See GetIndexes in the ApertureDB documentation for more information.

Parameters:

NameTypeDescriptionDefault
targetstr

"entity" or "connection". Defaults to both.

None
class_namestr

Entity or connection class.

None
property_keystr

Indexed property.

None
kindstr

Index kind, such as "ordered". Defaults to all kinds.

None

Returns:

NameTypeDescription
indexesList[dict]

One dict per index with "target", "class", "property", "kind" and "params".

remove_all_indexes​

remove_all_indexes() -> bool

Remove all indexes from the database.

This may improve the performance of remove_all_objects. It may improve or degrade the performance of other operations.

Built-in indexes, which the server does not allow removing, are kept.

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

remove_all_objects​

remove_all_objects() -> bool

Remove all objects from the database.

This includes images, videos, blobs, clips, descriptor sets, descriptors, bounding boxes, polygons, frames, entities, connections, indexes and connections.

Returns:

NameTypeDescription
successbool

True if the operation was successful, False otherwise.

user_log_message​

user_log_message(message: str, level: str = 'INFO') -> None

Log a message to the user log.

This is useful because it can later be seen in Grafana, not only as log entries in the ApertureDB Logging dashboard, but also as event markers in the ApertureDB Status dashboard.

Parameters:

NameTypeDescriptionDefault
messagestr

The message to log.

required
levelstr

The level of the message. Default is "INFO".

'INFO'