API Specification 

property token: Get token.

needs_refresh(leeway=0)[source]

Check if the token needs to be refreshed.

Parameters:: leeway (int) – Leeway in seconds, before official expiration, when to consider the token expired.
Returns:: True if the token needs to be refreshed, False otherwise.
Return type:: bool

class arangoasync.database.Database(executor)[source]

Database API.

Parameters:: executor – API executor. Responsible for executing requests and handling responses.

property connection: Return the HTTP connection.

property name: Return the name of the current database.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

property context

Return the API execution context.

Returns:: API execution context. Possible values are “default”, “transaction”.
Return type:: str

property aql

Return the AQL API wrapper.

Returns:: AQL API wrapper.
Return type:: arangoasync.aql.AQL

property backup

Return Backup API wrapper.

Returns:: Backup API wrapper.
Return type:: arangoasync.backup.Backup

property cluster

Return Cluster API wrapper.

Returns:: Cluster API wrapper.
Return type:: arangoasync.cluster.Cluster

property foxx

Return Foxx API wrapper.

Warning

Foxx microservice features are no longer available in ArangoDB 4.0.

Returns:: Foxx API wrapper.
Return type:: arangoasync.foxx.Foxx

property replication

Return Replication API wrapper.

Returns:: Replication API wrapper.

async properties()[source]

Return database properties.

Returns:: Properties of the current database.
Return type:: DatabaseProperties
Raises:: DatabasePropertiesError – If retrieval fails.

References

get-information-about-the-current-database

async status()[source]

Query the server status.

Returns:: Server status.
Return type:: ServerStatusInformation
Raises:: ServerSatusError – If retrieval fails.

References

get-server-status-information

async databases()[source]

Return the names of all databases.

Note

This method can only be executed in the _system database.

Returns:: Database names.
Return type:: list
Raises:: DatabaseListError – If retrieval fails.

References

list-all-databases

async databases_accessible_to_user()[source]

Return the names of all databases accessible to the current user.

Note

This method can only be executed in the _system database.

Returns:: Database names.
Return type:: list
Raises:: DatabaseListError – If retrieval fails.

References

list-the-accessible-databases

async has_database(name)[source]

Check if a database exists.

Note

This method can only be executed from within the _system database.

Parameters:: name (str) – Database name.
Returns:: True if the database exists, False otherwise.
Return type:: bool
Raises:: DatabaseListError – If retrieval fails.

async create_database(name, users=None, replication_factor=None, write_concern=None, sharding=None)[source]

Create a new database.

Note

This method can only be executed from within the _system database.

Parameters:

name (str) – Database name.
users (list | None) – Optional list of users with access to the new database, where each user is of User type, or a dictionary with fields “username”, “password” and “active”. If not set, the default user root will be used to ensure that the new database will be accessible after it is created.
replication_factor (int | str | None) – Default replication factor for new collections created in this database. Special values include “satellite”, which will replicate the collection to every DB-Server (Enterprise Edition only), and 1, which disables replication. Used for clusters only.
write_concern (int | None) – Default write concern for collections created in this database. Determines how many copies of each shard are required to be in sync on different DB-Servers. If there are less than these many copies in the cluster a shard will refuse to write. Writes to shards with enough up-to-date copies will succeed at the same time, however. Value of this parameter can not be larger than the value of replication_factor. Used for clusters only.
sharding (str | None) – Sharding method used for new collections in this database. Allowed values are: “”, “flexible” and “single”. The first two are equivalent. Used for clusters only.

Returns:

True if the database was created successfully.

Return type:

Raises:

DatabaseCreateError – If creation fails.

References

create-a-database

async delete_database(name, ignore_missing=False)[source]

Delete a database.

Note

This method can only be executed from within the _system database.

Parameters:

name (str) – Database name.
ignore_missing (bool) – Do not raise an exception on missing database.

Returns:

True if the database was deleted successfully, False if the: database was not found but ignore_missing was set to True.

Return type:

Raises:

DatabaseDeleteError – If deletion fails.

References

drop-a-database

collection(name, doc_serializer=None, doc_deserializer=None)[source]

Return the collection API wrapper.

Parameters:

name (str) – Collection name.
doc_serializer (Serializer) – Custom document serializer. This will be used only for document operations.
doc_deserializer (Deserializer) – Custom document deserializer. This will be used only for document operations.

Returns:

Collection API wrapper.

Return type:

StandardCollection

async collections(exclude_system=None)[source]

Returns basic information for all collections in the current database, optionally excluding system collections.

Returns:: Collection names.
Return type:: list
Raises:: CollectionListError – If retrieval fails.

References

list-all-collections

async has_collection(name)[source]

Check if a collection exists in the database.

Parameters:: name (str) – Collection name.
Returns:: True if the collection exists, False otherwise.
Return type:: bool
Raises:: CollectionListError – If retrieval fails.

async create_collection(name, doc_serializer=None, doc_deserializer=None, col_type=None, write_concern=None, wait_for_sync=None, number_of_shards=None, replication_factor=None, cache_enabled=None, computed_values=None, distribute_shards_like=None, is_system=False, key_options=None, schema=None, shard_keys=None, sharding_strategy=None, smart_graph_attribute=None, smart_join_attribute=None, wait_for_sync_replication=None, enforce_replication_factor=None)[source]

Create a new collection.

Parameters:

name (str) – Collection name.
doc_serializer (Serializer) – Custom document serializer. This will be used only for document operations.
doc_deserializer (Deserializer) – Custom document deserializer. This will be used only for document operations.
col_type (CollectionType | int | str | None) – Collection type.
write_concern (int | None) – Determines how many copies of each shard are required to be in sync on the different DB-Servers.
wait_for_sync (bool | None) – If True, the data is synchronised to disk before returning from a document create, update, replace or removal operation.
number_of_shards (int | None) – In a cluster, this value determines the number of shards to create for the collection.
replication_factor (int | None) – In a cluster, this attribute determines how many copies of each shard are kept on different DB-Servers.
cache_enabled (bool | None) – Whether the in-memory hash cache for documents should be enabled for this collection.
computed_values (Jsons | None) – An optional list of objects, each representing a computed value.
distribute_shards_like (str | None) – The name of another collection. If this property is set in a cluster, the collection copies the replicationFactor, numberOfShards and shardingStrategy properties from the specified collection (referred to as the prototype collection) and distributes the shards of this collection in the same way as the shards of the other collection.
is_system (bool | None) – If True, create a system collection. In this case, the collection name should start with an underscore.
key_options (KeyOptions | dict | None) – Additional options for key generation. You may use a KeyOptions object for easier configuration, or pass a dictionary directly.
schema (dict | None) – Optional object that specifies the collection level schema for documents.
shard_keys (list | None) – In a cluster, this attribute determines which document attributes are used to determine the target shard for documents.
sharding_strategy (str | None) – Name of the sharding strategy.
smart_graph_attribute – (str | None): The attribute that is used for sharding: vertices with the same value of this attribute are placed in the same shard.
smart_join_attribute – (str | None): Determines an attribute of the collection that must contain the shard key value of the referred-to SmartJoin collection.
wait_for_sync_replication (bool | None) – If True, the server only reports success back to the client when all replicas have created the collection. Set it to False if you want faster server responses and don’t care about full replication.
enforce_replication_factor (bool | None) – If True, the server checks if there are enough replicas available at creation time and bail out otherwise. Set it to False to disable this extra check.

Returns:

Collection API wrapper.

Return type:

StandardCollection

Raises:

ValueError – If parameters are invalid.
CollectionCreateError – If the operation fails.

References

create-a-collection

async delete_collection(name, ignore_missing=False, is_system=None)[source]

Delete a collection.

Parameters:

name (str) – Collection name.
ignore_missing (bool) – Do not raise an exception on missing collection.
is_system (bool | None) – Whether to drop a system collection. This parameter must be set to True in order to drop a system collection.

Returns:

True if the collection was deleted successfully, False if the: collection was not found but ignore_missing was set to True.

Return type:

Raises:

CollectionDeleteError – If the operation fails.

References

drop-a-collection

async key_generators()[source]

Returns the available key generators for collections.

Returns:: List of available key generators.
Return type:: list
Raises:: CollectionKeyGeneratorsError – If retrieval fails.

References

get-the-available-key-generators

async has_document(document, allow_dirty_read=False, if_match=None, if_none_match=None)[source]

Check if a document exists.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” field.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

True if the document exists, False otherwise.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.

References

get-a-document-header

async document(document, allow_dirty_read=False, if_match=None, if_none_match=None)[source]

Return a document.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” field.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

Document or None if not found.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.
DocumentParseError – If the document is malformed.

References

get-a-document

async insert_document(collection, document, wait_for_sync=None, return_new=None, return_old=None, silent=None, overwrite=None, overwrite_mode=None, keep_null=None, merge_objects=None, refill_index_caches=None, version_attribute=None)[source]

Insert a new document.

Parameters:

collection (str) – Collection name.
document (dict) – Document to insert. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result. Only available if the overwrite option is used.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
overwrite (bool | None) – If set to True, operation does not fail on duplicate key and existing document is overwritten (replace-insert).
overwrite_mode (str | None) – Overwrite mode. Supersedes overwrite option. May be one of “ignore”, “replace”, “update” or “conflict”.
keep_null (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely. Applies only when overwrite_mode is set to “update” (update-insert).
merge_objects (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one. Applies only when overwrite_mode is set to “update” (update-insert).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations. Only applicable if overwrite is set to True or overwrite_mode is set to “update” or “replace”.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

References

create-a-document

async update_document(document, ignore_revs=None, wait_for_sync=None, return_new=None, return_old=None, silent=None, keep_null=None, merge_objects=None, refill_index_caches=None, version_attribute=None, if_match=None)[source]

Update a document.

Parameters:

document (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
merge_objects (bool | None) – Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to False, the value in the patch document overwrites the existing document’s value. If set to True, objects are merged.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations.
if_match (str | None) – You can conditionally update a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentUpdateError – If update fails.

References

update-a-document

async replace_document(document, ignore_revs=None, wait_for_sync=None, return_new=None, return_old=None, silent=None, refill_index_caches=None, version_attribute=None, if_match=None)[source]

Replace a document.

Parameters:

document (dict) – New document. It must contain the “_key” or “_id” field. Edge document must also have “_from” and “_to” fields.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentReplaceError – If replace fails.

References

replace-a-document

async delete_document(document, ignore_revs=None, ignore_missing=False, wait_for_sync=None, return_old=None, silent=None, refill_index_caches=None, if_match=None)[source]

Delete a document.

Parameters:

document (str | dict) – Document ID, key or body. The body must contain the “_key” or “_id” field.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
ignore_missing (bool) – Do not raise an exception on missing document. This parameter has no effect in transactions where an exception is always raised on failures.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.
if_match (bool | None) – You can conditionally remove a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True and the document was found.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentDeleteError – If deletion fails.

References

remove-a-document

graph(name, doc_serializer=None, doc_deserializer=None)[source]

Return the graph API wrapper.

Parameters:

name (str) – Graph name.
doc_serializer (Serializer) – Custom document serializer. This will be used only for document operations.
doc_deserializer (Deserializer) – Custom document deserializer. This will be used only for document operations.

Returns:

Graph API wrapper.

Return type:

Graph

async has_graph(name)[source]

Check if a graph exists in the database.

Parameters:: name (str) – Graph name.
Returns:: True if the graph exists, False otherwise.
Return type:: bool
Raises:: GraphListError – If the operation fails.

async graphs()[source]

List all graphs stored in the database.

Returns:: Graph properties.
Return type:: list
Raises:: GraphListError – If the operation fails.

References

list-all-graphs

async create_graph(name, doc_serializer=None, doc_deserializer=None, edge_definitions=None, is_disjoint=None, is_smart=None, options=None, orphan_collections=None, wait_for_sync=None)[source]

Create a new graph.

Parameters:

name (str) – Graph name.
doc_serializer (Serializer) – Custom document serializer. This will be used only for document operations.
doc_deserializer (Deserializer) – Custom document deserializer. This will be used only for document operations.
edge_definitions (list | None) – List of edge definitions, where each edge definition entry is a dictionary with fields “collection” (name of the edge collection), “from” (list of vertex collection names) and “to” (list of vertex collection names).
is_disjoint (bool | None) – Whether to create a Disjoint SmartGraph instead of a regular SmartGraph (Enterprise Edition only).
is_smart (bool | None) – Define if the created graph should be smart (Enterprise Edition only).
options (GraphOptions | dict | None) – Options for creating collections within this graph.
orphan_collections (list | None) – An array of additional vertex collections. Documents in these collections do not have edges within this graph.
wait_for_sync (bool | None) – If True, wait until everything is synced to disk.

Returns:

Graph API wrapper.

Return type:

Graph

Raises:

GraphCreateError – If the operation fails.

References

create-a-graph

async delete_graph(name, drop_collections=None, ignore_missing=False)[source]

Drops an existing graph object by name.

Parameters:

name (str) – Graph name.
drop_collections (bool | None) – Optionally all collections not used by other graphs can be dropped as well.
ignore_missing (bool) – Do not raise an exception on missing graph.

Returns:

True if the graph was deleted successfully, False if the: graph was not found but ignore_missing was set to True.

Return type:

Raises:

GraphDeleteError – If the operation fails.

References

drop-a-graph

async view(name)[source]

Return the properties of a view.

Parameters:: name (str) – View name.
Returns:: View properties.
Return type:: dict
Raises:: ViewGetError – If the operation fails.

References

async view_info(name)[source]

Return basic information about a specific view.

Parameters:: name (str) – View name.
Returns:: View information.
Return type:: dict
Raises:: ViewGetError – If the operation fails.

References

async views()[source]

List all views in the database along with their summary information.

Returns:: List of views with their properties.
Return type:: list
Raises:: ViewListError – If the operation fails.

References

async create_view(name, view_type, properties=None)[source]

Create a view.

Parameters:

name (str) – View name.
view_type (str) – Type of the view (e.g., “arangosearch”, “view”).
properties (dict | None) – Properties of the view.

Returns:

View properties.

Return type:

Raises:

ViewCreateError – If the operation fails.

References

async replace_view(name, properties)[source]

Replace the properties of an existing view.

Parameters:

name (str) – View name.
properties (dict) – New properties for the view.

Returns:

Updated view properties.

Return type:

Raises:

ViewReplaceError – If the operation fails.

References

async update_view(name, properties)[source]

Update the properties of an existing view.

Parameters:

name (str) – View name.
properties (dict) – New properties for the view.

Returns:

Updated view properties.

Return type:

Raises:

ViewUpdateError – If the operation fails.

References

async rename_view(name, new_name)[source]

Rename an existing view (not supported in cluster deployments).

Parameters:

name (str) – Current view name.
new_name (str) – New view name.

Raises:

ViewRenameError – If the operation fails.

References

async delete_view(name, ignore_missing=False)[source]

Delete a view.

Parameters:

name (str) – View name.
ignore_missing (bool) – If True, do not raise an exception if the view does not exist.

Returns:

True if the view was deleted successfully, False if the: view was not found and ignore_missing was set to True.

Return type:

Raises:

ViewDeleteError – If the operation fails.

References

async analyzers()[source]

List all analyzers in the database.

Returns:: List of analyzers with their properties.
Return type:: list
Raises:: AnalyzerListError – If the operation fails.

References

list-all-analyzers

async analyzer(name)[source]

Return analyzer details.

Parameters:: name (str) – Analyzer name.
Returns:: Analyzer properties.
Return type:: dict

References

get-an-analyzer-definition

async create_analyzer(name, analyzer_type, properties=None, features=None)[source]

Create an analyzer.

Parameters:

name (str) – Analyzer name.
analyzer_type (str) – Type of the analyzer (e.g., “text”, “identity”).
properties (dict | None) – Properties of the analyzer.
features (list | None) – The set of features to set on the Analyzer generated fields. The default value is an empty array. Possible values: “frequency”, “norm”, “position”, “offset”.

Returns:

Analyzer properties.

Return type:

Raises:

AnalyzerCreateError – If the operation fails.

References

create-an-analyzer

async delete_analyzer(name, force=None, ignore_missing=False)[source]

Delete an analyzer.

Parameters:

name (str) – Analyzer name.
force (bool | None) – Remove the analyzer configuration even if in use.
ignore_missing (bool) – Do not raise an exception on missing analyzer.

Returns:

True if the analyzer was deleted successfully, False if the: analyzer was not found and ignore_missing was set to True.

Return type:

Raises:

AnalyzerDeleteError – If the operation fails.

References

remove-an-analyzer

async has_user(username)[source]

Check if a user exists.

Parameters:: username (str) – Username.
Returns:: True if the user exists, False otherwise.
Return type:: bool
Raises:: UserListError – If the operation fails.

async user(username)[source]

Fetches data about a user.

Parameters:: username (str) – Username.
Returns:: User details.
Return type:: UserInfo
Raises:: UserGetError – If the operation fails.

References

get-a-user <https://docs.arango.ai/arangodb/stable/develop/http-api/users/#get-a-user>`__

async users()[source]

Fetches data about all users.

Without the necessary permissions, you might only get data about the current user.

Returns:: User information.
Return type:: list
Raises:: UserListError – If the operation fails.

References

list-available-users

async create_user(user)[source]

Create a new user.

Parameters:

user (UserInfo | dict) – User information.

Returns:

New user details.

Return type:

UserInfo

Raises:

ValueError – If the username is missing.
UserCreateError – If the operation fails.

Example

await db.create_user(UserInfo(user="john", password="secret"))
await db.create_user({user="john", password="secret"})

References

create-a-user

async replace_user(user)[source]

Replace the data of an existing user.

Parameters:

user (UserInfo | dict) – New user information.

Returns:

New user details.

Return type:

UserInfo

Raises:

ValueError – If the username is missing.
UserReplaceError – If the operation fails.

References

replace-a-user

async update_user(user)[source]

Partially modifies the data of an existing user.

Parameters:

user (UserInfo | dict) – User information.

Returns:

Updated user details.

Return type:

UserInfo

Raises:

ValueError – If the username is missing.
UserUpdateError – If the operation fails.

References

update-a-user

async delete_user(username, ignore_missing=False)[source]

Delete a user.

Parameters:

username (str) – Username.
ignore_missing (bool) – Do not raise an exception on missing user.

Returns:

True if the user was deleted successfully, False if the user was: not found but ignore_missing was set to True.

Return type:

Raises:

UserDeleteError – If the operation fails.

References

remove-a-user

async permissions(username, full=True)[source]

Return user permissions for all databases and collections.

Parameters:

username (str) – Username.
full (bool) – If True, the result will contain the permissions for the databases as well as the permissions for the collections.

Returns:

User permissions for all databases and (optionally) collections.

Return type:

Raises:

PermissionListError – If the operation fails.

References

list-a-users-accessible-databases

async permission(username, database, collection=None)[source]

Return user permission for a specific database or collection.

Parameters:

username (str) – Username.
database (str) – Database name.
collection (str | None) – Collection name.

Returns:

User access level.

Return type:

Raises:

PermissionGetError – If the operation fails.

References

async update_permission(username, permission, database, collection=None, ignore_failure=False)[source]

Update user permissions for a specific database or collection.

Parameters:

username (str) – Username.
permission (str) – Allowed values are “rw” (administrate), “ro” (access) and “none” (no access).
database (str) – Database to set the access level for.
collection (str | None) – Collection to set the access level for.
ignore_failure (bool) – Do not raise an exception on failure.

Returns:

True if the operation was successful.

Return type:

Raises:

PermissionUpdateError – If the operation fails and ignore_failure is False.

References

async reset_permission(username, database, collection=None, ignore_failure=False)[source]

Reset user permission for a specific database or collection.

Parameters:

username (str) – Username.
database (str) – Database to reset the access level for.
collection (str | None) – Collection to reset the access level for.
ignore_failure (bool) – Do not raise an exception on failure.

Returns:

True if the operation was successful.

Return type:

Raises:

PermissionResetError – If the operation fails and ignore_failure is False.

References

async jwt_secrets()[source]

Return information on currently loaded JWT secrets.

Returns:: JWT secrets.
Return type:: dict
Raises:: JWTSecretListError – If the operation fails.

References

get-information-about-the-loaded-jwt-secrets

async reload_jwt_secrets()[source]

Hot_reload JWT secrets from disk.

Returns:: Information on reloaded JWT secrets.
Return type:: dict
Raises:: JWTSecretReloadError – If the operation fails.

References

hot-reload-the-jwt-secrets-from-disk

async create_access_token(user, name, valid_until)[source]

Create an access token for the given user.

Parameters:

user (str) – The name of the user.
name (str) – A name for the access token to make identification easier, like a short description.
valid_until (int) – A Unix timestamp in seconds to set the expiration date and time.

Returns:

Information about the created access token, including the token itself.

Return type:

AccessToken

Raises:

AccessTokenCreateError – If the operation fails.

References

create-an-access-token

async delete_access_token(user, token_id)[source]

List all access tokens for the given user.

Parameters:

user (str) – The name of the user.
token_id (int) – The ID of the access token to delete.

Raises:

AccessTokenDeleteError – If the operation fails.

References

delete-an-access-token

async list_access_tokens(user)[source]

List all access tokens for the given user.

Parameters:: user (str) – The name of the user.
Returns:: List of access tokens for the user.
Return type:: list
Raises:: AccessTokenListError – If the operation fails.

References

list-all-access-tokens

async tls()[source]

Return TLS data (keyfile, clientCA).

This API requires authentication.

Returns:

dict containing the following components:

keyfile: Information about the key file.
clientCA: Information about the Certificate Authority (CA) for client certificate verification.

Return type:

Raises:

ServerTLSError – If the operation fails.

References

get-the-tls-data

async reload_tls()[source]

Reload TLS data (keyfile, clientCA).

This is a protected API and can only be executed with superuser rights.

Returns:: New TLS data.
Return type:: dict
Raises:: ServerTLSReloadError – If the operation fails.

References

reload-the-tls-data

async encryption()[source]

Rotate the user-supplied keys for encryption.

This is a protected API and can only be executed with superuser rights. This API is not available on Coordinator nodes.

Returns:: Encryption keys.
Return type:: dict
Raises:: ServerEncryptionError – If the operation fails.

References

rotate-the-encryption-keys

async list_transactions()[source]

List all currently running stream transactions.

Returns:

List of transactions, with each transaction containing: an “id” and a “state” field.

Return type:

Raises:

TransactionListError – If the operation fails on the server side.

async execute_transaction(command, params=None, read=None, write=None, exclusive=None, allow_implicit=None, wait_for_sync=None, lock_timeout=None, max_transaction_size=None)[source]

Execute a JavaScript Transaction.

Warning

JavaScript Transactions are deprecated from ArangoDB v3.12.0 onward and will be removed in a future version.

Parameters:

command (str) – The actual transaction operations to be executed, in the form of stringified JavaScript code.
params (dict) – Optional parameters passed into the JavaScript command.
read (str | list | None) – Name(s) of collections read during transaction.
write (str | list | None) – Name(s) of collections written to during transaction with shared access.
exclusive (str | list | None) – Name(s) of collections written to during transaction with exclusive access.
allow_implicit (bool | None) – Allow reading from undeclared collections.
wait_for_sync (bool | None) – If True, will force the transaction to write all data to disk before returning.
lock_timeout (int | None) – Timeout for waiting on collection locks. Setting it to 0 will prevent ArangoDB from timing out while waiting for a lock.
max_transaction_size (int | None) – Transaction size limit in bytes.

Returns:

Result of the transaction.

Return type:

Any

Raises:

TransactionExecuteError – If the operation fails on the server side.

References

execute-a-javascript-transaction

async version(details=False)[source]

Return the server version information.

Parameters:: details (bool) – If True, return detailed version information.
Returns:: Server version information.
Return type:: dict
Raises:: ServerVersionError – If the operation fails on the server side.

References

get-the-server-version

async tasks()[source]

Fetches all existing tasks from the server.

Warning

Tasks are no longer available in ArangoDB 4.0.

Returns:: List of currently active server tasks.
Return type:: list
Raises:: TaskListError – If the list cannot be retrieved.

References

list-all-tasks

async task(task_id)[source]

Return the details of an active server task.

Warning

Tasks are no longer available in ArangoDB 4.0.

Parameters:: task_id (str)
Returns:: Details of the server task.
Return type:: dict
Raises:: TaskGetError – If the task details cannot be retrieved.

References

get-a-task

async create_task(command, task_id=None, name=None, offset=None, params=None, period=None)[source]

Create a new task.

Warning

Tasks are no longer available in ArangoDB 4.0.

Parameters:

command (str) – The JavaScript code to be executed.
task_id (str | None) – Optional task ID. If not provided, the server will generate a unique ID.
name (str | None) – The name of the task.
offset (int | None) – The offset in seconds after which the task should start executing.
params (dict | None) – Parameters to be passed to the command.
period (int | None) – The number of seconds between the executions.

Returns:

Details of the created task.

Return type:

Raises:

TaskCreateError – If the task cannot be created.

References

async delete_task(task_id, ignore_missing=False)[source]

Delete a server task.

Warning

Tasks are no longer available in ArangoDB 4.0.

Parameters:

task_id (str) – Task ID.
ignore_missing (bool) – If True, do not raise an exception if the task does not exist.

Returns:

True if the task was deleted successfully, False if the: task was not found and ignore_missing was set to True.

Return type:

Raises:

TaskDeleteError – If the operation fails.

References

delete-a-task

async engine()[source]

Returns the storage engine the server is configured to use.

Returns:: Database engine details.
Return type:: dict
Raises:: ServerEngineError – If the operation fails.

References

get-the-storage-engine-type

async time()[source]

Return server system time.

Returns:: Server system time.
Return type:: datetime.datetime
Raises:: ServerTimeError – If the operation fails.

References

get-the-system-time

async check_availability()[source]

Return ArangoDB server availability mode.

Returns:: Server availability mode, either “readonly” or “default”.
Return type:: str
Raises:: ServerCheckAvailabilityError – If the operation fails.

References

check-server-availability

async support_info()[source]

Retrieves deployment information for support purposes.

Note

As this API may reveal sensitive data about the deployment, it can only be accessed from inside the _system database.

Returns:: Deployment information
Return type:: dict
Raises:: DatabaseSupportInfoError – If the operation fails.

References

get-information-about-the-deployment

async options()[source]

Return the currently-set server options.

Returns:: Server options.
Return type:: dict
Raises:: ServerCurrentOptionsGetError – If the operation fails.

References

get-the-startup-option-configuration

async options_available()[source]

Return a description of all available server options.

Returns:: Server options description.
Return type:: dict
Raises:: ServerAvailableOptionsGetError – If the operation fails.

References

get-the-available-startup-options

async mode()[source]

Return the server mode (“default” or “readonly”).

Returns:: Server mode, either “default” or “readonly”.
Return type:: str
Raises:: ServerModeError – If the operation fails.

References

return-whether-or-not-a-server-is-in-read-only-mode

async set_mode(mode)[source]

Set the server mode to read-only or default.

Parameters:: mode (str) – Server mode. Possible values are “default” or “readonly”.
Returns:: New server mode.
Return type:: str
Raises:: ServerModeSetError – If the operation fails.

References

set-the-server-mode-to-read-only-or-default

async license()[source]

View the license information and status of an Enterprise Edition instance.

Returns:: Server license information.
Return type:: dict
Raises:: ServerLicenseGetError – If the operation fails.

References

get-information-about-the-current-license

async set_license(license, force=False)[source]

Set a new license for an Enterprise Edition instance.

Parameters:

license (str)
force (bool | None) – expires sooner than the current one.

Raises:

ServerLicenseSetError – If the operation fails.

References

set-a-new-license

async shutdown(soft=None)[source]

Initiate server shutdown sequence.

Parameters:: soft (bool | None) – If set to True, this initiates a soft shutdown.
Raises:: ServerShutdownError – If the operation fails.

References

start-the-shutdown-sequence

async shutdown_progress()[source]

Query the soft shutdown progress.

Returns:: Information about the shutdown progress.
Return type:: dict
Raises:: ServerShutdownProgressError – If the operation fails.

References

query-the-soft-shutdown-progress

async compact(change_level=None, compact_bottom_most_level=None)[source]

Compact all databases. This method requires superuser access.

Note

This command can cause a full rewrite of all data in all databases, which may take very long for large databases.

Parameters:

change_level (bool | None) – Whether or not compacted data should be moved to the minimum possible level. Default value is False.
compact_bottom_most_level (bool | None) – Whether or not to compact the bottom-most level of data. Default value is False.

Returns:

Information about the compaction process.

Return type:

Raises:

DatabaseCompactError – If the operation fails.

References

compact-all-databases

async reload_routing()[source]

Reload the routing information.

Warning

Route reloading is no longer available in ArangoDB 4.0.

Raises:: ServerReloadRoutingError – If the operation fails.

References

reload-the-routing-table

async echo(body=None)[source]

Return an object with the servers request information.

Warning

Request echoing is no longer available in ArangoDB 4.0.

Parameters:: body (dict | None) – Optional body of the request.
Returns:: Details of the request.
Return type:: dict
Raises:: ServerEchoError – If the operation fails.

References

echo-a-request

async execute(command)[source]

Execute raw Javascript command on the server.

Warning

Javascript command execution is no longer available in ArangoDB 4.0.

Parameters:: command (str) – Javascript command to execute.
Returns:: Return value of command, if any.
Raises:: ServerExecuteError – If the execution fails.

References

execute-a-script

async request(request)[source]

Execute a custom request.

Parameters:: request (Request) – Request object to be executed.
Returns:: Response object containing the result of the request.
Return type:: Response

async metrics(server_id=None)[source]

Return server metrics in Prometheus format.

Parameters:: server_id (str | None) – Returns metrics of the specified server. If no serverId is given, the asked server will reply.
Returns:: Server metrics in Prometheus format.
Return type:: str
Raises:: ServerMetricsError – If the operation fails.

References

metrics-api

async read_log_entries(upto=None, level=None, start=None, size=None, offset=None, search=None, sort=None, server_id=None)[source]

Read the global log from server.

Parameters:

upto (int | str | None) – Return the log entries up to the given level (mutually exclusive with parameter level). Allowed values are “fatal”, “error”, “warning”, “info” (default), “debug” and “trace”.
level (int | str | None) – Return the log entries of only the given level (mutually exclusive with upto).
start (int | None) – Return the log entries whose ID is greater or equal to the given value.
size (int | None) – Restrict the size of the result to the given value. This can be used for pagination.
offset (int | None) – Number of entries to skip (e.g. for pagination).
search (str | None) – Return only the log entries containing the given text.
sort (str | None) – Sort the log entries according to the given fashion, which can be “sort” or “desc”.
server_id (str | None) – Returns all log entries of the specified server. If no serverId is given, the asked server will reply.

Returns:

Server log entries.

Return type:

Raises:

ServerReadLogError – If the operation fails.

References

get-the-global-server-logs

async log_levels(server_id=None, with_appenders=None)[source]

Return current logging levels.

Parameters:

server_id (str | None) – Forward the request to the specified server.
with_appenders (bool | None) – Include appenders in the response.

Returns:

Current logging levels.

Return type:

Raises:

ServerLogLevelError – If the operation fails.

References

get-the-server-log-levels

async set_log_levels(server_id=None, with_appenders=None, **kwargs)[source]

Set the logging levels.

This method takes arbitrary keyword arguments where the keys are the logger names and the values are the logging levels. For example:

db.set_log_levels(
    agency='DEBUG',
    collector='INFO',
    threads='WARNING'
)

Keys that are not valid logger names are ignored.

Parameters:

server_id (str | None)
with_appenders (bool | None) – Include appenders in the response.
kwargs (dict) – Logging levels to be set.

Returns:

New logging levels.

Return type:

Raises:

ServerLogLevelSetError – If the operation fails.

References

set-the-structured-log-settings

async reset_log_levels(server_id=None)[source]

Reset the logging levels.

Revert the server’s log level settings to the values they had at startup, as determined by the startup options specified on the command-line, a configuration file, and the factory defaults.

Parameters:: server_id – Forward the request to a specific server.
Returns:: New logging levels.
Return type:: dict
Raises:: ServerLogLevelResetError – If the operation fails.

References

reset-the-server-log-levels

async log_settings()[source]

Get the structured log settings.

Returns:: Current structured log settings.
Return type:: dict
Raises:: ServerLogSettingError – If the operation fails.

References

get-the-structured-log-settings

async set_log_settings(**kwargs)[source]

Set the structured log settings.

This method takes arbitrary keyword arguments where the keys are the structured log parameters and the values are true or false, for either enabling or disabling the parameters.

db.set_log_settings(
    database=True,
    url=True,
    username=False,
)

Parameters:: kwargs (dict) – Structured log parameters to be set.
Returns:: New structured log settings.
Return type:: dict
Raises:: ServerLogSettingSetError – If the operation fails.

References

set-the-structured-log-settings

async api_calls()[source]

Get a list of the most recent requests with a timestamp and the endpoint.

Returns:: API calls made to the server.
Return type:: dict
Raises:: ServerApiCallsError – If the operation fails.

References

get-recent-api-calls

class arangoasync.database.StandardDatabase(connection)[source]

Standard database API wrapper.

Parameters:: connection (Connection) – Connection object to be used by the API executor.

async begin_transaction(read=None, write=None, exclusive=None, wait_for_sync=None, allow_implicit=None, lock_timeout=None, max_transaction_size=None, allow_dirty_read=None, skip_fast_lock_round=None)[source]

Begin a Stream Transaction.

Parameters:

read (str | list | None) – Name(s) of collections read during transaction. Read-only collections are added lazily but should be declared if possible to avoid deadlocks.
write (str | list | None) – Name(s) of collections written to during transaction with shared access.
exclusive (str | list | None) – Name(s) of collections written to during transaction with exclusive access.
wait_for_sync (bool | None) – If True, will force the transaction to write all data to disk before returning
allow_implicit (bool | None) – Allow reading from undeclared collections.
lock_timeout (int | None) – Timeout for waiting on collection locks. Setting it to 0 will prevent ArangoDB from timing out while waiting for a lock.
max_transaction_size (int | None) – Transaction size limit in bytes.
allow_dirty_read (bool | None) – If True, allows the Coordinator to ask any shard replica for the data, not only the shard leader. This may result in “dirty reads”. This setting decides about dirty reads for the entire transaction. Individual read operations, that are performed as part of the transaction, cannot override it.
skip_fast_lock_round (bool | None) – Whether to disable fast locking for write operations.

Returns:

Database API wrapper specifically tailored for: transactions.

Return type:

TransactionDatabase

Raises:

TransactionInitError – If the operation fails on the server side.

References

begin-a-stream-transaction

fetch_transaction(transaction_id)[source]

Fetch an existing transaction.

Parameters:

transaction_id (str) – Transaction ID.

Returns:

Database API wrapper specifically tailored for: transactions.

Return type:

TransactionDatabase

begin_async_execution(return_result=True)[source]

Begin async execution.

Parameters:: return_result (bool) – If set to True, API executions return instances of arangoasync.job.AsyncJob, which you can be used to retrieve results from server once available. Otherwise, API executions return None and no results are stored on server.
Returns:: Database API wrapper tailored for async execution.
Return type:: AsyncDatabase

async async_jobs(status, count=None)[source]

Return IDs of async jobs with given status.

Parameters:

status (str) – Job status (e.g. “pending”, “done”).
count (int | None) – Max number of job IDs to return.

Returns:

List of job IDs.

Return type:

See arangoasync.database.StandardDatabase.begin_transaction().

Raises:

AsyncJobListError – If retrieval fails.

References

list-async-jobs-by-status-or-get-the-status-of-specific-job

async clear_async_jobs(threshold=None)[source]

Clear async job results from the server.

Async jobs that are still queued or running are not stopped. Clients can use this method to perform an eventual garbage collection of job results.

Parameters:: threshold (float | None) – If specified, only the job results created prior to the threshold (a Unix timestamp) are deleted. Otherwise, all job results are deleted.
Raises:: AsyncJobClearError – If the operation fails.

References

delete-async-job-results

class arangoasync.database.TransactionDatabase(connection, transaction_id)[source]

Database API tailored specifically for Stream Transactions.

It allows you start a transaction, run multiple operations (eg. AQL queries) over a short period of time, and then commit or abort the transaction.

Parameters:

connection (Connection) – Connection object to be used by the API executor.
transaction_id (str) – Transaction ID.

property transaction_id: Transaction ID.

async transaction_status()[source]

Get the status of the transaction.

Returns:: Transaction status: one of “running”, “committed” or “aborted”.
Return type:: str
Raises:: TransactionStatusError – If the transaction is not found.

References

get-the-status-of-a-stream-transaction

async commit_transaction()[source]

Commit the transaction.

Raises:: TransactionCommitError – If the operation fails on the server side.

References

commit-a-stream-transaction

async abort_transaction()[source]

Abort the transaction.

Raises:: TransactionAbortError – If the operation fails on the server side.

References

abort-a-stream-transaction

class arangoasync.database.AsyncDatabase(connection, return_result)[source]

Database API wrapper tailored specifically for async execution.

See arangoasync.database.StandardDatabase.begin_async_execution().

Parameters:

connection (Connection) – HTTP connection.
return_result (bool) – If set to True, API executions return instances of arangoasync.job.AsyncJob, which you can use to retrieve results from server once available. If set to False, API executions return None and no results are stored on server.

References

jobs

class arangoasync.collection.Collection(executor, name, doc_serializer, doc_deserializer)[source]

Base class for collection API wrappers.

Parameters:

executor (ApiExecutor) – API executor.
name (str) – Collection name
doc_serializer (Serializer) – Document serializer.
doc_deserializer (Deserializer) – Document deserializer.

static get_col_name(doc)[source]

Extract the collection name from the document.

Parameters:: doc (str | dict) – Document ID or body with “_id” field.
Returns:: Collection name.
Return type:: str
Raises:: DocumentParseError – If document ID is missing.

property name

Return the name of the collection.

Returns:: Collection name.
Return type:: str

property context

Return the context of the collection.

Returns:: Context.
Return type:: str

property db_name

Return the name of the current database.

Returns:: Database name.
Return type:: str

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async indexes(with_stats=None, with_hidden=None)[source]

Fetch all index descriptions for the given collection.

Parameters:

with_stats (bool | None) – Whether to include figures and estimates in the result.
with_hidden (bool | None) – Whether to include hidden indexes in the result.

Returns:

List of index properties.

Return type:

Raises:

IndexListError – If retrieval fails.

References

list-all-indexes-of-a-collection

async get_index(id)[source]

Return the properties of an index.

Parameters:: id (str) – Index ID. Could be either the full ID or just the index number.
Returns:: Index properties.
Return type:: IndexProperties
Raises:: IndexGetError – If retrieval fails.

References

get-an-index

async add_index(type, fields, options=None)[source]

Create an index.

Parameters:

type (str) – Type attribute (ex. “persistent”, “inverted”, “ttl”, “mdi”, “geo”, “vector”).
fields (dict | list) – Fields to index.
options (dict | None) – Additional index options.

Returns:

New index properties.

Return type:

IndexProperties

Raises:

IndexCreateError – If index creation fails.

References

async delete_index(id, ignore_missing=False)[source]

Delete an index.

Parameters:

id (str) – Index ID. Could be either the full ID or just the index number.
ignore_missing (bool) – Do not raise an exception on missing index.

Returns:

True if the operation was successful. False if the index was not: found and ignore_missing was set to True.

Return type:

Raises:

IndexDeleteError – If deletion fails.

References

delete-an-index

async load_indexes()[source]

Cache this collection’s index entries in the main memory.

Returns:: True if the operation was successful.
Return type:: bool
Raises:: IndexLoadError – If loading fails.

References

load-collection-indexes-into-memory

async recalculate_count()[source]

Recalculate the document count.

Raises:: CollectionRecalculateCountError – If re-calculation fails.

References

recalculate-the-document-count-of-a-collection

async properties()[source]

Return the full properties of the current collection.

Returns:: Properties.
Return type:: CollectionProperties
Raises:: CollectionPropertiesError – If retrieval fails.

References

get-the-properties-of-a-collection

async configure(cache_enabled=None, computed_values=None, replication_factor=None, schema=None, wait_for_sync=None, write_concern=None)[source]

Changes the properties of a collection.

Only the provided attributes are updated.

Parameters:

cache_enabled (bool | None) – Whether the in-memory hash cache for documents should be enabled for this collection.
computed_values (list | None) – An optional list of objects, each representing a computed value.
replication_factor (int | None) – In a cluster, this attribute determines how many copies of each shard are kept on different DB-Servers. For SatelliteCollections, it needs to be the string “satellite”.
schema (dict | None) – The configuration of the collection-level schema validation for documents.
wait_for_sync (bool | None) – If set to True, the data is synchronized to disk before returning from a document create, update, replace or removal operation.
write_concern (int | None) – Determines how many copies of each shard are required to be in sync on the different DB-Servers.

Returns:

Properties.

Return type:

CollectionProperties

Raises:

CollectionConfigureError – If configuration fails.
ValueError – If parameters are invalid.

References

change-the-properties-of-a-collection

async rename(new_name)[source]

Rename the collection.

Renames may not be reflected immediately in async execution, batch execution or transactions. It is recommended to initialize new API wrappers after a rename.

Note

Renaming collections is not supported in cluster deployments.

Parameters:: new_name (str) – New collection name.
Raises:: CollectionRenameError – If rename fails.

References

rename-a-collection

async compact()[source]

Compact a collection.

Returns:: Collection information.
Return type:: CollectionInfo
Raises:: CollectionCompactError – If compaction fails.

References

compact-a-collection

async truncate(wait_for_sync=None, compact=None)[source]

Removes all documents, but leaves indexes intact.

Parameters:

wait_for_sync (bool | None) – If set to True, the data is synchronized to disk before returning from the truncate operation.
compact (bool | None) – If set to True, the storage engine is told to start a compaction in order to free up disk space. This can be resource intensive. If the only intention is to start over with an empty collection, specify False.

Raises:

CollectionTruncateError – If truncation fails.

References

truncate-a-collection

async count()[source]

Return the total document count.

Returns:: Total document count.
Return type:: int
Raises:: DocumentCountError – If retrieval fails.

References

get-the-document-count-of-a-collection

async statistics()[source]

Get additional statistical information about the collection.

Returns:: Collection statistics.
Return type:: CollectionStatistics
Raises:: CollectionStatisticsError – If retrieval fails.

References

get-the-collection-statistics

async responsible_shard(document)[source]

Return the ID of the shard responsible for given document.

If the document does not exist, return the shard that would be responsible.

Parameters:: document (dict) – Document body with “_key” field.
Returns:: Shard ID.
Return type:: str
Raises:: CollectionResponsibleShardError – If retrieval fails.

References

get-the-responsible-shard-for-a-document

async shards(details=None)[source]

Return collection shards and properties.

Available only in a cluster setup.

Parameters:: details (bool | None) – If set to True, include responsible servers for these shards.
Returns:: Collection shards.
Return type:: dict
Raises:: CollectionShardsError – If retrieval fails.

References

get-the-shard-ids-of-a-collection

async revision()[source]

Return collection revision.

Returns:: Collection revision.
Return type:: str
Raises:: CollectionRevisionError – If retrieval fails.

References

get-the-collection-revision-id

async checksum(with_rev=None, with_data=None)[source]

Calculate collection checksum.

Parameters:

with_rev (bool | None) – Include document revisions in checksum calculation.
with_data (bool | None) – Include document data in checksum calculation.

Returns:

Collection checksum.

Return type:

Raises:

CollectionChecksumError – If retrieval fails.

References

get-the-collection-checksum

async has(document, allow_dirty_read=False, if_match=None, if_none_match=None)[source]

Check if a document exists in the collection.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

True if the document exists, False otherwise.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.

References

get-a-document-header

async get_many(documents, allow_dirty_read=None, ignore_revs=None)[source]

Return multiple documents ignoring any missing ones.

Parameters:

documents (list) – List of document IDs, keys or bodies. A search document must contain at least a value for the _key field. A value for _rev may be specified to verify whether the document has the same revision value, unless ignoreRevs is set to false.
allow_dirty_read (bool | None) – Allow reads from followers in a cluster.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.

Returns:

List of documents. Missing ones are not included.

Return type:

Raises:

DocumentGetError – If retrieval fails.

References

get-multiple-documents

async find(filters=None, skip=None, limit=None, allow_dirty_read=False, sort=None)[source]

Return all documents that match the given filters.

Parameters:

filters (dict | None) – Query filters.
skip (int | None) – Number of documents to skip.
limit (int | str | None) – Maximum number of documents to return.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
sort (list | None) – Document sort parameters.

Returns:

Document cursor.

Return type:

Cursor

Raises:

DocumentGetError – If retrieval fails.
SortValidationError – If sort parameters are invalid.

async update_match(filters, body, limit=None, keep_none=None, wait_for_sync=None, merge_objects=None)[source]

Update matching documents.

Parameters:

filters (dict | None) – Query filters.
body (dict) – Full or partial document body with the updates.
limit (int | str | None) – Maximum number of documents to update.
keep_none (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
merge_objects (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.

Returns:

Number of documents that got updated.

Return type:

Raises:

DocumentUpdateError – If update fails.

async replace_match(filters, body, limit=None, wait_for_sync=None)[source]

Replace matching documents.

Parameters:

filters (dict | None) – Query filters.
body (dict) – New document body.
limit (int | str | None) – Maximum number of documents to replace.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.

Returns:

Number of documents that got replaced.

Return type:

Raises:

DocumentReplaceError – If replace fails.

async delete_match(filters, limit=None, wait_for_sync=None)[source]

Delete matching documents.

Parameters:

filters (dict | None) – Query filters.
limit (int | str | None) – Maximum number of documents to delete.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.

Returns:

Number of documents that got deleted.

Return type:

Raises:

DocumentDeleteError – If delete fails.

async insert_many(documents, wait_for_sync=None, return_new=None, return_old=None, silent=None, overwrite=None, overwrite_mode=None, keep_null=None, merge_objects=None, refill_index_caches=None, version_attribute=None)[source]

Insert multiple documents.

Note

If inserting a document fails, the exception is not raised but returned as an object in the “errors” list. It is up to you to inspect the list to determine which documents were inserted successfully (returns document metadata) and which were not (returns exception object).

Parameters:

documents (list) – Documents to insert. If an item contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until documents have been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result. Only available if the overwrite option is used.
silent (bool | None) – If set to True, an empty object is returned as response if all document operations succeed. No meta-data is returned for the created documents. If any of the operations raises an error, an array with the error object(s) is returned.
overwrite (bool | None) – If set to True, operation does not fail on duplicate key and existing document is overwritten (replace-insert).
overwrite_mode (str | None) – Overwrite mode. Supersedes overwrite option. May be one of “ignore”, “replace”, “update” or “conflict”.
keep_null (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely. Applies only when overwrite_mode is set to “update” (update-insert).
merge_objects (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one. Applies only when overwrite_mode is set to “update” (update-insert).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations. Only applicable if overwrite is set to True or overwrite_mode is set to “update” or “replace”.

Returns:

Documents metadata (e.g. document id, key, revision) and: errors or just errors if silent is set to True.

Return type:

Raises:

DocumentInsertError – If insertion fails.

References

create-multiple-documents

async replace_many(documents, wait_for_sync=None, ignore_revs=None, return_new=None, return_old=None, silent=None, refill_index_caches=None, version_attribute=None)[source]

Insert multiple documents.

Note

If replacing a document fails, the exception is not raised but returned as an object in the “errors” list. It is up to you to inspect the list to determine which documents were replaced successfully (returns document metadata) and which were not (returns exception object).

Parameters:

documents (list) – New documents to replace the old ones. An item must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until documents have been synced to disk.
ignore_revs (bool | None) – If this is set to False, then any _rev attribute given in a body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, an empty object is returned as response if all document operations succeed. No meta-data is returned for the created documents. If any of the operations raises an error, an array with the error object(s) is returned.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations.

Returns:

Documents metadata (e.g. document id, key, revision) and: errors or just errors if silent is set to True.

Return type:

Raises:

DocumentReplaceError – If replacing fails.

References

replace-multiple-documents

async update_many(documents, wait_for_sync=None, ignore_revs=None, return_new=None, return_old=None, silent=None, keep_null=None, merge_objects=None, refill_index_caches=None, version_attribute=None)[source]

Insert multiple documents.

Note

If updating a document fails, the exception is not raised but returned as an object in the “errors” list. It is up to you to inspect the list to determine which documents were updated successfully (returned as document metadata) and which were not (returned as exception object).

Parameters:

documents (list) – Documents to update. An item must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until documents have been synced to disk.
ignore_revs (bool | None) – If this is set to False, then any _rev attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, an empty object is returned as response if all document operations succeed. No meta-data is returned for the created documents. If any of the operations raises an error, an array with the error object(s) is returned.
keep_null (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely. Applies only when overwrite_mode is set to “update” (update-insert).
merge_objects (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one. Applies only when overwrite_mode is set to “update” (update-insert).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations.

Returns:

Documents metadata (e.g. document id, key, revision) and: errors or just errors if silent is set to True.

Return type:

Raises:

DocumentUpdateError – If update fails.

References

update-multiple-documents

async delete_many(documents, wait_for_sync=None, ignore_revs=None, return_old=None, silent=None, refill_index_caches=None)[source]

Delete multiple documents.

Note

If deleting a document fails, the exception is not raised but returned as an object in the “errors” list. It is up to you to inspect the list to determine which documents were deleted successfully (returned as document metadata) and which were not (returned as exception object).

Parameters:

documents (list) – Documents to delete. An item must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until documents have been synced to disk.
ignore_revs (bool | None) – If this is set to False, then any _rev attribute given in a body document is taken as a precondition. The document is only updated if the current revision is the one specified.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, an empty object is returned as response if all document operations succeed. No meta-data is returned for the created documents. If any of the operations raises an error, an array with the error object(s) is returned.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.

Returns:

Documents metadata (e.g. document id, key, revision) and: errors or just errors if silent is set to True.

Return type:

Raises:

DocumentRemoveError – If removal fails.

References

remove-multiple-documents

async import_bulk(documents, doc_type=None, complete=True, details=True, from_prefix=None, to_prefix=None, overwrite=None, overwrite_collection_prefix=None, on_duplicate=None, wait_for_sync=None, ignore_missing=None)[source]

Load JSON data in bulk into ArangoDB.

Parameters:

documents (bytes | str) – String representation of the JSON data to import.
doc_type (str | None) – Determines how the body of the request is interpreted. Possible values: “”, “documents”, “array”, “auto”.
complete (bool | None) – If set to True, the whole import fails if any error occurs. Otherwise, the import continues even if some documents are invalid and cannot be imported, skipping the problematic documents.
details (bool | None) – If set to True, the result includes a details attribute with information about documents that could not be imported.
from_prefix (str | None) – String prefix prepended to the value of “_from” field in each edge document inserted. For example, prefix “foo” prepended to “_from”: “bar” will result in “_from”: “foo/bar”. Applies only to edge collections.
to_prefix (str | None) – String prefix prepended to the value of “_to” field in each edge document inserted. For example, prefix “foo” prepended to “_to”: “bar” will result in “_to”: “foo/bar”. Applies only to edge collections.
overwrite (bool | None) – If set to True, all existing documents are removed prior to the import. Indexes are still preserved.
overwrite_collection_prefix (bool | None) – Force the fromPrefix and toPrefix, possibly replacing existing collection name prefixes.
on_duplicate (str | None) – Action to take on unique key constraint violations (for documents with “_key” fields). Allowed values are “error” (do not import the new documents and count them as errors), “update” (update the existing documents while preserving any fields missing in the new ones), “replace” (replace the existing documents with new ones), and “ignore” (do not import the new documents and count them as ignored, as opposed to counting them as errors). Options “update” and “replace” may fail on secondary unique key constraint violations.
wait_for_sync (bool | None) – Block until operation is synchronized to disk.
ignore_missing (bool | None) – When importing JSON arrays of tabular data (type parameter is omitted), the first line of the request body defines the attribute keys and the subsequent lines the attribute values for each document. Subsequent lines with a different number of elements than the first line are not imported by default. You can enable this option to import them anyway. For the missing elements, the document attributes are omitted. Excess elements are ignored.

Returns:

Result of the import operation.

Return type:

Raises:

DocumentInsertError – If import fails.

References

import-json-data-as-documents

class arangoasync.collection.EdgeCollection(executor, graph, name, doc_serializer, doc_deserializer)[source]

Edge collection API wrapper.

Parameters:

executor (ApiExecutor) – API executor.
name (str) – Collection name
graph (str) – Graph name.
doc_serializer (Serializer) – Document serializer.
doc_deserializer (Deserializer) – Document deserializer.

property graph

Return the graph name.

Returns:: Graph name.
Return type:: str

async get(edge, rev=None, if_match=None, if_none_match=None)[source]

Return an edge from the graph.

Parameters:

edge (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
rev (str | None) – If this is set a document is only returned if it has exactly this revision.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

Document or None if not found.

Return type:

dict | None

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.
DocumentParseError – If the document is malformed.

References

get-an-edge

async insert(edge, wait_for_sync=None, return_new=None)[source]

Insert a new edge document.

Parameters:

edge (dict) – Document to insert. It must contain “_from” and “_to” fields. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new is specified, the result contains the document metadata in the “edge” field and the new document in the “new” field.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

References

create-an-edge

async update(edge, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Update an edge in the graph.

Parameters:

edge (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field, along with “_from” and “_to” fields.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally update a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “edge” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentUpdateError – If update fails.

References

update-an-edge

async replace(edge, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Replace an edge in the graph.

Parameters:

edge (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field, along with “_from” and “_to” fields.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “edge” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentReplaceError – If replace fails.

References

replace-an-edge

async delete(edge, ignore_missing=False, wait_for_sync=None, return_old=None, if_match=None)[source]

Delete an edge from the graph.

Parameters:

edge (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field, along with “_from” and “_to” fields.
ignore_missing (bool) – Do not raise an exception on missing document.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

True if vertex was deleted successfully, False if vertex: was not found and ignore_missing was set to True (does not apply in transactions). Old document is returned if return_old is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentDeleteError – If deletion fails.

References

remove-an-edge

async edges(vertex, direction=None, allow_dirty_read=None)[source]

Return the edges starting or ending at the specified vertex.

Parameters:

vertex (str | dict) – Document ID, key or body.
direction (str | None) – Direction of the edges to return. Selects in or out direction for edges. If not set, any edges are returned.
allow_dirty_read (bool | None) – Allow reads from followers in a cluster.

Returns:

List of edges and statistics.

Return type:

Raises:

EdgeListError – If retrieval fails.

References

get-inbound-and-outbound-edges

async link(from_vertex, to_vertex, data=None, wait_for_sync=None, return_new=False)[source]

Insert a new edge document linking the given vertices.

Parameters:

from_vertex (str | dict) – “_from” vertex document ID or body with “_id” field.
to_vertex (str | dict) – “_to” vertex document ID or body with “_id” field.
data (dict | None) – Any extra data for the new edge document. If it has “_key” or “_id” field, its value is used as key of the new edge document (otherwise it is auto-generated).
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_new – Optional[bool]: Additionally return the complete new document under the attribute new in the result.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new is specified, the result contains the document metadata in the “edge” field and the new document in the “new” field.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

class arangoasync.collection.StandardCollection(executor, name, doc_serializer, doc_deserializer)[source]

Standard collection API wrapper.

Parameters:

executor (ApiExecutor) – API executor.
name (str) – Collection name
doc_serializer (Serializer) – Document serializer.
doc_deserializer (Deserializer) – Document deserializer.

async get(document, allow_dirty_read=False, if_match=None, if_none_match=None)[source]

Return a document.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

Document or None if not found.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.
DocumentParseError – If the document is malformed.

References

get-a-document

async insert(document, wait_for_sync=None, return_new=None, return_old=None, silent=None, overwrite=None, overwrite_mode=None, keep_null=None, merge_objects=None, refill_index_caches=None, version_attribute=None)[source]

Insert a new document.

Parameters:

document (dict) – Document to insert. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result. Only available if the overwrite option is used.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
overwrite (bool | None) – If set to True, operation does not fail on duplicate key and existing document is overwritten (replace-insert).
overwrite_mode (str | None) – Overwrite mode. Supersedes overwrite option. May be one of “ignore”, “replace”, “update” or “conflict”.
keep_null (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely. Applies only when overwrite_mode is set to “update” (update-insert).
merge_objects (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one. Applies only when overwrite_mode is set to “update” (update-insert).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations. Only applicable if overwrite is set to True or overwrite_mode is set to “update” or “replace”.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

References

create-a-document

async update(document, ignore_revs=None, wait_for_sync=None, return_new=None, return_old=None, silent=None, keep_null=None, merge_objects=None, refill_index_caches=None, version_attribute=None, if_match=None)[source]

Update a document.

Parameters:

document (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only updated if the current revision is the one specified.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
merge_objects (bool | None) – Controls whether objects (not arrays) are merged if present in both the existing and the patch document. If set to False, the value in the patch document overwrites the existing document’s value. If set to True, objects are merged.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations.
if_match (str | None) – You can conditionally update a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentUpdateError – If update fails.

References

update-a-document

async replace(document, ignore_revs=None, wait_for_sync=None, return_new=None, return_old=None, silent=None, refill_index_caches=None, version_attribute=None, if_match=None)[source]

Replace a document.

Parameters:

document (dict) – New document. It must contain the “_key” or “_id” field. Edge document must also have “_from” and “_to” fields.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.
version_attribute (str | None) – Support for simple external versioning to document operations.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentReplaceError – If replace fails.

References

replace-a-document

async delete(document, ignore_revs=None, ignore_missing=False, wait_for_sync=None, return_old=None, silent=None, refill_index_caches=None, if_match=None)[source]

Delete a document.

Parameters:

document (str | dict) – Document ID, key or body. The body must contain the “_key” or “_id” field.
ignore_revs (bool | None) – If set to True, the _rev attribute in the document is ignored. If this is set to False, then the _rev attribute given in the body document is taken as a precondition. The document is only replaced if the current revision is the one specified.
ignore_missing (bool) – Do not raise an exception on missing document. This parameter has no effect in transactions where an exception is always raised on failures.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
silent (bool | None) – If set to True, no document metadata is returned. This can be used to save resources.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document updates affect the edge index or cache-enabled persistent indexes.
if_match (bool | None) – You can conditionally remove a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision) or True: if silent is set to True and the document was found.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentDeleteError – If deletion fails.

References

remove-a-document

class arangoasync.collection.VertexCollection(executor, graph, name, doc_serializer, doc_deserializer)[source]

Vertex collection API wrapper.

Parameters:

executor (ApiExecutor) – API executor.
name (str) – Collection name
graph (str) – Graph name.
doc_serializer (Serializer) – Document serializer.
doc_deserializer (Deserializer) – Document deserializer.

property graph

Return the graph name.

Returns:: Graph name.
Return type:: str

async get(vertex, rev=None, if_match=None, if_none_match=None)[source]

Return a vertex from the graph.

Parameters:

vertex (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
rev (str | None) – If this is set a document is only returned if it has exactly this revision.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

Document or None if not found.

Return type:

dict | None

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.
DocumentParseError – If the document is malformed.

References

get-a-vertex

async insert(vertex, wait_for_sync=None, return_new=None)[source]

Insert a new vertex document.

Parameters:

vertex (dict) – Document to insert. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new is specified, the result contains the document metadata in the “vertex” field and the new document in the “new” field.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

References

create-a-vertex

async update(vertex, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Update a vertex in the graph.

Parameters:

vertex (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally update a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “vertex” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentUpdateError – If update fails.

References

update-a-vertex

async replace(vertex, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Replace a vertex in the graph.

Parameters:

vertex (dict) – New document. It must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “vertex” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentReplaceError – If replace fails.

References

replace-a-vertex

async delete(vertex, ignore_missing=False, wait_for_sync=None, return_old=None, if_match=None)[source]

Delete a vertex from the graph.

Parameters:

vertex (dict) – Document ID, key or body. The body must contain the “_key” or “_id” field.
ignore_missing (bool) – Do not raise an exception on missing document.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

True if vertex was deleted successfully, False if vertex: was not found and ignore_missing was set to True (does not apply in transactions). Old document is returned if return_old is set to True.

Return type:

QueryTrackingConfiguration

Raises:

DocumentRevisionError – If precondition was violated.
DocumentDeleteError – If deletion fails.

References

remove-a-vertex

class arangoasync.aql.AQL(executor)[source]

AQL (ArangoDB Query Language) API wrapper.

Allows you to execute, track, kill, explain, and validate queries written in ArangoDB’s query language.

Parameters:: executor – API executor. Required to execute the API requests.

property name: Return the name of the current database.

property context: Return the current API execution context.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

property cache: Return the AQL Query Cache API wrapper.

async execute(query, count=None, batch_size=None, bind_vars=None, cache=None, memory_limit=None, ttl=None, allow_dirty_read=None, options=None)[source]

Execute the query and return the result cursor.

Parameters:

query (str) – Query string to be executed.
count (bool | None) – If set to True, the total document count is calculated and included in the result cursor.
batch_size (int | None) – Maximum number of result documents to be transferred from the server to the client in one roundtrip.
bind_vars (dict | None) – An object with key/value pairs representing the bind parameters.
cache (bool | None) – Flag to determine whether the AQL query results cache shall be used.
memory_limit (int | None) – Maximum memory (in bytes) that the query is allowed to use.
ttl (int | None) – The time-to-live for the cursor (in seconds). The cursor will be removed on the server automatically after the specified amount of time.
allow_dirty_read (bool | None) – Allow reads from followers in a cluster.
options (QueryProperties | dict | None) – Extra options for the query.

Returns:

Result cursor.

Return type:

Cursor

References

create-a-cursor

async tracking()[source]

Returns the current query tracking configuration.

Returns:: Returns the current query tracking configuration.
Return type:: QueryTrackingConfiguration
Raises:: AQLQueryTrackingGetError – If retrieval fails.

References

get-the-aql-query-tracking-configuration

async set_tracking(enabled=None, max_slow_queries=None, slow_query_threshold=None, slow_streaming_query_threshold=None, max_query_string_length=None, track_bind_vars=None, track_slow_queries=None)[source]

Configure AQL query tracking properties.

Parameters:

enabled (bool | None) – If set to True, then queries will be tracked. If set to False, neither queries nor slow queries will be tracked.
max_slow_queries (int | None) – Maximum number of slow queries to track. Oldest entries are discarded first.
slow_query_threshold (int | None) – Runtime threshold (in seconds) for treating a query as slow.
slow_streaming_query_threshold (int | None) – Runtime threshold (in seconds) for treating a streaming query as slow.
max_query_string_length (int | None) – The maximum query string length (in bytes) to keep in the list of queries.
track_bind_vars (bool | None) – If set to True, track bind variables used in queries.
track_slow_queries (int | None) – If set to True, then slow queries will be tracked in the list of slow queries if their runtime exceeds the value set in slowQueryThreshold.

Returns:

Returns the updated query tracking configuration.

Return type:

Raises:

AQLQueryTrackingSetError – If setting the configuration fails.

References

update-the-aql-query-tracking-configuration

async history()[source]

Return recently executed AQL queries (admin only).

Returns:: AQL query history.
Return type:: dict
Raises:: AQLQueryHistoryError – If retrieval fails.

async queries(all_queries=False)[source]

Return a list of currently running queries.

Parameters:: all_queries (bool) – If set to True, will return the currently running queries in all databases, not just the selected one. Using the parameter is only allowed in the _system database and with superuser privileges.
Returns:: List of currently running queries and their properties.
Return type:: list
Raises:: AQLQueryListError – If retrieval fails.

References

list-the-running-queries

async slow_queries(all_queries=False)[source]

Returns a list containing the last AQL queries that are finished and have exceeded the slow query threshold in the selected database.

Parameters:: all_queries (bool) – If set to True, will return the slow queries in all databases, not just the selected one. Using the parameter is only allowed in the _system database and with superuser privileges.
Returns:: List of slow queries.
Return type:: list
Raises:: AQLQueryListError – If retrieval fails.

References

list-the-slow-aql-queries

async clear_slow_queries(all_queries=False)[source]

Clears the list of slow queries.

Parameters:: all_queries (bool) – If set to True, will clear the slow queries in all databases, not just the selected one. Using the parameter is only allowed in the _system database and with superuser privileges.
Returns:: Empty dictionary.
Return type:: dict
Raises:: AQLQueryClearError – If retrieval fails.

References

clear-the-list-of-slow-aql-queries

async kill(query_id, ignore_missing=False, all_queries=False)[source]

Kill a running query.

Parameters:

query_id (str) – Thea ID of the query to kill.
ignore_missing (bool) – If set to True, will not raise an exception if the query is not found.
all_queries (bool) – If set to True, will kill the query in all databases, not just the selected one. Using the parameter is only allowed in the _system database and with superuser privileges.

Returns:

True if the query was killed successfully.

Return type:

Raises:

AQLQueryKillError – If killing the query fails.

References

kill-a-running-aql-query

async explain(query, bind_vars=None, options=None)[source]

Inspect the query and return its metadata without executing it.

Parameters:

query (str) – Query string to be explained.
bind_vars (dict | None) – An object with key/value pairs representing the bind parameters.
options (QueryExplainOptions | dict | None) – Extra options for the query.

Returns:

Query execution plan.

Return type:

Raises:

AQLQueryExplainError – If retrieval fails.

References

explain-an-aql-query

async validate(query)[source]

Parse and validate the query without executing it.

Parameters:: query (str) – Query string to be validated.
Returns:: Query information.
Return type:: dict
Raises:: AQLQueryValidateError – If validation fails.

References

parse-an-aql-query

async query_rules()[source]

A list of all optimizer rules and their properties.

Returns:: Available optimizer rules.
Return type:: list
Raises:: AQLQueryRulesGetError – If retrieval fails.

References

list-all-aql-optimizer-rules

async functions(namespace=None)[source]

List the registered used-defined AQL functions.

Warning

AQL User Functions are no longer available in ArangoDB 4.0.

Parameters:: namespace (str | None) – Returns all registered AQL user functions from the specified namespace.
Returns:: List of the AQL functions defined in the database.
Return type:: list
Raises:: AQLFunctionListError – If retrieval fails.

References

list-the-registered-user-defined-aql-functions

async create_function(name, code, is_deterministic=None)[source]

Registers a user-defined AQL function (UDF) written in JavaScript.

Warning

AQL User Functions are no longer available in ArangoDB 4.0.

Parameters:

name (str) – Name of the function.
code (str) – JavaScript code of the function.
is_deterministic (bool | None) – If set to True, the function is deterministic.

Returns:

Information about the registered function.

Return type:

Raises:

AQLFunctionCreateError – If registration fails.

References

create-a-user-defined-aql-function

async delete_function(name, group=None, ignore_missing=False)[source]

Remove a user-defined AQL function.

Warning

AQL User Functions are no longer available in ArangoDB 4.0.

Parameters:

name (str) – Name of the function.
group (bool | None) – If set to True, the function name is treated as a namespace prefix.
ignore_missing (bool) – If set to True, will not raise an exception if the function is not found.

Returns:

Information about the removed functions (their count).

Return type:

Raises:

AQLFunctionDeleteError – If removal fails.

References

remove-a-user-defined-aql-function

class arangoasync.aql.AQLQueryCache(executor)[source]

AQL Query Cache API wrapper.

Parameters:: executor – API executor. Required to execute the API requests.

property name: Return the name of the current database.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async entries()[source]

Return a list of all AQL query results cache entries.

Returns:: List of AQL query results cache entries.
Return type:: list
Raises:: AQLCacheEntriesError – If retrieval fails.

References

list-the-entries-of-the-aql-query-results-cache

async plan_entries()[source]

Return a list of all AQL query plan cache entries.

Returns:: List of AQL query plan cache entries.
Return type:: list
Raises:: AQLCacheEntriesError – If retrieval fails.

References

list-the-entries-of-the-aql-query-plan-cache

async clear()[source]

Clear the AQL query results cache.

Raises:: AQLCacheClearError – If clearing the cache fails.

References

clear-the-aql-query-results-cache

async clear_plan()[source]

Clear the AQL query plan cache.

Raises:: AQLCacheClearError – If clearing the cache fails.

References

clear-the-aql-query-plan-cache

async properties()[source]

Return the current AQL query results cache configuration.

Returns:: Current AQL query cache properties.
Return type:: QueryCacheProperties
Raises:: AQLCachePropertiesError – If retrieval fails.

References

get-the-aql-query-results-cache-configuration

async configure(mode=None, max_results=None, max_results_size=None, max_entry_size=None, include_system=None)[source]

Configure the AQL query results cache.

Parameters:

mode (str | None) – Cache mode. Allowed values are “off”, “on”, and “demand”.
max_results (int | None) – Max number of query results stored per database-specific cache.
max_results_size (int | None) – Max cumulative size of query results stored per database-specific cache.
max_entry_size (int | None) – Max entry size of each query result stored per database-specific cache.
include_system (bool | None) – Store results of queries in system collections.

Returns:

Updated AQL query cache properties.

Return type:

QueryCacheProperties

Raises:

AQLCacheConfigureError – If setting the configuration fails.

References

set-the-aql-query-results-cache-configuration

class arangoasync.graph.Graph(executor, name, doc_serializer, doc_deserializer)[source]

Graph API wrapper, representing a graph in ArangoDB.

Parameters:

executor (APIExecutor) – Required to execute the API requests.
name (str) – Graph name.
doc_serializer (Serializer) – Document serializer.
doc_deserializer (Deserializer) – Document deserializer.

property name: Name of the graph.

property db_name

Return the name of the current database.

Returns:: Database name.
Return type:: str

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async properties()[source]

Get the properties of the graph.

Returns:: Properties of the graph.
Return type:: GraphProperties
Raises:: GraphProperties – If the operation fails.

References

get-a-graph

vertex_collection(name)[source]

Returns the vertex collection API wrapper.

Parameters:: name (str) – Vertex collection name.
Returns:: Vertex collection API wrapper.
Return type:: VertexCollection

async vertex_collections()[source]

Get the names of all vertex collections in the graph.

Returns:: List of vertex collection names.
Return type:: list
Raises:: VertexCollectionListError – If the operation fails.

References

list-vertex-collections

async has_vertex_collection(name)[source]

Check if the graph has the given vertex collection.

Parameters:: name (str) – Vertex collection mame.
Returns:: True if the graph has the vertex collection, False otherwise.
Return type:: bool
Raises:: VertexCollectionListError – If the operation fails.

async create_vertex_collection(name, options=None)[source]

Create a vertex collection in the graph.

Parameters:

name (str) – Vertex collection name.
options (dict | VertexCollectionOptions | None) – Extra options for creating vertex collections.

Returns:

Vertex collection API wrapper.

Return type:

VertexCollection

Raises:

VertexCollectionCreateError – If the operation fails.

References

add-a-vertex-collection

async delete_vertex_collection(name, purge=False)[source]

Remove a vertex collection from the graph.

Parameters:

name (str) – Vertex collection name.
purge (bool) – If set to True, the vertex collection is not just deleted from the graph but also from the database completely. Note that you cannot remove vertex collections that are used in one of the edge definitions of the graph.

Raises:

VertexCollectionDeleteError – If the operation fails.

References

remove-a-vertex-collection

async has_vertex(vertex, allow_dirty_read=False, if_match=None, if_none_match=None)[source]

Check if the vertex exists in the graph.

Parameters:

vertex (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

True if the document exists, False otherwise.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.

async vertex(vertex, if_match=None, if_none_match=None)[source]

Return a vertex document.

Parameters:

vertex (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

Document or None if not found.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.
DocumentParseError – If the document is malformed.

References

get-a-vertex

async insert_vertex(collection, vertex, wait_for_sync=None, return_new=None)[source]

Insert a new vertex document.

Parameters:

collection (str) – Name of the vertex collection to insert the document into.
vertex (dict) – Document to insert. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new is specified, the result contains the document metadata in the “vertex” field and the new document in the “new” field.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

References

create-a-vertex

async update_vertex(vertex, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Update a vertex in the graph.

Parameters:

vertex (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally update a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “vertex” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentUpdateError – If update fails.

References

update-a-vertex

async replace_vertex(vertex, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Replace a vertex in the graph.

Parameters:

vertex (dict) – New document. It must contain the “_key” or “_id” field.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “vertex” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentReplaceError – If replace fails.

References

replace-a-vertex

async delete_vertex(vertex, ignore_missing=False, wait_for_sync=None, return_old=None, if_match=None)[source]

Delete a vertex in the graph.

Parameters:

vertex (dict) – Document ID, key or body. The body must contain the “_key” or “_id” field.
ignore_missing (bool) – Do not raise an exception on missing document.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

True if vertex was deleted successfully, False if vertex: was not found and ignore_missing was set to True (does not apply in transactions). Old document is returned if return_old is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentDeleteError – If deletion fails.

References

remove-a-vertex

edge_collection(name)[source]

Returns the edge collection API wrapper.

Parameters:: name (str) – Edge collection name.
Returns:: Edge collection API wrapper.
Return type:: EdgeCollection

async edge_definitions()[source]

Return the edge definitions from the graph.

Returns:: List of edge definitions.
Return type:: list
Raises:: EdgeDefinitionListError – If the operation fails.

async has_edge_definition(name)[source]

Check if the graph has the given edge definition.

Returns:: True if the graph has the edge definitions, False otherwise.
Return type:: bool
Raises:: EdgeDefinitionListError – If the operation fails.

async edge_collections()[source]

Get the names of all edge collections in the graph.

Returns:: List of edge collection names.
Return type:: list
Raises:: EdgeCollectionListError – If the operation fails.

References

list-edge-collections

async create_edge_definition(edge_collection, from_vertex_collections, to_vertex_collections, options=None)[source]

Create an edge definition in the graph.

This edge definition has to contain a collection and an array of each from and to vertex collections.

{
    "edge_collection": "edge_collection_name",
    "from_vertex_collections": ["from_vertex_collection_name"],
    "to_vertex_collections": ["to_vertex_collection_name"]
}

Parameters:

edge_collection (str) – Edge collection name.
from_vertex_collections (list) – List of vertex collections that can be used as the “from” vertex in edges.
to_vertex_collections (list) – List of vertex collections that can be used as the “to” vertex in edges.
options (dict | EdgeDefinitionOptions | None) – Extra options for creating edge definitions.

Returns:

Edge collection API wrapper.

Return type:

EdgeCollection

Raises:

EdgeDefinitionCreateError – If the operation fails.

References

add-an-edge-definition

async replace_edge_definition(edge_collection, from_vertex_collections, to_vertex_collections, options=None, wait_for_sync=None, drop_collections=None)[source]

Replace an edge definition.

Parameters:

edge_collection (str) – Edge collection name.
from_vertex_collections (list) – Names of “from” vertex collections.
to_vertex_collections (list) – Names of “to” vertex collections.
options (dict | EdgeDefinitionOptions | None) – Extra options for modifying collections withing this edge definition.
wait_for_sync (bool | None) – If set to True, the operation waits for data to be synced to disk before returning.
drop_collections (bool | None) – Drop the edge collection in addition to removing it from the graph. The collection is only dropped if it is not used in other graphs.

Returns:

API wrapper.

Return type:

EdgeCollection

Raises:

EdgeDefinitionReplaceError – If the operation fails.

References

replace-an-edge-definition

async delete_edge_definition(name, drop_collections=None, wait_for_sync=None)[source]

Delete an edge definition from the graph.

Parameters:

name (str) – Edge collection name.
drop_collections (bool | None) – If set to True, the edge definition is not just removed from the graph but the edge collection is also deleted completely from the database.
wait_for_sync (bool | None) – If set to True, the operation waits for changes to be synced to disk before returning.

Raises:

EdgeDefinitionDeleteError – If the operation fails.

References

remove-an-edge-definition

async has_edge(edge, allow_dirty_read=False, if_match=None, if_none_match=None)[source]

Check if the edge exists in the graph.

Parameters:

edge (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
allow_dirty_read (bool) – Allow reads from followers in a cluster.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

True if the document exists, False otherwise.

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.

async edge(edge, rev=None, if_match=None, if_none_match=None)[source]

Return an edge from the graph.

Parameters:

edge (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
rev (str | None) – If this is set a document is only returned if it has exactly this revision.
if_match (str | None) – The document is returned, if it has the same revision as the given ETag.
if_none_match (str | None) – The document is returned, if it has a different revision than the given ETag.

Returns:

Document or None if not found.

Return type:

dict | None

Raises:

DocumentRevisionError – If the revision is incorrect.
DocumentGetError – If retrieval fails.
DocumentParseError – If the document is malformed.

References

get-an-edge

async insert_edge(collection, edge, wait_for_sync=None, return_new=None)[source]

Insert a new edge document.

Parameters:

collection (str) – Name of the vertex collection to insert the document into.
edge (dict) – Document to insert. It must contain “_from” and “_to” fields. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new is specified, the result contains the document metadata in the “edge” field and the new document in the “new” field.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

References

create-an-edge

async update_edge(edge, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Update a vertex in the graph.

Parameters:

edge (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field, along with “_from” and “_to” fields.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally update a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “edge” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentUpdateError – If update fails.

References

update-an-edge

async replace_edge(edge, wait_for_sync=None, keep_null=None, return_new=None, return_old=None, if_match=None)[source]

Replace an edge in the graph.

Parameters:

edge (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field, along with “_from” and “_to” fields.
wait_for_sync (bool | None) – Wait until document has been synced to disk.
keep_null (bool | None) – If the intention is to delete existing attributes with the patch command, set this parameter to False.
return_new (bool | None) – Additionally return the complete new document under the attribute new in the result.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new or “return_old” are specified, the result contains the document metadata in the “edge” field and two additional fields (“new” and “old”).

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentReplaceError – If replace fails.

References

replace-an-edge

async delete_edge(edge, ignore_missing=False, wait_for_sync=None, return_old=None, if_match=None)[source]

Delete an edge from the graph.

Parameters:

edge (dict) – Partial or full document with the updated values. It must contain the “_key” or “_id” field, along with “_from” and “_to” fields.
ignore_missing (bool) – Do not raise an exception on missing document.
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_old (bool | None) – Additionally return the complete old document under the attribute old in the result.
if_match (str | None) – You can conditionally replace a document based on a target revision id by using the “if-match” HTTP header.

Returns:

True if vertex was deleted successfully, False if vertex: was not found and ignore_missing was set to True (does not apply in transactions). Old document is returned if return_old is set to True.

Return type:

Raises:

DocumentRevisionError – If precondition was violated.
DocumentDeleteError – If deletion fails.

References

remove-an-edge

async edges(collection, vertex, direction=None, allow_dirty_read=None)[source]

Return the edges starting or ending at the specified vertex.

Parameters:

collection (str) – Name of the edge collection to return edges from.
vertex (str | dict) – Document ID, key or body.
direction (str | None) – Direction of the edges to return. Selects in or out direction for edges. If not set, any edges are returned.
allow_dirty_read (bool | None) – Allow reads from followers in a cluster.

Returns:

List of edges and statistics.

Return type:

Raises:

EdgeListError – If retrieval fails.

References

get-inbound-and-outbound-edges

async link(collection, from_vertex, to_vertex, data=None, wait_for_sync=None, return_new=False)[source]

Insert a new edge document linking the given vertices.

Parameters:

collection (str) – Name of the collection to insert the edge into.
from_vertex (str | dict) – “_from” vertex document ID or body with “_id” field.
to_vertex (str | dict) – “_to” vertex document ID or body with “_id” field.
data (dict | None) – Any extra data for the new edge document. If it has “_key” or “_id” field, its value is used as key of the new edge document (otherwise it is auto-generated).
wait_for_sync (bool | None) – Wait until operation has been synced to disk.
return_new – Optional[bool]: Additionally return the complete new document under the attribute new in the result.

Returns:

Document metadata (e.g. document id, key, revision).: If return_new is specified, the result contains the document metadata in the “edge” field and the new document in the “new” field.

Return type:

Raises:

DocumentInsertError – If insertion fails.
DocumentParseError – If the document is malformed.

class arangoasync.job.AsyncJob(conn, job_id, response_handler)[source]

Job for tracking and retrieving result of an async API execution.

Parameters:

conn – HTTP connection.
job_id – Async job ID.
response_handler – HTTP response handler

References

jobs

property id

Return the async job ID.

Returns:: Async job ID.
Return type:: str

async status()[source]

Return the async job status from server.

Once a job result is retrieved via func:arangoasync.job.AsyncJob.result method, it is deleted from server and subsequent status queries will fail.

Returns:

Async job status. Possible values are “pending” (job is still in queue), “done” (job finished or raised an error).

Return type:

Raises:

ArangoError – If there is a problem with the request.
AsyncJobStatusError – If retrieval fails or the job is not found.

References

list-async-jobs-by-status-or-get-the-status-of-specific-job

async result()[source]

Fetch the async job result from server.

If the job raised an exception, it is propagated up at this point.

Once job result is retrieved, it is deleted from server and subsequent queries for result will fail.

Returns:

Async job result.

Raises:

ArangoError – If the job raised an exception or there was a problem with the request.
AsyncJobResultError – If retrieval fails, because job no longer exists or is still pending.

References

get-the-results-of-an-async-job

async cancel(ignore_missing=False)[source]

Cancel the async job.

An async job cannot be cancelled once it is taken out of the queue.

Note

It still might take some time to actually cancel the running async job.

Parameters:

ignore_missing – Do not raise an exception if the job is not found.

Returns:

True if job was cancelled successfully, False if the job was not found but ignore_missing was set to True.

Raises:

ArangoError – If there was a problem with the request.
AsyncJobCancelError – If cancellation fails.

References

cancel-an-async-job

async clear(ignore_missing=False)[source]

Delete the job result from the server.

Parameters:

ignore_missing – Do not raise an exception if the job is not found.

Returns:

True if result was deleted successfully, False if the job was not found but ignore_missing was set to True.

Raises:

ArangoError – If there was a problem with the request.
AsyncJobClearError – If deletion fails.

References

delete-async-job-results

async wait(seconds=None)[source]

Wait for the async job to finish.

Parameters:: seconds – Number of seconds to wait between status checks. If not provided, the method will wait indefinitely.
Returns:: True if the job is done, False if the job is still pending.

class arangoasync.cursor.Cursor(executor, data)[source]

Cursor API wrapper.

Cursors fetch query results from ArangoDB server in batches. Cursor objects are stateful as they store the fetched items in-memory. They must not be shared across threads without a proper locking mechanism.

Parameters:

executor – Required to execute the API requests.
data – Cursor initialization data. Returned by the server when the query is created.

property cached: Whether the result was served from the query cache or not.

property count: The total number of result documents available.

property extra: Extra information about the query execution.

property has_more: Whether there are more results available on the server.

property id: Cursor ID.

property next_batch_id: ID of the batch after current one.

property batch: Return the current batch of results.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

property statistics: Query statistics.

property profile: Query profiling information.

property plan: Execution plan for the query.

property warnings: Warnings generated during query execution.

empty()[source]: Check if the current batch is empty.

async next()[source]

Retrieve and pop the next item.

If current batch is empty/depleted, an API request is automatically sent to fetch the next batch from the server and update the cursor.

Returns:

Next item.

Return type:

Any

Raises:

StopAsyncIteration – If there are no more items to retrieve.
CursorNextError – If the cursor failed to fetch the next batch.
CursorStateError – If the cursor ID is not set.

pop()[source]

Pop the next item from the current batch.

If current batch is empty/depleted, an exception is raised. You must call arangoasync.cursor.Cursor.fetch() to manually fetch the next batch from server.

Returns:: Next item from the current batch.
Return type:: Any
Raises:: CursorEmptyError – If the current batch is empty.

async fetch(batch_id=None)[source]

Fetch the next batch from the server and update the cursor.

Parameters:

batch_id (str | None) – ID of the batch to fetch. If not set, the next batch after the current one is fetched.

Returns:

New batch results.

Return type:

List[Any]

Raises:

CursorNextError – If the cursor is empty.
CursorStateError – If the cursor ID is not set.

References

async close(ignore_missing=False)[source]

Close the cursor and free any server resources associated with it.

Parameters:

ignore_missing (bool) – Do not raise an exception on missing cursor.

Returns:

True if the cursor was closed successfully. False if there: was no cursor to close. If there is no cursor associated with the query, False is returned.

Return type:

Raises:

CursorCloseError – If the cursor failed to close.

References

delete-a-cursor

class arangoasync.backup.Backup(executor)[source]

Backup API wrapper.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async get(backup_id=None)[source]

Return backup details.

Parameters:: backup_id (str | None) – If set, the returned list is restricted to the backup with the given id.
Returns:: Backup details.
Return type:: dict
Raises:: BackupGetError – If the operation fails.

References

list-backups

async create(label=None, allow_inconsistent=None, force=None, timeout=None)[source]

Create a backup when the global write lock can be obtained.

Parameters:

label (str | None) – Label for this backup. If not specified, a UUID is used.
allow_inconsistent (bool | None) – Allow inconsistent backup when the global transaction lock cannot be acquired before timeout.
force (bool | None) – Forcefully abort all running transactions to ensure a consistent backup when the global transaction lock cannot be acquired before timeout. Default (and highly recommended) value is False.
timeout (float | None) – The time in seconds that the operation tries to get a consistent snapshot.

Returns:

Backup information.

Return type:

Raises:

BackupCreateError – If the backup creation fails.

References

create-backup

async restore(backup_id)[source]

Restore a local backup.

Parameters:: backup_id (str) – Backup ID.
Returns:: Result of the restore operation.
Return type:: dict
Raises:: BackupRestoreError – If the restore operation fails.

References

restore-backup

async delete(backup_id)[source]

Delete a backup.

Parameters:: backup_id (str) – Backup ID.
Raises:: BackupDeleteError – If the delete operation fails.

References

delete-backup

async upload(backup_id=None, repository=None, abort=None, config=None, upload_id=None)[source]

Manage backup uploads.

Parameters:

backup_id (str | None) – Backup ID used for scheduling an upload. Mutually exclusive with parameter upload_id.
repository (str | None) – Remote repository URL(e.g. “local://tmp/backups”).
abort (str | None) – If set to True, running upload is aborted. Used with parameter upload_id.
config (dict | None) – Remote repository configuration. Required for scheduling an upload and mutually exclusive with parameter upload_id.
upload_id (str | None) – Upload ID. Mutually exclusive with parameters backup_id, repository, and config.

Returns:

Upload details.

Return type:

Raises:

BackupUploadError – If upload operation fails.

References

upload-a-backup-to-a-remote-repository

async download(backup_id=None, repository=None, abort=None, config=None, download_id=None)[source]

Manage backup downloads.

Parameters:

backup_id (str | None) – Backup ID used for scheduling a download. Mutually exclusive with parameter download_id.
repository (str | None) – Remote repository URL (e.g. “local://tmp/backups”).
abort (bool | None) – If set to True, running download is aborted.
config (dict | None) – Remote repository configuration. Required for scheduling a download and mutually exclusive with parameter download_id.
download_id (str | None) – Download ID. Mutually exclusive with parameters backup_id, repository, and config.

Returns:

Download details.

Return type:

Raises:

BackupDownloadError – If the download operation fails.

References

download-a-backup-from-a-remote-repository

class arangoasync.foxx.Foxx(executor)[source]

Foxx API wrapper.

Warning

Foxx microservice features are no longer available in ArangoDB 4.0.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async services(exclude_system=False)[source]

List installed services.

Parameters:: exclude_system (bool | None) – Exclude system services.
Returns:: List of installed services.
Return type:: list
Raises:: FoxxServiceListError – If retrieval fails.

References

list-the-installed-services

async service(mount)[source]

Return service metadata.

Parameters:: mount (str) – Service mount path (e.g “/_admin/aardvark”).
Returns:: Service metadata.
Return type:: dict
Raises:: FoxxServiceGetError – If retrieval fails.

References

get-the-service-description

async create_service(mount, service, headers=None, development=None, setup=None, legacy=None)[source]

Installs the given new service at the given mount path.

Parameters:

mount (str) – Mount path the service should be installed at.
service (Any) – Service payload. Can be a JSON string, a file-like object, or a multipart form.
headers (dict | None) – Request headers.
development (bool | None) – Whether to install the service in development mode.
setup (bool | None) – Whether to run the service setup script.
legacy (bool | None) – Whether to install in legacy mode.

Returns:

Service metadata.

Return type:

Raises:

FoxxServiceCreateError – If installation fails.

References

install-a-new-service-mode

async delete_service(mount, teardown=None)[source]

Removes the service at the given mount path from the database and file system.

Parameters:

mount (str) – Mount path of the service to uninstall.
teardown (bool | None) – Whether to run the teardown script.

Raises:

FoxxServiceDeleteError – If operations fails.

References

uninstall-a-service

async replace_service(mount, service, headers=None, teardown=None, setup=None, legacy=None, force=None)[source]

Replace an existing Foxx service at the given mount path.

Parameters:

mount (str) – Mount path of the service to replace.
service (Any) – Service payload (JSON string, file-like object, or multipart form).
headers (dict | None) – Optional request headers.
teardown (bool | None) – Whether to run the teardown script.
setup (bool | None) – Whether to run the setup script.
legacy (bool | None) – Whether to install in legacy mode.
force (bool | None) – Set to True to force service install even if no service is installed under given mount.

Returns:

Service metadata.

Return type:

Raises:

FoxxServiceReplaceError – If replacement fails.

References

replace-a-service

async update_service(mount, service, headers=None, teardown=None, setup=None, legacy=None, force=None)[source]

Upgrade a Foxx service at the given mount path.

Parameters:

mount (str) – Mount path of the service to upgrade.
service (Any) – Service payload (JSON string, file-like object, or multipart form).
headers (dict | None) – Optional request headers.
teardown (bool | None) – Whether to run the teardown script.
setup (bool | None) – Whether to run the setup script.
legacy (bool | None) – Whether to upgrade in legacy mode.
force (bool | None) – Set to True to force service install even if no service is installed under given mount.

Returns:

Service metadata.

Return type:

Raises:

FoxxServiceUpdateError – If upgrade fails.

References

upgrade-a-service

async config(mount)[source]

Return service configuration.

Parameters:: mount (str) – Service mount path.
Returns:: Service configuration.
Return type:: dict
Raises:: FoxxConfigGetError – If retrieval fails.

References

get-the-configuration-options

async update_config(mount, options)[source]

Update service configuration.

Parameters:

mount (str) – Service mount path.
options (dict) – Configuration values. Omitted options are ignored.

Returns:

Updated configuration values.

Return type:

Raises:

FoxxConfigUpdateError – If update fails.

References

update-the-configuration-options

async replace_config(mount, options)[source]

Replace service configuration.

Parameters:

mount (str) – Service mount path.
options (dict) – Configuration values. Omitted options are reset to their default values or marked as un-configured.

Returns:

Replaced configuration values.

Return type:

Raises:

FoxxConfigReplaceError – If replace fails.

References

replace-the-configuration-options

async dependencies(mount)[source]

Return service dependencies.

Parameters:: mount (str) – Service mount path.
Returns:: Service dependencies settings.
Return type:: dict
Raises:: FoxxDependencyGetError – If retrieval fails.

References

get-the-dependency-options

async update_dependencies(mount, options)[source]

Update service dependencies.

Parameters:

mount (str) – Service mount path.
options (dict) – Dependencies settings. Omitted ones are ignored.

Returns:

Updated dependency settings.

Return type:

Raises:

FoxxDependencyUpdateError – If update fails.

References

update-the-dependency-options

async replace_dependencies(mount, options)[source]

Replace service dependencies.

Parameters:

mount (str) – Service mount path.
options (dict) – Dependencies settings. Omitted ones are disabled.

Returns:

Replaced dependency settings.

Return type:

Raises:

FoxxDependencyReplaceError – If replace fails.

References

replace-the-dependency-options

async scripts(mount)[source]

List service scripts.

Parameters:: mount (str) – Service mount path.
Returns:: Service scripts.
Return type:: dict
Raises:: FoxxScriptListError – If retrieval fails.

References

list-the-service-scripts

async run_script(mount, name, arg=None)[source]

Run a service script.

Parameters:

mount (str) – Service mount path.
name (str) – Script name.
arg (dict | None) – Arbitrary value passed into the script as first argument.

Returns:

Returns the exports of the script, if any.

Return type:

Any

Raises:

FoxxScriptRunError – If script fails.

References

run-a-service-script

async run_tests(mount, reporter=None, idiomatic=None, filter=None, output_format=None)[source]

Run service tests.

Parameters:

mount (str) – Service mount path.
reporter (str | None) – Test reporter. Allowed values are “default” (simple list of test cases), “suite” (object of test cases nested in suites), “stream” (raw stream of test results), “xunit” (XUnit or JUnit compatible structure), or “tap” (raw TAP compatible stream).
idiomatic (bool | None) – Use matching format for the reporter, regardless of the value of parameter output_format.
filter (str | None) – Only run tests whose full name (test suite and test case) matches the given string.
output_format (str | None) – Used to further control format. Allowed values are “x-ldjson”, “xml” and “text”. When using “stream” reporter, setting this to “x-ldjson” returns newline-delimited JSON stream. When using “tap” reporter, setting this to “text” returns plain text TAP report. When using “xunit” reporter, settings this to “xml” returns an XML instead of JSONML.

Returns:

Reporter output (e.g. raw JSON string, XML, plain text).

Return type:

Raises:

FoxxTestRunError – If test fails.

References

run-the-service-tests

async enable_development(mount)[source]

Puts the service into development mode.

While the service is running in development mode, it is reloaded from the file system, and its setup script (if any) is re-executed every time the service handles a request.

In a cluster with multiple coordinators, changes to the filesystem on one coordinator is not reflected across other coordinators.

Parameters:: mount (str) – Service mount path.
Returns:: Service metadata.
Return type:: dict
Raises:: FoxxDevModeEnableError – If the operation fails.

References

enable-the-development-mode

async disable_development(mount)[source]

Puts the service into production mode.

In a cluster with multiple coordinators, the services on all other coordinators are replaced with the version on the calling coordinator.

Parameters:: mount (str) – Service mount path.
Returns:: Service metadata.
Return type:: dict
Raises:: FoxxDevModeDisableError – If the operation fails.

References

disable-the-development-mode

async readme(mount)[source]

Return the service readme.

Parameters:: mount (str) – Service mount path.
Returns:: Service readme content.
Return type:: str
Raises:: FoxxReadmeGetError – If retrieval fails.

References

get-the-service-readme

async swagger(mount)[source]

Return the Swagger API description for the given service.

Parameters:: mount (str) – Service mount path.
Returns:: Swagger API description.
Return type:: dict
Raises:: FoxxSwaggerGetError – If retrieval fails.

References

get-the-swagger-description

async download(mount)[source]

Downloads a zip bundle of the service directory.

When development mode is enabled, this always creates a new bundle. Otherwise, the bundle will represent the version of a service that is installed on that ArangoDB instance.

Parameters:: mount (str) – Service mount path.
Returns:: Service bundle zip in raw bytes form.
Return type:: bytes
Raises:: FoxxDownloadError – If download fails.

References

download-a-service-bundle

async commit(replace=None)[source]

Commit local service state of the coordinator to the database.

This can be used to resolve service conflicts between coordinators that cannot be fixed automatically due to missing data.

Parameters:: replace (bool | None) – If set to True, any existing service files in the database will be overwritten.
Raises:: FoxxCommitError – If commit fails.

References

commit-the-local-service-state

class arangoasync.cluster.Cluster(executor)[source]

Cluster-specific endpoints.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async health()[source]

Queries the health of the cluster.

Returns:: Health status of the cluster.
Return type:: dict
Raises:: ClusterHealthError – If retrieval fails.

References

get-the-cluster-health

async statistics(db_server)[source]

Queries the statistics of the given DB-Server.

Warning

DB-Server statistics are no longer available in ArangoDB 4.0. Use arangoasync.database.Database.metrics() instead.

Parameters:: db_server (str) – The ID of the DB-Server.
Returns:: Statistics of the DB-Server.
Return type:: dict
Raises:: ClusterStatisticsError – If retrieval fails.

References

get-the-statistics-of-a-db-server

async endpoints()[source]

Fetch all coordinator endpoints.

Returns:: List of coordinator endpoints.
Return type:: list
Raises:: ClusterEndpointsError – If retrieval fails.

References

list-all-coordinator-endpoints

async server_id()[source]

Get the ID of the current server.

Returns:: Server ID.
Return type:: str
Raises:: ClusterServerIDError – If retrieval fails.

References

get-the-server-id

async server_role()[source]

Get the role of the current server

Returns:: Server role. Possible values: “SINGLE”, “COORDINATOR”, “PRIMARY”, “SECONDARY”, “AGENT”, “UNDEFINED”.
Return type:: str
Raises:: ClusterServerRoleError – If retrieval fails.

References

get-the-server-role

async toggle_maintenance_mode(mode)[source]

Enable or disable the cluster supervision (agency) maintenance mode.

Parameters:: mode (str) – Maintenance mode. Allowed values are “on” or “off”.
Returns:: Result of the operation.
Return type:: dict
Raises:: ClusterMaintenanceModeError – If the toggle operation fails.

References

toggle-cluster-maintenance-mode

async server_maintenance_mode(server_id)[source]

Check whether the specified DB-Server is in maintenance mode and until when.

Parameters:: server_id (str) – Server ID.
Returns:: Maintenance status for the given server.
Return type:: dict
Raises:: ClusterMaintenanceModeError – If retrieval fails.

References

get-the-maintenance-status-of-a-db-server

async toggle_server_maintenance_mode(server_id, mode, timeout=None)[source]

Enable or disable the maintenance mode for the given server.

Parameters:

server_id (str) – Server ID.
mode (str) – Maintenance mode. Allowed values are “normal” and “maintenance”.
timeout (int | None) – After how many seconds the maintenance mode shall automatically end.

Raises:

ClusterMaintenanceModeError – If the operation fails.

References

set-the-maintenance-status-of-a-db-server

async calculate_imbalance()[source]

Computes the current cluster imbalance and returns the result.

Returns:: Cluster imbalance information.
Return type:: dict
Raises:: ClusterRebalanceError – If retrieval fails.

References

get-the-current-cluster-imbalance

async calculate_rebalance_plan(databases_excluded=None, exclude_system_collections=None, leader_changes=None, maximum_number_of_moves=None, move_followers=None, move_leaders=None, pi_factor=None, version=1)[source]

Compute a set of move shard operations to improve balance.

Parameters:

databases_excluded (list | None) – List of database names to be excluded from the analysis.
exclude_system_collections (bool | None) – Ignore system collections in the rebalance plan.
leader_changes (bool | None) – Allow leader changes without moving data.
maximum_number_of_moves (int | None) – Maximum number of moves to be computed.
move_followers (bool | None) – Allow moving shard followers.
move_leaders (bool | None) – Allow moving shard leaders.
pi_factor (float | None) – A weighting factor that should remain untouched.
version (int) – Must be set to 1.

Returns:

Cluster rebalance plan.

Return type:

Raises:

ClusterRebalanceError – If retrieval fails.

References

compute-a-set-of-move-shard-operations-to-improve-balance

async rebalance(databases_excluded=None, exclude_system_collections=None, leader_changes=None, maximum_number_of_moves=None, move_followers=None, move_leaders=None, pi_factor=None, version=1)[source]

Compute and execute a set of move shard operations to improve balance.

Parameters:

databases_excluded (list | None) – List of database names to be excluded from the analysis.
exclude_system_collections (bool | None) – Ignore system collections in the rebalance plan.
leader_changes (bool | None) – Allow leader changes without moving data.
maximum_number_of_moves (int | None) – Maximum number of moves to be computed.
move_followers (bool | None) – Allow moving shard followers.
move_leaders (bool | None) – Allow moving shard leaders.
pi_factor (float | None) – A weighting factor that should remain untouched.
version (int) – Must be set to 1.

Returns:

Cluster rebalance plan.

Return type:

Raises:

ClusterRebalanceError – If retrieval fails.

References

compute-and-execute-a-set-of-move-shard-operations-to-improve-balance

async execute_rebalance_plan(moves, version=1)[source]

Execute a set of move shard operations.

Parameters:

moves (list) – List of move shard operations to be executed.
version (int) – Must be set to 1.

Returns:

Indicates whether the methods have been accepted and scheduled for execution.

Return type:

Raises:

ClusterRebalanceError – If the execution fails.

References

execute-a-set-of-move-shard-operations

class arangoasync.compression.AcceptEncoding(*values)[source]: Valid accepted encodings for the Accept-Encoding header.

class arangoasync.compression.ContentEncoding(*values)[source]: Valid content encodings for the Content-Encoding header.

class arangoasync.compression.CompressionManager[source]

Abstract base class for handling request/response compression.

abstractmethod needs_compression(data)[source]

Determine if the data needs to be compressed

Parameters:: data (str | bytes) – Data to check
Returns:: True if the data needs to be compressed
Return type:: bool

abstractmethod compress(data)[source]

Compress the data

Parameters:: data (str | bytes) – Data to compress
Returns:: Compressed data
Return type:: bytes

abstract property content_encoding

Return the content encoding.

This is the value of the Content-Encoding header in the HTTP request. Must match the encoding used in the compress method.

Returns:: Content encoding
Return type:: str

abstract property accept_encoding

Return the accept encoding.

This is the value of the Accept-Encoding header in the HTTP request. Currently, only “deflate” and “gzip” are supported.

Returns:: Accept encoding
Return type:: str

class arangoasync.compression.DefaultCompressionManager(threshold=1024, level=6, accept=AcceptEncoding.DEFLATE)[source]

Compress requests using the deflate algorithm.

Parameters:

threshold (int) – Will compress requests to the server if
body (the size of the request)
compression. (Setting it to -1 will disable request)
level (int) – Compression level. Defaults to 6.
accept (str | None) – Accepted encoding. Can be disabled by setting it to None.

property accept_encoding

Return the accept encoding.

This is the value of the Accept-Encoding header in the HTTP request. Currently, only “deflate” and “gzip” are supported.

Returns:: Accept encoding
Return type:: str

property content_encoding

Return the content encoding.

This is the value of the Content-Encoding header in the HTTP request. Must match the encoding used in the compress method.

Returns:: Content encoding
Return type:: str

needs_compression(data)[source]

Determine if the data needs to be compressed

Parameters:: data (str | bytes) – Data to check
Returns:: True if the data needs to be compressed
Return type:: bool

compress(data)[source]

Compress the data

Parameters:: data (str | bytes) – Data to compress
Returns:: Compressed data
Return type:: bytes

class arangoasync.serialization.Serializer[source]

Abstract base class for serialization.

Custom serialization classes should inherit from this class. Please be mindful of the performance implications.

abstractmethod dumps(data)[source]

Serialize any generic data.

Parameters:: data – Data to serialize.
Returns:: Serialized data.
Return type:: str
Raises:: SerializationError – If the data cannot be serialized.

class arangoasync.serialization.Deserializer[source]

Abstract base class for deserialization.

Custom deserialization classes should inherit from this class. Please be mindful of the performance implications.

abstractmethod loads(data)[source]

Deserialize response data.

Will be called on generic server data (such as server status) and single documents.

Parameters:: data (bytes) – Data to deserialize.
Returns:: Deserialized data.
Raises:: DeserializationError – If the data cannot be deserialized.

abstractmethod loads_many(data)[source]

Deserialize response data.

Will only be called when deserializing a list of documents.

Parameters:: data (bytes) – Data to deserialize.
Returns:: Deserialized data.
Raises:: DeserializationError – If the data cannot be deserialized.

class arangoasync.serialization.JsonSerializer[source]

JSON serializer.

dumps(data)[source]

Serialize any generic data.

Parameters:: data – Data to serialize.
Returns:: Serialized data.
Return type:: str
Raises:: SerializationError – If the data cannot be serialized.

class arangoasync.serialization.JsonDeserializer[source]

JSON deserializer.

loads(data)[source]

Deserialize response data.

Will be called on generic server data (such as server status) and single documents.

Parameters:: data (bytes) – Data to deserialize.
Returns:: Deserialized data.
Raises:: DeserializationError – If the data cannot be deserialized.

loads_many(data)[source]

Deserialize response data.

Will only be called when deserializing a list of documents.

Parameters:: data (bytes) – Data to deserialize.
Returns:: Deserialized data.
Raises:: DeserializationError – If the data cannot be deserialized.

arangoasync.serialization.DefaultSerializer: alias of JsonSerializer

arangoasync.serialization.DefaultDeserializer: alias of JsonDeserializer

class arangoasync.connection.BaseConnection(sessions, host_resolver, http_client, db_name, compression=None, serializer=None, deserializer=None)[source]

Blueprint for connection to a specific ArangoDB database.

Parameters:

sessions (list) – List of client sessions.
host_resolver (HostResolver) – Host resolver.
http_client (HTTPClient) – HTTP client.
db_name (str) – Database name.
compression (CompressionManager | None) – Compression manager.
serializer (Serializer | None) – For overriding the default JSON serialization. Leave None for default.
deserializer (Deserializer | None) – For overriding the default JSON deserialization. Leave None for default.

property db_name: Return the database name.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

static raise_for_status(request, resp)[source]

Raise an exception based on the response.

Parameters:

request (Request) – Request object.
resp (Response) – Response object.

Raises:

ServerConnectionError – If the response status code is not successful.

prep_response(request, resp)[source]

Prepare response for return.

Parameters:

request (Request) – Request object.
resp (Response) – Response object.

Returns:

Response object

Return type:

compress_request(request)[source]

Compress request if needed.

Additionally, the server may be instructed to compress the response. The decision to compress the request is based on the compression strategy passed during the connection initialization. The request headers and may be modified as a result of this operation.

Parameters:: request (Request) – Request to be compressed.
Returns:: True if compression settings were applied.
Return type:: bool

async process_request(request)[source]

Process request, potentially trying multiple hosts.

Parameters:: request (Request) – Request object.
Returns:: Response object.
Return type:: Response
Raises:: ConnectionAbortedError – If it can’t connect to host(s) within limit.

async ping()[source]

Ping host to check if connection is established.

Returns:: Response status code.
Return type:: int
Raises:: ServerConnectionError – If the response status code is not successful.

abstractmethod async send_request(request)[source]

Send an HTTP request to the ArangoDB server.

Parameters:: request (Request) – HTTP request.
Returns:: HTTP response.
Return type:: Response

class arangoasync.connection.BasicConnection(sessions, host_resolver, http_client, db_name, compression=None, serializer=None, deserializer=None, auth=None)[source]

Connection to a specific ArangoDB database.

Allows for basic authentication to be used (username and password).

Parameters:

sessions (list) – List of client sessions.
host_resolver (HostResolver) – Host resolver.
http_client (HTTPClient) – HTTP client.
db_name (str) – Database name.
compression (CompressionManager | None) – Compression manager.
serializer (Serializer | None) – Override default JSON serialization.
deserializer (Deserializer | None) – Override default JSON deserialization.
auth (Auth | None) – Authentication information.

async send_request(request)[source]

Send an HTTP request to the ArangoDB server.

Parameters:

request (Request) – HTTP request.

Returns:

HTTP response

Return type:

Raises:

ArangoClientError – If an error occurred from the client side.
ArangoServerError – If an error occurred from the server side.

class arangoasync.connection.JwtConnection(sessions, host_resolver, http_client, db_name, compression=None, serializer=None, deserializer=None, auth=None, token=None)[source]

Connection to a specific ArangoDB database, using JWT authentication.

Providing login information (username and password), allows to refresh the JWT.

Parameters:

sessions (list) – List of client sessions.
host_resolver (HostResolver) – Host resolver.
http_client (HTTPClient) – HTTP client.
db_name (str) – Database name.
compression (CompressionManager | None) – Compression manager.
serializer (Serializer | None) – For custom serialization.
deserializer (Deserializer | None) – For custom deserialization.
auth (Auth | None) – Authentication information.
token (JwtToken | None) – JWT token.

Raises:

ValueError – If neither token nor auth is provided.

property token

Get the JWT token.

Returns:: JWT token.
Return type:: JwtToken | None

async refresh_token()[source]

Refresh the JWT token.

Raises:: JWTRefreshError – If the token can’t be refreshed.

async send_request(request)[source]

Send an HTTP request to the ArangoDB server.

Parameters:

request (Request) – HTTP request.

Returns:

HTTP response

Return type:

Raises:

AuthHeaderError – If the authentication header could not be generated.
ArangoClientError – If an error occurred from the client side.
ArangoServerError – If an error occurred from the server side.

class arangoasync.connection.JwtSuperuserConnection(sessions, host_resolver, http_client, db_name, compression=None, serializer=None, deserializer=None, token=None)[source]

Connection to a specific ArangoDB database, using superuser JWT.

The JWT token is not refreshed and (username and password) are not required.

Parameters:

sessions (list) – List of client sessions.
host_resolver (HostResolver) – Host resolver.
http_client (HTTPClient) – HTTP client.
db_name (str) – Database name.
compression (CompressionManager | None) – Compression manager.
serializer (Serializer | None) – For custom serialization.
deserializer (Deserializer | None) – For custom deserialization.
token (JwtToken | None) – JWT token.

property token

Get the JWT token.

Returns:: JWT token.
Return type:: JwtToken | None

async send_request(request)[source]

Send an HTTP request to the ArangoDB server.

Parameters:

request (Request) – HTTP request.

Returns:

HTTP response

Return type:

Raises:

AuthHeaderError – If the authentication header could not be generated.
ArangoClientError – If an error occurred from the client side.
ArangoServerError – If an error occurred from the server side.

class arangoasync.http.HTTPClient[source]

Abstract base class for HTTP clients.

Custom HTTP clients should inherit from this class.

Example

class MyCustomHTTPClient(HTTPClient):
    def create_session(self, host):
        pass
    async def close_session(self, session):
        pass
    async def send_request(self, session, request):
        pass

abstractmethod create_session(host)[source]

Return a new session given the base host URL.

Note

This method must be overridden by the user.

Parameters:: host (str) – ArangoDB host URL.
Returns:: Requests session object.

abstractmethod async close_session(session)[source]

Close the session.

Note

This method must be overridden by the user.

Parameters:: session (Any) – Client session object.

abstractmethod async send_request(session, request)[source]

Send an HTTP request.

Note

This method must be overridden by the user.

Parameters:

session (Any) – Client session object.
request (Request) – HTTP request.

Returns:

HTTP response.

Return type:

class arangoasync.http.AioHTTPClient(connector=None, timeout=None, read_bufsize=65536, ssl_context=True)[source]

HTTP client implemented on top of aiohttp.

Parameters:

connector (aiohttp.BaseConnector | None) – Supports connection pooling. By default, 100 simultaneous connections are supported, with a 60-second timeout for connection reusing after release.
timeout (aiohttp.ClientTimeout | None) – Client timeout settings. 300s total timeout by default for a complete request/response operation.
read_bufsize (int) – Size of read buffer (64KB default).
ssl_context (ssl.SSLContext | bool) – SSL validation mode. True for default SSL checks (see ssl.create_default_context()). False disables SSL checks. Additionally, you can pass a custom ssl.SSLContext.

create_session(host)[source]

Return a new session given the base host URL.

Parameters:: host (str) – ArangoDB host URL. Must not include any paths. Typically, this is the address and port of a coordinator (e.g. “http://127.0.0.1:8529”).
Returns:: Session object, used to send future requests.
Return type:: aiohttp.ClientSession

async close_session(session)[source]

Close the session.

Parameters:: session (Any) – Client session object.

async send_request(session, request)[source]

Send an HTTP request.

Parameters:

session (aiohttp.ClientSession) – Session object used to make the request.
request (Request) – HTTP request.

Returns:

HTTP response.

Return type:

Raises:

ClientConnectionError – If the request fails.

arangoasync.http.DefaultHTTPClient: alias of AioHTTPClient

class arangoasync.request.Method(*values)[source]: HTTP methods enum: GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS

class arangoasync.request.Request(method, endpoint, headers=None, params=None, data=None, auth=None, prefix_needed=True)[source]

HTTP request.

Parameters:

method (Method) – HTTP method.
endpoint (str) – API endpoint.
headers (dict | None) – Request headers.
params (dict | None) – URL parameters.
data (Any) – Request payload.
auth (Auth | None) – Authentication.
prefix_needed (bool) – Whether the request needs a prefix (e.g., database name).

method

HTTP method.

Type:: Method

endpoint

API endpoint.

Type:: str

headers

Request headers.

Type:: dict | None

params

URL parameters.

Type:: dict | None

data

Request payload.

Type:: Any

auth

Authentication.

Type:: Auth | None

prefix_needed

Whether the request needs a prefix (e.g., database name).

Type:: bool

normalized_headers()[source]

Normalize request headers.

Returns:: Normalized request headers.
Return type:: dict

normalized_params()[source]

Normalize URL parameters.

Returns:: Normalized URL parameters.
Return type:: dict

class arangoasync.resolver.HostResolver(host_count=1, max_tries=None)[source]

Abstract base class for host resolvers.

Parameters:

host_count (int) – Number of hosts.
max_tries (int | None) – Maximum number of attempts to try a host. Will default to 3 times the number of hosts if not provided.

Raises:

ValueError – If max_tries is less than host_count.

abstractmethod get_host_index()[source]

Return the index of the host to use.

Returns:: Index of the host.
Return type:: int

change_host()[source]: If there are multiple hosts available, switch to the next one.

property host_count: Return the number of hosts.

property max_tries: Return the maximum number of attempts.

class arangoasync.resolver.SingleHostResolver(host_count, max_tries=None)[source]

Single host resolver.

Always returns the same host index, unless prompted to change.

get_host_index()[source]

Return the index of the host to use.

Returns:: Index of the host.
Return type:: int

class arangoasync.resolver.RoundRobinHostResolver(host_count, max_tries=None)[source]

Round-robin host resolver. Changes host every time.

Useful for bulk inserts or updates.

Note

Do not use this resolver for stream transactions. Transaction IDs cannot be shared across different coordinators.

get_host_index(indexes_to_filter=None)[source]

Return the index of the host to use.

Returns:: Index of the host.
Return type:: int

arangoasync.resolver.DefaultHostResolver: alias of SingleHostResolver

arangoasync.resolver.get_resolver(strategy, host_count, max_tries=None)[source]

Return a host resolver based on the strategy.

Parameters:

strategy (str) – Resolver strategy.
host_count (int) – Number of hosts.
max_tries (int) – Maximum number of attempts to try a host.

Returns:

Host resolver.

Return type:

HostResolver

Raises:

ValueError – If the strategy is not supported.

class arangoasync.response.Response(method, url, headers, status_code, status_text, raw_body)[source]

HTTP response.

Parameters:

method (Method) – HTTP method.
url (str) – API URL.
headers (dict) – Response headers.
status_code (int) – Response status code.
status_text (str) – Response status text.
raw_body (bytes) – Raw response body.

method

HTTP method.

Type:: Method

url

API URL.

Type:: str

headers

Response headers.

Type:: dict

status_code

Response status code.

Type:: int

status_text

Response status text.

Type:: str

raw_body

Raw response body.

Type:: bytes

error_code

Error code from ArangoDB server.

Type:: int | None

error_message

Error message from ArangoDB server.

Type:: str | None

is_success

True if response status code was 2XX.

Type:: bool | None

static format_body(body)[source]

Format the generic response body, stripping the error code and message.

Parameters:: body (Json) – The response body.
Returns:: The formatted response body.
Return type:: dict

class arangoasync.replication.Replication(executor)[source]

Replication API wrapper.

property serializer: Return the serializer.

property deserializer: Return the deserializer.

async inventory(batch_id, include_system=None, all_databases=None, collection=None, db_server=None)[source]

Return an overview of collections and indexes.

Parameters:

batch_id (str) – Batch ID.
include_system (bool | None) – Include system collections.
all_databases (bool | None) – Include all databases (only on “_system”).
collection (bool | None) – If this parameter is set, the response will be restricted to a single collection (the one specified), and no views will be returned.
db_server (str | None) – On a Coordinator, this request must have a DBserver query parameter

Returns:

Overview of collections and indexes.

Return type: