API Specification

This page contains the specification for all classes and methods available in python-arango.

ArangoClient

class arango.client.ArangoClient(hosts: str | ~typing.Sequence[str] = 'http://127.0.0.1:8529', host_resolver: str | ~arango.resolver.HostResolver = 'fallback', resolver_max_tries: int | None = None, http_client: ~arango.http.HTTPClient | None = None, serializer: ~typing.Callable[[...], str] = <function default_serializer>, deserializer: ~typing.Callable[[str], ~typing.Any] = <function default_deserializer>, verify_override: bool | str | None = None, request_timeout: int | float | None = 60)[source]

ArangoDB client.

Parameters:
  • hosts (str | [str]) – Host URL or list of URLs (coordinators in a cluster).

  • host_resolver (str | arango.resolver.HostResolver) – Host resolver. This parameter used for clusters (when multiple host URLs are provided). Accepted values are “fallback”, “roundrobin”, “random” and “periodic”. The default value is “fallback”.

  • resolver_max_tries (int) – Number of attempts to process an HTTP request before throwing a ConnectionAbortedError. Must not be lower than the number of hosts.

  • http_client (arango.http.HTTPClient) – User-defined HTTP client.

  • serializer (callable) – User-defined JSON serializer. Must be a callable which takes a JSON data type object as its only argument and return the serialized string. If not given, json.dumps is used by default.

  • deserializer (callable) – User-defined JSON de-serializer. Must be a callable which takes a JSON serialized string as its only argument and return the de-serialized object. If not given, json.loads is used by default.

  • verify_override (Union[bool, str, None]) – Override TLS certificate verification. This will override the verify method of the underlying HTTP client. None: Do not change the verification behavior of the underlying HTTP client. True: Verify TLS certificate using the system CA certificates. False: Do not verify TLS certificate. str: Path to a custom CA bundle file or directory.

  • request_timeout (int | float) – This is the default request timeout (in seconds) for http requests issued by the client if the parameter http_client is not specified. The default value is 60. None: No timeout. int: Timeout value in seconds.

close() None[source]

Close HTTP sessions.

property hosts: Sequence[str]

Return the list of ArangoDB host URLs.

Returns:

List of ArangoDB host URLs.

Return type:

[str]

property version: str

Return the client version.

Returns:

Client version.

Return type:

str

property request_timeout: Any

Return the request timeout of the http client.

Returns:

Request timeout.

Return type:

Any

db(name: str = '_system', username: str = 'root', password: str = '', verify: bool = False, auth_method: str = 'basic', user_token: str | None = None, superuser_token: str | None = None, verify_certificate: bool = True) StandardDatabase[source]

Connect to an ArangoDB database and return the database API wrapper.

Parameters:
  • name (str) – Database name.

  • username (str) – Username for basic authentication.

  • password (str) – Password for basic authentication.

  • verify (bool) – Verify the connection by sending a test request.

  • auth_method (str) – HTTP authentication method. Accepted values are “basic” (default) and “jwt”. If set to “jwt”, the token is refreshed automatically using ArangoDB username and password. This assumes that the clocks of the server and client are synchronized.

  • user_token (str) – User generated token for user access. If set, parameters username, password and auth_method are ignored. This token is not refreshed automatically. If automatic token refresh is required, consider setting auth_method to “jwt” and using the username and password parameters instead. Token expiry will be checked.

  • superuser_token (str) – User generated token for superuser access. If set, parameters username, password and auth_method are ignored. This token is not refreshed automatically. Token expiry will not be checked.

  • verify_certificate (bool) – Verify TLS certificates.

Returns:

Standard database API wrapper.

Return type:

arango.database.StandardDatabase

Raises:

arango.exceptions.ServerConnectionError – If verify was set to True and the connection fails.

AsyncDatabase

class arango.database.AsyncDatabase(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, return_result: bool)[source]

Database API wrapper tailored specifically for async execution.

See arango.database.StandardDatabase.begin_async_execution().

Parameters:
  • connection – HTTP connection.

  • return_result (bool) – If set to True, API executions return instances of arango.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.

analyzer(name: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return analyzer details.

Parameters:

name (str) – Analyzer name.

Returns:

Analyzer details.

Return type:

dict

Raises:

arango.exceptions.AnalyzerGetError – If retrieval fails.

analyzers() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return list of analyzers.

Returns:

List of analyzers.

Return type:

[dict]

Raises:

arango.exceptions.AnalyzerListError – If retrieval fails.

property aql: AQL

Return AQL (ArangoDB Query Language) API wrapper.

Returns:

AQL API wrapper.

Return type:

arango.aql.AQL

async_jobs(status: str, count: int | None = None) List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None

Return IDs of async jobs with given status.

Parameters:
  • status (str) – Job status (e.g. “pending”, “done”).

  • count (int) – Max number of job IDs to return.

Returns:

List of job IDs.

Return type:

[str]

Raises:

arango.exceptions.AsyncJobListError – If retrieval fails.

property backup: Backup

Return Backup API wrapper.

Returns:

Backup API wrapper.

Return type:

arango.backup.Backup

clear_async_jobs(threshold: int | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Clear async job results from the server.

Async jobs that are still queued or running are not stopped.

Parameters:

threshold (int | None) – If specified, only the job results created prior to the threshold (a unix timestamp) are deleted. Otherwise, all job results are deleted.

Returns:

True if job results were cleared successfully.

Return type:

bool

Raises:

arango.exceptions.AsyncJobClearError – If operation fails.

property cluster: Cluster

Return Cluster API wrapper.

Returns:

Cluster API wrapper.

Return type:

arango.cluster.Cluster

collection(name: str) StandardCollection

Return the standard collection API wrapper.

Parameters:

name (str) – Collection name.

Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

collections() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return the collections in the database.

Returns:

Collections in the database and their details.

Return type:

[dict]

Raises:

arango.exceptions.CollectionListError – If retrieval fails.

compact(change_level: bool | None = None, compact_bottom_most_level: bool | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Compact all databases.

NOTE: This command can cause a full rewrite of all data in all databases, which may take very long for large databases. It should thus only be used with care and only when additional I/O load can be tolerated for a prolonged time.

This method can be used to reclaim disk space after substantial data deletions have taken place, by compacting the entire database system data.

This method requires superuser access.

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:

Collection compact.

Return type:

dict

Raises:

arango.exceptions.CollectionCompactError – If retrieval fails.

property conn: BasicConnection | JwtConnection | JwtSuperuserConnection

Return the HTTP connection.

Returns:

HTTP connection.

Return type:

arango.connection.BasicConnection | arango.connection.JwtConnection | arango.connection.JwtSuperuserConnection

property context: str

Return the API execution context.

Returns:

API execution context. Possible values are “default”, “async”, “batch” and “transaction”.

Return type:

str

create_analyzer(name: str, analyzer_type: str, properties: Dict[str, Any] | None = None, features: Sequence[str] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create an analyzer.

Parameters:
  • name (str) – Analyzer name.

  • analyzer_type (str) – Analyzer type.

  • properties (dict | None) – Analyzer properties.

  • features (list | None) – Analyzer features.

Returns:

Analyzer details.

Return type:

dict

Raises:

arango.exceptions.AnalyzerCreateError – If create fails.

create_arangosearch_view(name: str, properties: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create an ArangoSearch view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

create_collection(name: str, sync: bool = False, system: bool = False, edge: bool = False, user_keys: bool = True, key_increment: int | None = None, key_offset: int | None = None, key_generator: str = 'traditional', shard_fields: Sequence[str] | None = None, shard_count: int | None = None, replication_factor: int | None = None, shard_like: str | None = None, sync_replication: bool | None = None, enforce_replication_factor: bool | None = None, sharding_strategy: str | None = None, smart_join_attribute: str | None = None, write_concern: int | None = None, schema: Dict[str, Any] | None = None, computedValues: List[Dict[str, Any]] | None = None) StandardCollection | AsyncJob[StandardCollection] | BatchJob[StandardCollection] | None

Create a new collection.

Parameters:
  • name (str) – Collection name.

  • sync (bool | None) – If set to True, document operations via the collection will block until synchronized to disk by default.

  • system (bool) – If set to True, a system collection is created. The collection name must have leading underscore “_” character.

  • edge (bool) – If set to True, an edge collection is created.

  • key_generator (str) – Used for generating document keys. Allowed values are “traditional” or “autoincrement”.

  • user_keys (bool) – If set to True, users are allowed to supply document keys. If set to False, the key generator is solely responsible for supplying the key values.

  • key_increment (int) – Key increment value. Applies only when value of key_generator is set to “autoincrement”.

  • key_offset (int) – Key offset value. Applies only when value of key_generator is set to “autoincrement”.

  • shard_fields ([str]) – Field(s) used to determine the target shard.

  • shard_count (int) – Number of shards to create.

  • replication_factor (int) – Number of copies of each shard on different servers in a cluster. Allowed values are 1 (only one copy is kept and no synchronous replication), and n (n-1 replicas are kept and any two copies are replicated across servers synchronously, meaning every write to the master is copied to all slaves before operation is reported successful).

  • shard_like (str) – Name of prototype collection whose sharding specifics are imitated. Prototype collections cannot be dropped before imitating collections. Applies to enterprise version of ArangoDB only.

  • sync_replication (bool) – If set to True, server reports success only when collection is created in all replicas. You can set this to False for faster server response, and if full replication is not a concern.

  • enforce_replication_factor (bool) – Check if there are enough replicas available at creation time, or halt the operation.

  • sharding_strategy (str) – Sharding strategy. Available for ArangoDB version and up only. Possible values are “community-compat”, “enterprise-compat”, “enterprise-smart-edge-compat”, “hash” and “enterprise-hash-smart-edge”. Refer to ArangoDB documentation for more details on each value.

  • smart_join_attribute (str) – Attribute of the collection which must contain the shard key value of the smart join collection. The shard key for the documents must contain the value of this attribute, followed by a colon “:” and the primary key of the document. Requires parameter shard_like to be set to the name of another collection, and parameter shard_fields to be set to a single shard key attribute, with another colon “:” at the end. Available only for enterprise version of ArangoDB.

  • write_concern (int) – Write concern for the collection. Determines how many copies of each shard are required to be in sync on different DBServers. 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. The value of this parameter cannot be larger than that of replication_factor. Default value is 1. Used for clusters only.

  • schema (dict) – Optional dict specifying the collection level schema for documents. See ArangoDB documentation for more information on document schema validation.

  • computedValues (list) – Array of computed values for the new collection enabling default values to new documents or the maintenance of auxiliary attributes for search queries. Available in ArangoDB version 3.10 or greater. See ArangoDB documentation for more information on computed values.

Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

Raises:

arango.exceptions.CollectionCreateError – If create fails.

create_database(name: str, users: Sequence[Dict[str, Any]] | None = None, replication_factor: int | str | None = None, write_concern: int | None = None, sharding: str | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Create a new database.

Parameters:
  • name (str) – Database name.

  • users ([dict]) – List of users with access to the new database, where each user is a dictionary with fields “username”, “password”, “active” and “extra” (see below for example). If not set, only the admin and current user are granted access.

  • replication_factor (int | str) – Default replication factor for collections created in this database. Special values include “satellite” which replicates the collection to every DBServer, and 1 which disables replication. Used for clusters only.

  • write_concern (int) – Default write concern for collections created in this database. Determines how many copies of each shard are required to be in sync on different DBServers. 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) – 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 database was created successfully.

Return type:

bool

Raises:

arango.exceptions.DatabaseCreateError – If create fails.

Here is an example entry for parameter users:

{
    'username': 'john',
    'password': 'password',
    'active': True,
    'extra': {'Department': 'IT'}
}
create_graph(name: str, edge_definitions: Sequence[Dict[str, Any]] | None = None, orphan_collections: Sequence[str] | None = None, smart: bool | None = None, disjoint: bool | None = None, smart_field: str | None = None, shard_count: int | None = None, replication_factor: int | None = None, write_concern: int | None = None) Graph | AsyncJob[Graph] | BatchJob[Graph] | None

Create a new graph.

Parameters:
  • name (str) – Graph name.

  • edge_definitions ([dict] | None) – List of edge definitions, where each edge definition entry is a dictionary with fields “edge_collection”, “from_vertex_collections” and “to_vertex_collections” (see below for example).

  • orphan_collections ([str] | None) – Names of additional vertex collections that are not in edge definitions.

  • smart (bool | None) – If set to True, sharding is enabled (see parameter smart_field below). Applies only to enterprise version of ArangoDB.

  • disjoint (bool | None) – If set to True, create a disjoint SmartGraph instead of a regular SmartGraph. Applies only to enterprise version of ArangoDB.

  • smart_field (str | None) – Document field used to shard the vertices of the graph. To use this, parameter smart must be set to True and every vertex in the graph must have the smart field. Applies only to enterprise version of ArangoDB.

  • shard_count (int | None) – Number of shards used for every collection in the graph. To use this, parameter smart must be set to True and every vertex in the graph must have the smart field. This number cannot be modified later once set. Applies only to enterprise version of ArangoDB.

  • replication_factor (int) – Number of copies of each shard on different servers in a cluster. Allowed values are 1 (only one copy is kept and no synchronous replication), and n (n-1 replicas are kept and any two copies are replicated across servers synchronously, meaning every write to the master is copied to all slaves before operation is reported successful).

  • write_concern (int) – Write concern for the collection. Determines how many copies of each shard are required to be in sync on different DBServers. 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. The value of this parameter cannot be larger than that of replication_factor. Default value is 1. Used for clusters only.

Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

Raises:

arango.exceptions.GraphCreateError – If create fails.

Here is an example entry for parameter edge_definitions:

[
    {
        'edge_collection': 'teach',
        'from_vertex_collections': ['teachers'],
        'to_vertex_collections': ['lectures']
    }
]
create_task(name: str, command: str, params: Dict[str, Any] | None = None, period: int | None = None, offset: int | None = None, task_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create a new server task.

Parameters:
  • name (str) – Name of the server task.

  • command (str) – Javascript command to execute.

  • params (dict | None) – Optional parameters passed into the Javascript command.

  • period (int | None) – Number of seconds to wait between executions. If set to 0, the new task will be “timed”, meaning it will execute only once and be deleted afterwards.

  • offset (int | None) – Initial delay before execution in seconds.

  • task_id (str | None) – Pre-defined ID for the new server task.

Returns:

Details of the new task.

Return type:

dict

Raises:

arango.exceptions.TaskCreateError – If create fails.

create_user(username: str, password: str | None = None, active: bool | None = None, extra: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create a new user.

Parameters:
  • username (str) – Username.

  • password (str | None) – Password.

  • active (bool | None) – True if user is active, False otherwise.

  • extra (dict | None) – Additional data for the user.

Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserCreateError – If create fails.

create_view(name: str, view_type: str, properties: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create a view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

databases() List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None

Return the names of all databases.

Returns:

Database names.

Return type:

[str]

Raises:

arango.exceptions.DatabaseListError – If retrieval fails.

databases_accessible_to_user() List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None

Return the names of all databases accessible by the user.

Returns:

Database names accesible by the current user.

Return type:

List[str]

Raises:

arango.exceptions.DatabaseListError – If retrieval fails.

property db_name: str

Return the name of the current database.

Returns:

Database name.

Return type:

str

delete_analyzer(name: str, force: bool = False, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete an analyzer.

Parameters:
  • name (str) – Analyzer name.

  • force (bool) – Remove the analyzer configuration even if in use.

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.AnalyzerDeleteError – If delete fails.

delete_collection(name: str, ignore_missing: bool = False, system: bool | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete the collection.

Parameters:
  • name (str) – Collection name.

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

  • system (bool) – Whether the collection is a system collection.

Returns:

True if collection was deleted successfully, False if collection was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.CollectionDeleteError – If delete fails.

delete_database(name: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete the database.

Parameters:
  • name (str) – Database name.

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

Returns:

True if database was deleted successfully, False if database was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.DatabaseDeleteError – If delete fails.

delete_document(document: str | Dict[str, Any], rev: str | None = None, check_rev: bool = True, ignore_missing: bool = False, return_old: bool = False, sync: bool | None = None, silent: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

Delete a document.

Parameters:
  • document (str | dict) – Document ID, key or body. Document body must contain the “_id” field.

  • rev (str | None) – Expected document revision. Overrides the value of “_rev” field in document if present.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

  • 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.

  • return_old (bool) – Include body of the old document in the result.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

Returns:

Document metadata (e.g. document key, revision), or True if parameter silent was set to True, or False if document was not found and ignore_missing was set to True (does not apply in transactions).

Return type:

bool | dict

Raises:
delete_graph(name: str, ignore_missing: bool = False, drop_collections: bool | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Drop the graph of the given name from the database.

Parameters:
  • name (str) – Graph name.

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

  • drop_collections (bool | None) – Drop the collections of the graph also. This is only if they are not in use by other graphs.

Returns:

True if graph was deleted successfully, False if graph was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.GraphDeleteError – If delete fails.

delete_task(task_id: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete a server task.

Parameters:
  • task_id (str) – Server task ID.

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.TaskDeleteError – If delete fails.

delete_user(username: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete a user.

Parameters:
  • username (str) – Username.

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

Returns:

True if user was deleted successfully, False if user was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.UserDeleteError – If delete fails.

delete_view(name: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete a view.

Parameters:
  • name (str) – View name.

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.ViewDeleteError – If delete fails.

details() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return ArangoDB server details.

Returns:

Server details.

Return type:

dict

Raises:

arango.exceptions.ServerDetailsError – If retrieval fails.

document(document: Dict[str, Any], rev: str | None = None, check_rev: bool = True) Dict[str, Any] | None | AsyncJob[Dict[str, Any] | None] | BatchJob[Dict[str, Any] | None]

Return a document.

Parameters:
  • document (str | dict) – Document ID or body with “_id” field.

  • rev (str | None) – Expected document revision. Overrides the value of “_rev” field in document if present.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

Returns:

Document, or None if not found.

Return type:

dict | None

Raises:
echo(body: Any | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return details of the last request (e.g. headers, payload), or echo the given request body.

Parameters:

body (dict | list | str | int | float | None) – The body of the request. Can be of any type and is simply forwarded. If not set, the details of the last request are returned.

Returns:

Details of the last request.

Return type:

dict

Raises:

arango.exceptions.ServerEchoError – If retrieval fails.

encryption() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Rotate the user-supplied keys for encryption.

This method is available only for enterprise edition of ArangoDB.

Returns:

New TLS data.

Return type:

dict

Raises:

arango.exceptions.ServerEncryptionError – If retrieval fails.

engine() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the database engine details.

Returns:

Database engine details.

Return type:

dict

Raises:

arango.exceptions.ServerEngineError – If retrieval fails.

execute(command: str) Any | AsyncJob[Any] | BatchJob[Any] | None

Execute raw Javascript command on the server.

Executes the JavaScript code in the body on the server as the body of a function with no arguments. If you have a return statement then the return value you produce will be returned as ‘application/json’.

NOTE: this method endpoint will only be usable if the server was started with the option –javascript.allow-admin-execute true. The default value of this option is false, which disables the execution of user-defined code and disables this API endpoint entirely. This is also the recommended setting for production.

Parameters:

command (str) – Javascript command to execute.

Returns:

Return value of command, if any.

Return type:

Any

Raises:

arango.exceptions.ServerExecuteError – If execution fails.

execute_transaction(command: str, params: Dict[str, Any] | None = None, read: Sequence[str] | None = None, write: Sequence[str] | None = None, sync: bool | None = None, timeout: Number | None = None, max_size: int | None = None, allow_implicit: bool | None = None, intermediate_commit_count: int | None = None, intermediate_commit_size: int | None = None, allow_dirty_read: bool = False) Any | AsyncJob[Any] | BatchJob[Any] | None

Execute raw Javascript command in transaction.

Parameters:
  • command (str) – Javascript command to execute.

  • read ([str] | None) – Names of collections read during transaction. If parameter allow_implicit is set to True, any undeclared read collections are loaded lazily.

  • write ([str] | None) – Names of collections written to during transaction. Transaction fails on undeclared write collections.

  • params (dict | None) – Optional parameters passed into the Javascript command.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • timeout (int | None) – Timeout for waiting on collection locks. If set to 0, ArangoDB server waits indefinitely. If not set, system default value is used.

  • max_size (int | None) – Max transaction size limit in bytes.

  • allow_implicit (bool | None) – If set to True, undeclared read collections are loaded lazily. If set to False, transaction fails on any undeclared collections.

  • intermediate_commit_count (int | None) – Max number of operations after which an intermediate commit is performed automatically.

  • intermediate_commit_size (int | None) – Max size of operations in bytes after which an intermediate commit is performed automatically.

  • allow_dirty_read (bool | None) – Allow reads from followers in a cluster.

Returns:

Return value of command.

Return type:

Any

Raises:

arango.exceptions.TransactionExecuteError – If execution fails.

property foxx: Foxx

Return Foxx API wrapper.

Returns:

Foxx API wrapper.

Return type:

arango.foxx.Foxx

graph(name: str) Graph

Return the graph API wrapper.

Parameters:

name (str) – Graph name.

Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

graphs() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

List all graphs in the database.

Returns:

Graphs in the database.

Return type:

[dict]

Raises:

arango.exceptions.GraphListError – If retrieval fails.

has_collection(name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if collection exists in the database.

Parameters:

name (str) – Collection name.

Returns:

True if collection exists, False otherwise.

Return type:

bool

has_database(name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if a database exists.

Parameters:

name (str) – Database name.

Returns:

True if database exists, False otherwise.

Return type:

bool

has_document(document: Dict[str, Any], rev: str | None = None, check_rev: bool = True) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if a document exists.

Parameters:
  • document (str | dict) – Document ID or body with “_id” field.

  • rev (str | None) – Expected document revision. Overrides value of “_rev” field in document if present.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

Returns:

True if document exists, False otherwise.

Return type:

bool

Raises:
has_graph(name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if a graph exists in the database.

Parameters:

name (str) – Graph name.

Returns:

True if graph exists, False otherwise.

Return type:

bool

has_user(username: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if user exists.

Parameters:

username (str) – Username.

Returns:

True if user exists, False otherwise.

Return type:

bool

insert_document(collection: str, document: Dict[str, Any], return_new: bool = False, sync: bool | None = None, silent: bool = False, overwrite: bool = False, return_old: bool = False, overwrite_mode: str | None = None, keep_none: bool | None = None, merge: bool | None = None) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

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.

  • return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

  • overwrite (bool) – If set to True, operation does not fail on duplicate key and the existing document is replaced.

  • return_old (bool) – Include body of the old document if replaced. Applies only when value of overwrite is set to True.

  • overwrite_mode (str | None) – Overwrite behavior used when the document key exists already. Allowed values are “replace” (replace-insert) or “update” (update-insert). Implicitly sets the value of parameter overwrite.

  • keep_none (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 (bool | None) – If set to True (default), sub-dictionaries are merged instead of the new one overwriting the old one. Applies only when overwrite_mode is set to “update” (update-insert).

Returns:

Document metadata (e.g. document key, revision) or True if parameter silent was set to True.

Return type:

bool | dict

Raises:

arango.exceptions.DocumentInsertError – If insert fails.

jwt_secrets() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return information on currently loaded JWT secrets.

Returns:

Information on currently loaded JWT secrets.

Return type:

dict

license() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

View the license information and status of an Enterprise Edition instance. Can be called on single servers, Coordinators, and DB-Servers.

Returns:

Server license.

Return type:

dict

Raises:

arango.exceptions.ServerLicenseGetError – If retrieval fails.

list_transactions() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return the list of running stream transactions.

Returns:

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

Return type:

List[Dict[str, Any]]

Raises:

arango.exceptions.TransactionListError – If retrieval fails.

log_levels(server_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return current logging levels.

Parameters:

server_id (str) – Forward log level to a specific server. This makes it easier to adjust the log levels in clusters because DB-Servers require JWT authentication whereas Coordinators also support authentication using usernames and passwords.

Returns:

Current logging levels.

Return type:

dict

log_settings() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the structured log settings.

Returns:

Current log settings. False values are not returned.

Return type:

dict

metrics() str | AsyncJob[str] | BatchJob[str] | None

Return server metrics in Prometheus format.

Returns:

Server metrics in Prometheus format.

Return type:

str

mode() str | AsyncJob[str] | BatchJob[str] | None

Return the server mode (default or read-only)

In a read-only server, all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

Returns:

Server mode. Possible values are “default” or “readonly”.

Return type:

str

Raises:

arango.exceptions.ServerModeError – If retrieval fails.

property name: str

Return database name.

Returns:

Database name.

Return type:

str

permission(username: str, database: str, collection: str | None = None) str | AsyncJob[str] | BatchJob[str] | None

Return user permission for a specific database or collection.

Parameters:
  • username (str) – Username.

  • database (str) – Database name.

  • collection (str | None) – Collection name.

Returns:

Permission for given database or collection.

Return type:

str

Raises:

arango.exceptions.PermissionGetError – If retrieval fails.

permissions(username: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return user permissions for all databases and collections.

Parameters:

username (str) – Username.

Returns:

User permissions for all databases and collections.

Return type:

dict

Raises:

arango.exceptions.PermissionListError – If retrieval fails.

property pregel: Pregel

Return Pregel API wrapper.

Returns:

Pregel API wrapper.

Return type:

arango.pregel.Pregel

properties() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return database properties.

Returns:

Database properties.

Return type:

dict

Raises:

arango.exceptions.DatabasePropertiesError – If retrieval fails.

read_log(upto: int | str | None = None, level: int | str | None = None, start: int | None = None, size: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None
Read the global log from server. This method is deprecated

in ArangoDB 3.8 and will be removed in a future version of the driver. Use arango.database.Database.read_log_entries() instead.

Parameters:
  • upto (int | str) – Return the log entries up to the given level (mutually exclusive with parameter level). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • level (int | str) – Return the log entries of only the given level (mutually exclusive with upto). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • start (int) – Return the log entries whose ID is greater or equal to the given value.

  • size (int) – Restrict the size of the result to the given value. This can be used for pagination.

  • offset (int) – Number of entries to skip (e.g. for pagination).

  • search (str) – Return only the log entries containing the given text.

  • sort (str) – Sort the log entries according to the given fashion, which can be “sort” or “desc”.

Returns:

Server log entries.

Return type:

dict

Raises:

arango.exceptions.ServerReadLogError – If read fails.

read_log_entries(upto: int | str | None = None, level: int | str | None = None, start: int | None = None, size: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, server_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Read the global log from server.

Parameters:
  • upto (int | str) – Return the log entries up to the given level (mutually exclusive with parameter level). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • level (int | str) – Return the log entries of only the given level (mutually exclusive with upto). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • start (int) – Return the log entries whose ID is greater or equal to the given value.

  • size (int) – Restrict the size of the result to the given value. This can be used for pagination.

  • offset (int) – Number of entries to skip (e.g. for pagination).

  • search (str) – Return only the log entries containing the given text.

  • sort (str) – Sort the log entries according to the given fashion, which can be “sort” or “desc”.

  • server_id (str) – Returns all log entries of the specified server. All other query parameters remain valid. If no serverId is given, the asked server will reply. This parameter is only meaningful on Coordinators.

Returns:

Server log entries.

Return type:

dict

Raises:

arango.exceptions.ServerReadLogError – If read fails.

reload_jwt_secrets() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Hot-reload JWT secrets.

Calling this without payload reloads JWT secrets from disk. Only files specified via arangod startup option --server.jwt-secret-keyfile or --server.jwt-secret-folder are used. It is not possible to change the location where files are loaded from without restarting the server.

Returns:

Information on reloaded JWT secrets.

Return type:

dict

reload_routing() bool | AsyncJob[bool] | BatchJob[bool] | None

Reload the routing information.

Returns:

True if routing was reloaded successfully.

Return type:

bool

Raises:

arango.exceptions.ServerReloadRoutingError – If reload fails.

reload_tls() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Reload TLS data (server key, client-auth CA).

Returns:

New TLS data.

Return type:

dict

rename_view(name: str, new_name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Rename a view.

Parameters:
  • name (str) – View name.

  • new_name (str) – New view name.

Returns:

True if view was renamed successfully.

Return type:

bool

Raises:

arango.exceptions.ViewRenameError – If delete fails.

replace_arangosearch_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Replace an ArangoSearch view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

replace_document(document: Dict[str, Any], check_rev: bool = True, return_new: bool = False, return_old: bool = False, sync: bool | None = None, silent: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

Replace a document.

Parameters:
  • document (dict) – New document to replace the old one with. It must contain the “_id” field. Edge document must also have “_from” and “_to” fields.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

  • return_new (bool) – Include body of the new document in the result.

  • return_old (bool) – Include body of the old document in the result.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

Returns:

Document metadata (e.g. document key, revision) or True if parameter silent was set to True.

Return type:

bool | dict

Raises:
replace_user(username: str, password: str, active: bool | None = None, extra: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Replace a user.

Parameters:
  • username (str) – Username.

  • password (str) – New password.

  • active (bool | None) – Whether the user is active.

  • extra (dict | None) – Additional data for the user.

Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserReplaceError – If replace fails.

replace_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Replace a view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

property replication: Replication

Return Replication API wrapper.

Returns:

Replication API wrapper.

Return type:

arango.replication.Replication

required_db_version() str | AsyncJob[str] | BatchJob[str] | None

Return required version of target database.

Returns:

Required version of target database.

Return type:

str

Raises:

arango.exceptions.ServerRequiredDBVersionError – If retrieval fails.

reset_permission(username: str, database: str, collection: str | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Reset user permission for a specific database or collection.

Parameters:
  • username (str) – Username.

  • database (str) – Database name.

  • collection (str) – Collection name.

Returns:

True if permission was reset successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionRestError – If reset fails.

role() str | AsyncJob[str] | BatchJob[str] | None

Return server role.

Returns:

Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY”, “AGENT” (Agency node in a cluster) or “UNDEFINED”.

Return type:

str

Raises:

arango.exceptions.ServerRoleError – If retrieval fails.

run_tests(tests: Sequence[str]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Run available unittests on the server.

Parameters:

tests ([str]) – List of files containing the test suites.

Returns:

Test results.

Return type:

dict

Raises:

arango.exceptions.ServerRunTestsError – If execution fails.

set_license(license: str, force: bool = False) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Set a new license for an Enterprise Edition instance. Can be called on single servers, Coordinators, and DB-Servers.

Parameters:
  • license (str) – The Base64-encoded license string.

  • force (bool) – If set to True, the new license will be set even if it expires sooner than the current license.

Returns:

Server license.

Return type:

dict

Raises:

arango.exceptions.ServerLicenseError – If retrieval fails.

set_log_levels(server_id: str | None = None, **kwargs: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

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:

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

Keys that are not valid logger names are ignored.

Parameters:
  • server_id (str | None) – Forward log level to a specific server. This makes it easier to adjust the log levels in clusters because DB-Servers require JWT authentication whereas Coordinators also support authentication using usernames and passwords.

  • kwargs (Dict[str, Any]) – Logging levels.

Returns:

New logging levels.

Return type:

dict

set_log_settings(**kwargs: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

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.

arango.set_log_settings(
    database=True,
    url=True,
    username=False,
)
Parameters:

kwargs (Dict[str, Any]) – Structured log parameters.

Returns:

New log settings. False values are not returned.

Return type:

dict

set_mode(mode: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Set the server mode to read-only or default.

Update mode information about a server. The JSON response will contain a field mode with the value readonly or default. In a read-only server all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

This is a protected API. It requires authentication and administrative server rights.

Parameters:

mode (str) – Server mode. Possible values are “default” or “readonly”.

Returns:

Server mode.

Return type:

str

Raises:

arango.exceptions.ServerModeSetError – If set fails.

shutdown(soft: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Initiate server shutdown sequence.

Parameters:

soft (bool) – If set to true, this initiates a soft shutdown. This is only available on Coordinators. When issued, the Coordinator tracks a number of ongoing operations, waits until all have finished, and then shuts itself down normally. It will still accept new operations.

Returns:

True if the server was shutdown successfully.

Return type:

bool

Raises:

arango.exceptions.ServerShutdownError – If shutdown fails.

shutdown_progress() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None
Query the soft shutdown progress. This call reports progress about a

soft Coordinator shutdown (DELETE /_admin/shutdown?soft=true). This API is only available on Coordinators.

Returns:

Information about the shutdown progress.

Return type:

dict

Raises:

arango.exceptions.ServerShutdownError – If shutdown fails.

statistics(description: bool = False) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return server statistics.

Returns:

Server statistics.

Return type:

dict

Raises:

arango.exceptions.ServerStatisticsError – If retrieval fails.

status() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return ArangoDB server status.

Returns:

Server status.

Return type:

dict

Raises:

arango.exceptions.ServerStatusError – If retrieval fails.

support_info() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return information about the deployment.

Retrieves deployment information for support purposes. The endpoint returns data about the ArangoDB version used, the host (operating system, server ID, CPU and storage capacity, current utilization, a few metrics) and the other servers in the deployment (in case of Active Failover or cluster deployments).

NOTE: This method can only be accessed from inside the _system database. The is a policy control startup option –server.support-info-api that controls if and to whom the API is made available.

Returns:

Deployment information.

Return type:

dict

Raises:

arango.exceptions.DatabaseSupportInfoError – If retrieval fails.

task(task_id: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the details of an active server task.

Parameters:

task_id (str) – Server task ID.

Returns:

Server task details.

Return type:

dict

Raises:

arango.exceptions.TaskGetError – If retrieval fails.

tasks() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return all currently active server tasks.

Returns:

Currently active server tasks.

Return type:

[dict]

Raises:

arango.exceptions.TaskListError – If retrieval fails.

time() datetime | AsyncJob[datetime] | BatchJob[datetime] | None

Return server system time.

Returns:

Server system time.

Return type:

datetime.datetime

Raises:

arango.exceptions.ServerTimeError – If retrieval fails.

tls() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return TLS data (server key, client-auth CA).

Returns:

TLS data.

Return type:

dict

update_arangosearch_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Update an ArangoSearch view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

update_document(document: Dict[str, Any], check_rev: bool = True, merge: bool = True, keep_none: bool = True, return_new: bool = False, return_old: bool = False, sync: bool | None = None, silent: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

Update a document.

Parameters:
  • document (dict) – Partial or full document with the updated values. It must contain the “_id” field.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

  • merge (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.

  • keep_none (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.

  • return_new (bool) – Include body of the new document in the result.

  • return_old (bool) – Include body of the old document in the result.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

Returns:

Document metadata (e.g. document key, revision) or True if parameter silent was set to True.

Return type:

bool | dict

Raises:
update_permission(username: str, permission: str, database: str, collection: str | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Update user permission for a specific database or collection.

Parameters:
  • username (str) – Username.

  • permission (str) – Allowed values are “rw” (read and write), “ro” (read only) or “none” (no access).

  • database (str) – Database name.

  • collection (str | None) – Collection name.

Returns:

True if access was granted successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionUpdateError – If update fails.

update_user(username: str, password: str | None = None, active: bool | None = None, extra: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Update a user.

Parameters:
  • username (str) – Username.

  • password (str | None) – New password.

  • active (bool | None) – Whether the user is active.

  • extra (dict | None) – Additional data for the user.

Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserUpdateError – If update fails.

update_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Update a view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

user(username: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return user details.

Parameters:

username (str) – Username.

Returns:

User details.

Return type:

dict

Raises:

arango.exceptions.UserGetError – If retrieval fails.

property username: str | None

Return the username.

Returns:

Username.

Return type:

str

users() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return all user details.

Returns:

List of user details.

Return type:

[dict]

Raises:

arango.exceptions.UserListError – If retrieval fails.

version(details: bool = False) Any | AsyncJob[Any] | BatchJob[Any] | None

Return ArangoDB server version. :param details: Return more detailed version output :type details: bool | None :return: Server version. :rtype: str :raise arango.exceptions.ServerVersionError: If retrieval fails.

view(name: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the properties of a View.

Returns:

The View properties.

Return type:

dict

Raises:

arango.exceptions.ViewGetError – If retrieval fails.

view_info(name: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the id, name and type of a View.

Returns:

Some View information.

Return type:

dict

Raises:

arango.exceptions.ViewGetError – If retrieval fails.

views() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return list of views and their summaries.

Returns:

List of views.

Return type:

[dict]

Raises:

arango.exceptions.ViewListError – If retrieval fails.

property wal: WAL

Return WAL (Write-Ahead Log) API wrapper.

Returns:

WAL API wrapper.

Return type:

arango.wal.WAL

AsyncJob

class arango.job.AsyncJob(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, job_id: str, response_handler: Callable[[Response], T])[source]

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

Parameters:
  • connection – HTTP connection.

  • job_id (str) – Async job ID.

  • response_handler (callable) – HTTP response handler.

property id: str

Return the async job ID.

Returns:

Async job ID.

Return type:

str

status() str[source]

Return the async job status from server.

Once a job result is retrieved via func:arango.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), or “cancelled” (job was cancelled before completion).

Return type:

str

Raises:

arango.exceptions.AsyncJobStatusError – If retrieval fails.

result() T[source]

Return 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:
cancel(ignore_missing: bool = False) bool[source]

Cancel the async job.

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

Parameters:

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.AsyncJobCancelError – If cancel fails.

clear(ignore_missing: bool = False) bool[source]

Delete the job result from the server.

Parameters:

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.AsyncJobClearError – If delete fails.

AQL

class arango.aql.AQL(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, executor: DefaultApiExecutor | AsyncApiExecutor | BatchApiExecutor | TransactionApiExecutor | OverloadControlApiExecutor)[source]

AQL (ArangoDB Query Language) API wrapper.

Parameters:
  • connection – HTTP connection.

  • executor – API executor.

property cache: AQLQueryCache

Return the query cache API wrapper.

Returns:

Query cache API wrapper.

Return type:

arango.aql.AQLQueryCache

explain(query: str, all_plans: bool = False, max_plans: int | None = None, opt_rules: Sequence[str] | None = None, bind_vars: MutableMapping[str, bool | Number | str | None | Sequence[bool | Number | str | None | CompoundDataTypes] | MutableMapping[str, bool | Number | str | None | CompoundDataTypes]] | None = None) Dict[str, Any] | List[Dict[str, Any]] | AsyncJob[Dict[str, Any] | List[Dict[str, Any]]] | BatchJob[Dict[str, Any] | List[Dict[str, Any]]] | None[source]

Inspect the query and return its metadata without executing it.

Parameters:
  • query (str) – Query to inspect.

  • all_plans (bool) – If set to True, all possible execution plans are returned in the result. If set to False, only the optimal plan is returned.

  • max_plans (int) – Total number of plans generated by the optimizer.

  • opt_rules (list) – List of optimizer rules.

  • bind_vars (dict) – Bind variables for the query.

Returns:

Execution plan, or plans if all_plans was set to True.

Return type:

dict | list

Raises:

arango.exceptions.AQLQueryExplainError – If explain fails.

validate(query: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Parse and validate the query without executing it.

Parameters:

query (str) – Query to validate.

Returns:

Query details.

Return type:

dict

Raises:

arango.exceptions.AQLQueryValidateError – If validation fails.

execute(query: str, count: bool = False, batch_size: int | None = None, ttl: Number | None = None, bind_vars: MutableMapping[str, bool | Number | str | None | Sequence[bool | Number | str | None | CompoundDataTypes] | MutableMapping[str, bool | Number | str | None | CompoundDataTypes]] | None = None, full_count: bool | None = None, max_plans: int | None = None, optimizer_rules: Sequence[str] | None = None, cache: bool | None = None, memory_limit: int = 0, fail_on_warning: bool | None = None, profile: bool | None = None, max_transaction_size: int | None = None, max_warning_count: int | None = None, intermediate_commit_count: int | None = None, intermediate_commit_size: int | None = None, satellite_sync_wait: int | None = None, stream: bool | None = None, skip_inaccessible_cols: bool | None = None, max_runtime: Number | None = None, fill_block_cache: bool | None = None, allow_dirty_read: bool = False, allow_retry: bool = False, force_one_shard_attribute_value: str | None = None) Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None[source]

Execute the query and return the result cursor.

Parameters:
  • query (str) – Query to execute.

  • count (bool) – If set to True, the total document count is included in the result cursor.

  • batch_size (int) – Number of documents fetched by the cursor in one round trip.

  • ttl (int) – Server side time-to-live for the cursor in seconds.

  • bind_vars (dict) – Bind variables for the query.

  • full_count (bool) – This parameter applies only to queries with LIMIT clauses. If set to True, the number of matched documents before the last LIMIT clause executed is included in the cursor. This is similar to MySQL SQL_CALC_FOUND_ROWS hint. Using this disables a few LIMIT optimizations and may lead to a longer query execution.

  • max_plans (int) – Max number of plans the optimizer generates.

  • optimizer_rules ([str]) – List of optimizer rules.

  • cache (bool) – If set to True, the query cache is used. The operation mode of the query cache must be set to “on” or “demand”.

  • memory_limit (int) – Max amount of memory the query is allowed to use in bytes. If the query goes over the limit, it fails with error “resource limit exceeded”. Value 0 indicates no limit.

  • fail_on_warning (bool) – If set to True, the query throws an exception instead of producing a warning. This parameter can be used during development to catch issues early. If set to False, warnings are returned with the query result. There is a server configuration option “–query.fail-on-warning” for setting the default value for this behaviour, so it does not need to be set per-query.

  • profile (bool) – Return additional profiling details in the cursor, unless the query cache is used.

  • max_transaction_size (int) – Transaction size limit in bytes.

  • max_warning_count (int) – Max number of warnings returned.

  • intermediate_commit_count (int) – Max number of operations after which an intermediate commit is performed automatically.

  • intermediate_commit_size (int) – Max size of operations in bytes after which an intermediate commit is performed automatically.

  • satellite_sync_wait (int | float) – Number of seconds in which the server must synchronize the satellite collections involved in the query. When the threshold is reached, the query is stopped. Available only for enterprise version of ArangoDB.

  • stream (bool) – If set to True, query is executed in streaming fashion: query result is not stored server-side but calculated on the fly. Note: long-running queries hold collection locks for as long as the cursor exists. If set to False, query is executed right away in its entirety. Results are either returned right away (if the result set is small enough), or stored server-side and accessible via cursors (while respecting the ttl). You should use this parameter only for short-running queries or without exclusive locks. Note: parameters cache, count and full_count do not work for streaming queries. Query statistics, warnings and profiling data are made available only after the query is finished. Default value is False.

  • skip_inaccessible_cols (bool) – If set to True, collections without user access are skipped, and query executes normally instead of raising an error. This helps certain use cases: a graph may contain several collections, and users with different access levels may execute the same query. This parameter lets you limit the result set by user access. Cannot be used in transactions and is available only for enterprise version of ArangoDB. Default value is False.

  • max_runtime (int | float) – Query must be executed within this given timeout or it is killed. The value is specified in seconds. Default value is 0.0 (no timeout).

  • fill_block_cache (bool) – If set to true or not specified, this will make the query store the data it reads via the RocksDB storage engine in the RocksDB block cache. This is usually the desired behavior. The option can be set to false for queries that are known to either read a lot of data which would thrash the block cache, or for queries that read data which are known to be outside of the hot set. By setting the option to false, data read by the query will not make it into the RocksDB block cache if not already in there, thus leaving more room for the actual hot set.

  • allow_dirty_read (bool | None) – Allow reads from followers in a cluster.

  • allow_retry (bool) – Make it possible to retry fetching the latest batch from a cursor.

  • force_one_shard_attribute_value – (Enterprise Only) Explicitly set a shard key value that will be used during query snippet distribution to limit the query to a specific server in the cluster. This query option can be used in complex queries in case the query optimizer cannot automatically detect that the query can be limited to only a single server (e.g. in a disjoint smart graph case). If the option is set incorrectly, i.e. to a wrong shard key value, then the query may be shipped to a wrong DB server and may not return results (i.e. empty result set). Use at your own risk.

  • force_one_shard_attribute_value – str | None

Returns:

Result cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.AQLQueryExecuteError – If execute fails.

kill(query_id: str) bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Kill a running query.

Parameters:

query_id (str) – Query ID.

Returns:

True if kill request was sent successfully.

Return type:

bool

Raises:

arango.exceptions.AQLQueryKillError – If the send fails.

queries() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return the currently running AQL queries.

Returns:

Running AQL queries.

Return type:

[dict]

Raises:

arango.exceptions.AQLQueryListError – If retrieval fails.

slow_queries() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return a list of all slow AQL queries.

Returns:

Slow AQL queries.

Return type:

[dict]

Raises:

arango.exceptions.AQLQueryListError – If retrieval fails.

clear_slow_queries() bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Clear slow AQL queries.

Returns:

True if slow queries were cleared successfully.

Return type:

bool

Raises:

arango.exceptions.AQLQueryClearError – If operation fails.

tracking() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return AQL query tracking properties.

Returns:

AQL query tracking properties.

Return type:

dict

Raises:

arango.exceptions.AQLQueryTrackingGetError – If retrieval fails.

set_tracking(enabled: bool | None = None, max_slow_queries: int | None = None, slow_query_threshold: int | None = None, max_query_string_length: int | None = None, track_bind_vars: bool | None = None, track_slow_queries: bool | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Configure AQL query tracking properties

Parameters:
  • enabled (bool) – Track queries if set to True.

  • max_slow_queries (int) – Max number of slow queries to track. Oldest entries are discarded first.

  • slow_query_threshold (int) – Runtime threshold (in seconds) for treating a query as slow.

  • max_query_string_length (int) – Max query string length (in bytes) tracked.

  • track_bind_vars (bool) – If set to True, track bind variables used in queries.

  • track_slow_queries (bool) – If set to True, track slow queries whose runtimes exceed slow_query_threshold. To use this, parameter enabled must be set to True.

Returns:

Updated AQL query tracking properties.

Return type:

dict

Raises:

arango.exceptions.AQLQueryTrackingSetError – If operation fails.

functions() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

List the AQL functions defined in the database.

Returns:

AQL functions.

Return type:

[dict]

Raises:

arango.exceptions.AQLFunctionListError – If retrieval fails.

create_function(name: str, code: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Create a new AQL function.

Parameters:
  • name (str) – AQL function name.

  • code (str) – Function definition in Javascript.

Returns:

Whether the AQL function was newly created or an existing one was replaced.

Return type:

dict

Raises:

arango.exceptions.AQLFunctionCreateError – If create fails.

delete_function(name: str, group: bool = False, ignore_missing: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None[source]

Delete an AQL function.

Parameters:
  • name (str) – AQL function name.

  • group (bool) – If set to True, value of parameter name is treated as a namespace prefix, and all functions in the namespace are deleted. If set to False, the value of name must be a fully qualified function name including any namespaces.

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

Returns:

Number of AQL functions deleted if operation was successful, False if function(s) was not found and ignore_missing was set to True.

Return type:

dict | bool

Raises:

arango.exceptions.AQLFunctionDeleteError – If delete fails.

query_rules() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return the available optimizer rules for AQL queries

Returns:

The available optimizer rules for AQL queries

Return type:

dict

Raises:

arango.exceptions.AQLQueryRulesGetError – If retrieval fails.

AQLQueryCache

class arango.aql.AQLQueryCache(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, executor: DefaultApiExecutor | AsyncApiExecutor | BatchApiExecutor | TransactionApiExecutor | OverloadControlApiExecutor)[source]

AQL Query Cache API wrapper.

properties() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the query cache properties.

Returns:

Query cache properties.

Return type:

dict

Raises:

arango.exceptions.AQLCachePropertiesError – If retrieval fails.

configure(mode: str | None = None, max_results: int | None = None, max_results_size: int | None = None, max_entry_size: int | None = None, include_system: bool | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Configure the query cache properties.

Parameters:
  • mode (str) – Operation mode. Allowed values are “off”, “on” and “demand”.

  • max_results (int) – Max number of query results stored per database-specific cache.

  • max_results_size (int) – Max cumulative size of query results stored per database-specific cache.

  • max_entry_size (int) – Max entry size of each query result stored per database-specific cache.

  • include_system (bool) – Store results of queries in system collections.

Returns:

Query cache properties.

Return type:

dict

Raises:

arango.exceptions.AQLCacheConfigureError – If operation fails.

entries() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return the query cache entries.

Returns:

Query cache entries.

Return type:

[dict]

Raises:

AQLCacheEntriesError – If retrieval fails.

clear() bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Clear the query cache.

Returns:

True if query cache was cleared successfully.

Return type:

bool

Raises:

arango.exceptions.AQLCacheClearError – If operation fails.

Backup

class arango.backup.Backup(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, executor: DefaultApiExecutor | AsyncApiExecutor | BatchApiExecutor | TransactionApiExecutor | OverloadControlApiExecutor)[source]
get(backup_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return backup details.

Parameters:

backup_id (str) – If set, details on only the specified backup is returned. Otherwise, details on all backups are returned.

Returns:

Backup details.

Return type:

dict

Raises:

arango.exceptions.BackupGetError – If delete fails.

create(label: str | None = None, allow_inconsistent: bool | None = None, force: bool | None = None, timeout: Number | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

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

Parameters:
  • label (str) – Backup label. If not given, a UUID is used.

  • allow_inconsistent (bool) – Allow inconsistent backup when the global transaction lock cannot be acquired before timeout. Default value is False.

  • force (bool) – 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 (int) – Timeout in seconds for creating the backup. Default value is 120 seconds.

Returns:

Result of the create operation.

Return type:

dict

Raises:

arango.exceptions.BackupCreateError – If create fails.

delete(backup_id: str) bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Delete a backup.

Parameters:

backup_id (str) – Backup ID.

Returns:

True if the backup was deleted successfully.

Return type:

bool

Raises:

arango.exceptions.BackupDeleteError – If delete fails.

download(backup_id: str | None = None, repository: str | None = None, abort: bool | None = None, config: Dict[str, Any] | None = None, download_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Manage backup downloads.

Parameters:
  • backup_id (str) – Backup ID used for scheduling a download. Mutually exclusive with parameter download_id.

  • repository (str) – Remote repository URL (e.g. “local://tmp/backups”). Required for scheduling a download and mutually exclusive with parameter download_id.

  • abort (bool) – If set to True, running download is aborted. Used with parameter download_id.

  • config (dict) – Remote repository configuration. Required for scheduling a download and mutually exclusive with parameter download_id.

  • download_id (str) – Download ID. Mutually exclusive with parameters backup_id, repository, and config.

Returns:

Download details.

Return type:

dict

Raises:

arango.exceptions.BackupDownloadError – If operation fails.

upload(backup_id: str | None = None, repository: str | None = None, abort: bool | None = None, config: Dict[str, Any] | None = None, upload_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Manage backup uploads.

Parameters:
  • backup_id (str) – Backup ID used for scheduling an upload. Mutually exclusive with parameter upload_id.

  • repository (str) – Remote repository URL (e.g. “local://tmp/backups”). Required for scheduling a upload and mutually exclusive with parameter upload_id.

  • config (dict) – Remote repository configuration. Required for scheduling an upload and mutually exclusive with parameter upload_id.

  • upload_id (str) – Upload ID. Mutually exclusive with parameters backup_id, repository, and config.

  • abort (bool) – If set to True, running upload is aborted. Used with parameter upload_id.

Returns:

Upload details.

Return type:

dict

Raises:

arango.exceptions.BackupUploadError – If upload operation fails.

restore(backup_id: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Restore from a local backup.

Parameters:

backup_id (str) – Backup ID.

Returns:

Result of the restore operation.

Return type:

dict

Raises:

arango.exceptions.BackupRestoreError – If restore fails.

property conn: BasicConnection | JwtConnection | JwtSuperuserConnection

Return the HTTP connection.

Returns:

HTTP connection.

Return type:

arango.connection.BasicConnection | arango.connection.JwtConnection | arango.connection.JwtSuperuserConnection

property context: str

Return the API execution context.

Returns:

API execution context. Possible values are “default”, “async”, “batch” and “transaction”.

Return type:

str

property db_name: str

Return the name of the current database.

Returns:

Database name.

Return type:

str

property username: str | None

Return the username.

Returns:

Username.

Return type:

str

BatchDatabase

class arango.database.BatchDatabase(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, return_result: bool, max_workers: int | None)[source]

Database API wrapper tailored specifically for batch execution.

Note

This class is not intended to be instantiated directly. See arango.database.StandardDatabase.begin_batch_execution().

Parameters:
  • connection – HTTP connection.

  • return_result (bool) – If set to True, API executions return instances of arango.job.BatchJob that are populated with results on commit. If set to False, API executions return None and no results are tracked client-side.

  • max_workers (Optional[int]) – Use a thread pool of at most max_workers.

queued_jobs() Sequence[BatchJob[Any]] | None[source]

Return the queued batch jobs.

Returns:

Queued batch jobs or None if return_result parameter was set to False during initialization.

Return type:

[arango.job.BatchJob] | None

commit() Sequence[BatchJob[Any]] | None[source]

Execute the queued requests in a single batch API request.

If return_result parameter was set to True during initialization, arango.job.BatchJob instances are populated with results.

Returns:

Batch jobs, or None if return_result parameter was set to False during initialization.

Return type:

[arango.job.BatchJob] | None

Raises:
analyzer(name: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return analyzer details.

Parameters:

name (str) – Analyzer name.

Returns:

Analyzer details.

Return type:

dict

Raises:

arango.exceptions.AnalyzerGetError – If retrieval fails.

analyzers() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return list of analyzers.

Returns:

List of analyzers.

Return type:

[dict]

Raises:

arango.exceptions.AnalyzerListError – If retrieval fails.

property aql: AQL

Return AQL (ArangoDB Query Language) API wrapper.

Returns:

AQL API wrapper.

Return type:

arango.aql.AQL

async_jobs(status: str, count: int | None = None) List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None

Return IDs of async jobs with given status.

Parameters:
  • status (str) – Job status (e.g. “pending”, “done”).

  • count (int) – Max number of job IDs to return.

Returns:

List of job IDs.

Return type:

[str]

Raises:

arango.exceptions.AsyncJobListError – If retrieval fails.

property backup: Backup

Return Backup API wrapper.

Returns:

Backup API wrapper.

Return type:

arango.backup.Backup

clear_async_jobs(threshold: int | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Clear async job results from the server.

Async jobs that are still queued or running are not stopped.

Parameters:

threshold (int | None) – If specified, only the job results created prior to the threshold (a unix timestamp) are deleted. Otherwise, all job results are deleted.

Returns:

True if job results were cleared successfully.

Return type:

bool

Raises:

arango.exceptions.AsyncJobClearError – If operation fails.

property cluster: Cluster

Return Cluster API wrapper.

Returns:

Cluster API wrapper.

Return type:

arango.cluster.Cluster

collection(name: str) StandardCollection

Return the standard collection API wrapper.

Parameters:

name (str) – Collection name.

Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

collections() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return the collections in the database.

Returns:

Collections in the database and their details.

Return type:

[dict]

Raises:

arango.exceptions.CollectionListError – If retrieval fails.

compact(change_level: bool | None = None, compact_bottom_most_level: bool | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Compact all databases.

NOTE: This command can cause a full rewrite of all data in all databases, which may take very long for large databases. It should thus only be used with care and only when additional I/O load can be tolerated for a prolonged time.

This method can be used to reclaim disk space after substantial data deletions have taken place, by compacting the entire database system data.

This method requires superuser access.

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:

Collection compact.

Return type:

dict

Raises:

arango.exceptions.CollectionCompactError – If retrieval fails.

property conn: BasicConnection | JwtConnection | JwtSuperuserConnection

Return the HTTP connection.

Returns:

HTTP connection.

Return type:

arango.connection.BasicConnection | arango.connection.JwtConnection | arango.connection.JwtSuperuserConnection

property context: str

Return the API execution context.

Returns:

API execution context. Possible values are “default”, “async”, “batch” and “transaction”.

Return type:

str

create_analyzer(name: str, analyzer_type: str, properties: Dict[str, Any] | None = None, features: Sequence[str] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create an analyzer.

Parameters:
  • name (str) – Analyzer name.

  • analyzer_type (str) – Analyzer type.

  • properties (dict | None) – Analyzer properties.

  • features (list | None) – Analyzer features.

Returns:

Analyzer details.

Return type:

dict

Raises:

arango.exceptions.AnalyzerCreateError – If create fails.

create_arangosearch_view(name: str, properties: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create an ArangoSearch view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

create_collection(name: str, sync: bool = False, system: bool = False, edge: bool = False, user_keys: bool = True, key_increment: int | None = None, key_offset: int | None = None, key_generator: str = 'traditional', shard_fields: Sequence[str] | None = None, shard_count: int | None = None, replication_factor: int | None = None, shard_like: str | None = None, sync_replication: bool | None = None, enforce_replication_factor: bool | None = None, sharding_strategy: str | None = None, smart_join_attribute: str | None = None, write_concern: int | None = None, schema: Dict[str, Any] | None = None, computedValues: List[Dict[str, Any]] | None = None) StandardCollection | AsyncJob[StandardCollection] | BatchJob[StandardCollection] | None

Create a new collection.

Parameters:
  • name (str) – Collection name.

  • sync (bool | None) – If set to True, document operations via the collection will block until synchronized to disk by default.

  • system (bool) – If set to True, a system collection is created. The collection name must have leading underscore “_” character.

  • edge (bool) – If set to True, an edge collection is created.

  • key_generator (str) – Used for generating document keys. Allowed values are “traditional” or “autoincrement”.

  • user_keys (bool) – If set to True, users are allowed to supply document keys. If set to False, the key generator is solely responsible for supplying the key values.

  • key_increment (int) – Key increment value. Applies only when value of key_generator is set to “autoincrement”.

  • key_offset (int) – Key offset value. Applies only when value of key_generator is set to “autoincrement”.

  • shard_fields ([str]) – Field(s) used to determine the target shard.

  • shard_count (int) – Number of shards to create.

  • replication_factor (int) – Number of copies of each shard on different servers in a cluster. Allowed values are 1 (only one copy is kept and no synchronous replication), and n (n-1 replicas are kept and any two copies are replicated across servers synchronously, meaning every write to the master is copied to all slaves before operation is reported successful).

  • shard_like (str) – Name of prototype collection whose sharding specifics are imitated. Prototype collections cannot be dropped before imitating collections. Applies to enterprise version of ArangoDB only.

  • sync_replication (bool) – If set to True, server reports success only when collection is created in all replicas. You can set this to False for faster server response, and if full replication is not a concern.

  • enforce_replication_factor (bool) – Check if there are enough replicas available at creation time, or halt the operation.

  • sharding_strategy (str) – Sharding strategy. Available for ArangoDB version and up only. Possible values are “community-compat”, “enterprise-compat”, “enterprise-smart-edge-compat”, “hash” and “enterprise-hash-smart-edge”. Refer to ArangoDB documentation for more details on each value.

  • smart_join_attribute (str) – Attribute of the collection which must contain the shard key value of the smart join collection. The shard key for the documents must contain the value of this attribute, followed by a colon “:” and the primary key of the document. Requires parameter shard_like to be set to the name of another collection, and parameter shard_fields to be set to a single shard key attribute, with another colon “:” at the end. Available only for enterprise version of ArangoDB.

  • write_concern (int) – Write concern for the collection. Determines how many copies of each shard are required to be in sync on different DBServers. 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. The value of this parameter cannot be larger than that of replication_factor. Default value is 1. Used for clusters only.

  • schema (dict) – Optional dict specifying the collection level schema for documents. See ArangoDB documentation for more information on document schema validation.

  • computedValues (list) – Array of computed values for the new collection enabling default values to new documents or the maintenance of auxiliary attributes for search queries. Available in ArangoDB version 3.10 or greater. See ArangoDB documentation for more information on computed values.

Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

Raises:

arango.exceptions.CollectionCreateError – If create fails.

create_database(name: str, users: Sequence[Dict[str, Any]] | None = None, replication_factor: int | str | None = None, write_concern: int | None = None, sharding: str | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Create a new database.

Parameters:
  • name (str) – Database name.

  • users ([dict]) – List of users with access to the new database, where each user is a dictionary with fields “username”, “password”, “active” and “extra” (see below for example). If not set, only the admin and current user are granted access.

  • replication_factor (int | str) – Default replication factor for collections created in this database. Special values include “satellite” which replicates the collection to every DBServer, and 1 which disables replication. Used for clusters only.

  • write_concern (int) – Default write concern for collections created in this database. Determines how many copies of each shard are required to be in sync on different DBServers. 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) – 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 database was created successfully.

Return type:

bool

Raises:

arango.exceptions.DatabaseCreateError – If create fails.

Here is an example entry for parameter users:

{
    'username': 'john',
    'password': 'password',
    'active': True,
    'extra': {'Department': 'IT'}
}
create_graph(name: str, edge_definitions: Sequence[Dict[str, Any]] | None = None, orphan_collections: Sequence[str] | None = None, smart: bool | None = None, disjoint: bool | None = None, smart_field: str | None = None, shard_count: int | None = None, replication_factor: int | None = None, write_concern: int | None = None) Graph | AsyncJob[Graph] | BatchJob[Graph] | None

Create a new graph.

Parameters:
  • name (str) – Graph name.

  • edge_definitions ([dict] | None) – List of edge definitions, where each edge definition entry is a dictionary with fields “edge_collection”, “from_vertex_collections” and “to_vertex_collections” (see below for example).

  • orphan_collections ([str] | None) – Names of additional vertex collections that are not in edge definitions.

  • smart (bool | None) – If set to True, sharding is enabled (see parameter smart_field below). Applies only to enterprise version of ArangoDB.

  • disjoint (bool | None) – If set to True, create a disjoint SmartGraph instead of a regular SmartGraph. Applies only to enterprise version of ArangoDB.

  • smart_field (str | None) – Document field used to shard the vertices of the graph. To use this, parameter smart must be set to True and every vertex in the graph must have the smart field. Applies only to enterprise version of ArangoDB.

  • shard_count (int | None) – Number of shards used for every collection in the graph. To use this, parameter smart must be set to True and every vertex in the graph must have the smart field. This number cannot be modified later once set. Applies only to enterprise version of ArangoDB.

  • replication_factor (int) – Number of copies of each shard on different servers in a cluster. Allowed values are 1 (only one copy is kept and no synchronous replication), and n (n-1 replicas are kept and any two copies are replicated across servers synchronously, meaning every write to the master is copied to all slaves before operation is reported successful).

  • write_concern (int) – Write concern for the collection. Determines how many copies of each shard are required to be in sync on different DBServers. 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. The value of this parameter cannot be larger than that of replication_factor. Default value is 1. Used for clusters only.

Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

Raises:

arango.exceptions.GraphCreateError – If create fails.

Here is an example entry for parameter edge_definitions:

[
    {
        'edge_collection': 'teach',
        'from_vertex_collections': ['teachers'],
        'to_vertex_collections': ['lectures']
    }
]
create_task(name: str, command: str, params: Dict[str, Any] | None = None, period: int | None = None, offset: int | None = None, task_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create a new server task.

Parameters:
  • name (str) – Name of the server task.

  • command (str) – Javascript command to execute.

  • params (dict | None) – Optional parameters passed into the Javascript command.

  • period (int | None) – Number of seconds to wait between executions. If set to 0, the new task will be “timed”, meaning it will execute only once and be deleted afterwards.

  • offset (int | None) – Initial delay before execution in seconds.

  • task_id (str | None) – Pre-defined ID for the new server task.

Returns:

Details of the new task.

Return type:

dict

Raises:

arango.exceptions.TaskCreateError – If create fails.

create_user(username: str, password: str | None = None, active: bool | None = None, extra: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create a new user.

Parameters:
  • username (str) – Username.

  • password (str | None) – Password.

  • active (bool | None) – True if user is active, False otherwise.

  • extra (dict | None) – Additional data for the user.

Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserCreateError – If create fails.

create_view(name: str, view_type: str, properties: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Create a view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

databases() List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None

Return the names of all databases.

Returns:

Database names.

Return type:

[str]

Raises:

arango.exceptions.DatabaseListError – If retrieval fails.

databases_accessible_to_user() List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None

Return the names of all databases accessible by the user.

Returns:

Database names accesible by the current user.

Return type:

List[str]

Raises:

arango.exceptions.DatabaseListError – If retrieval fails.

property db_name: str

Return the name of the current database.

Returns:

Database name.

Return type:

str

delete_analyzer(name: str, force: bool = False, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete an analyzer.

Parameters:
  • name (str) – Analyzer name.

  • force (bool) – Remove the analyzer configuration even if in use.

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.AnalyzerDeleteError – If delete fails.

delete_collection(name: str, ignore_missing: bool = False, system: bool | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete the collection.

Parameters:
  • name (str) – Collection name.

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

  • system (bool) – Whether the collection is a system collection.

Returns:

True if collection was deleted successfully, False if collection was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.CollectionDeleteError – If delete fails.

delete_database(name: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete the database.

Parameters:
  • name (str) – Database name.

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

Returns:

True if database was deleted successfully, False if database was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.DatabaseDeleteError – If delete fails.

delete_document(document: str | Dict[str, Any], rev: str | None = None, check_rev: bool = True, ignore_missing: bool = False, return_old: bool = False, sync: bool | None = None, silent: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

Delete a document.

Parameters:
  • document (str | dict) – Document ID, key or body. Document body must contain the “_id” field.

  • rev (str | None) – Expected document revision. Overrides the value of “_rev” field in document if present.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

  • 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.

  • return_old (bool) – Include body of the old document in the result.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

Returns:

Document metadata (e.g. document key, revision), or True if parameter silent was set to True, or False if document was not found and ignore_missing was set to True (does not apply in transactions).

Return type:

bool | dict

Raises:
delete_graph(name: str, ignore_missing: bool = False, drop_collections: bool | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Drop the graph of the given name from the database.

Parameters:
  • name (str) – Graph name.

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

  • drop_collections (bool | None) – Drop the collections of the graph also. This is only if they are not in use by other graphs.

Returns:

True if graph was deleted successfully, False if graph was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.GraphDeleteError – If delete fails.

delete_task(task_id: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete a server task.

Parameters:
  • task_id (str) – Server task ID.

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.TaskDeleteError – If delete fails.

delete_user(username: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete a user.

Parameters:
  • username (str) – Username.

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

Returns:

True if user was deleted successfully, False if user was not found and ignore_missing was set to True.

Return type:

bool

Raises:

arango.exceptions.UserDeleteError – If delete fails.

delete_view(name: str, ignore_missing: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Delete a view.

Parameters:
  • name (str) – View name.

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

Returns:

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

Return type:

bool

Raises:

arango.exceptions.ViewDeleteError – If delete fails.

details() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return ArangoDB server details.

Returns:

Server details.

Return type:

dict

Raises:

arango.exceptions.ServerDetailsError – If retrieval fails.

document(document: Dict[str, Any], rev: str | None = None, check_rev: bool = True) Dict[str, Any] | None | AsyncJob[Dict[str, Any] | None] | BatchJob[Dict[str, Any] | None]

Return a document.

Parameters:
  • document (str | dict) – Document ID or body with “_id” field.

  • rev (str | None) – Expected document revision. Overrides the value of “_rev” field in document if present.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

Returns:

Document, or None if not found.

Return type:

dict | None

Raises:
echo(body: Any | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return details of the last request (e.g. headers, payload), or echo the given request body.

Parameters:

body (dict | list | str | int | float | None) – The body of the request. Can be of any type and is simply forwarded. If not set, the details of the last request are returned.

Returns:

Details of the last request.

Return type:

dict

Raises:

arango.exceptions.ServerEchoError – If retrieval fails.

encryption() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Rotate the user-supplied keys for encryption.

This method is available only for enterprise edition of ArangoDB.

Returns:

New TLS data.

Return type:

dict

Raises:

arango.exceptions.ServerEncryptionError – If retrieval fails.

engine() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the database engine details.

Returns:

Database engine details.

Return type:

dict

Raises:

arango.exceptions.ServerEngineError – If retrieval fails.

execute(command: str) Any | AsyncJob[Any] | BatchJob[Any] | None

Execute raw Javascript command on the server.

Executes the JavaScript code in the body on the server as the body of a function with no arguments. If you have a return statement then the return value you produce will be returned as ‘application/json’.

NOTE: this method endpoint will only be usable if the server was started with the option –javascript.allow-admin-execute true. The default value of this option is false, which disables the execution of user-defined code and disables this API endpoint entirely. This is also the recommended setting for production.

Parameters:

command (str) – Javascript command to execute.

Returns:

Return value of command, if any.

Return type:

Any

Raises:

arango.exceptions.ServerExecuteError – If execution fails.

execute_transaction(command: str, params: Dict[str, Any] | None = None, read: Sequence[str] | None = None, write: Sequence[str] | None = None, sync: bool | None = None, timeout: Number | None = None, max_size: int | None = None, allow_implicit: bool | None = None, intermediate_commit_count: int | None = None, intermediate_commit_size: int | None = None, allow_dirty_read: bool = False) Any | AsyncJob[Any] | BatchJob[Any] | None

Execute raw Javascript command in transaction.

Parameters:
  • command (str) – Javascript command to execute.

  • read ([str] | None) – Names of collections read during transaction. If parameter allow_implicit is set to True, any undeclared read collections are loaded lazily.

  • write ([str] | None) – Names of collections written to during transaction. Transaction fails on undeclared write collections.

  • params (dict | None) – Optional parameters passed into the Javascript command.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • timeout (int | None) – Timeout for waiting on collection locks. If set to 0, ArangoDB server waits indefinitely. If not set, system default value is used.

  • max_size (int | None) – Max transaction size limit in bytes.

  • allow_implicit (bool | None) – If set to True, undeclared read collections are loaded lazily. If set to False, transaction fails on any undeclared collections.

  • intermediate_commit_count (int | None) – Max number of operations after which an intermediate commit is performed automatically.

  • intermediate_commit_size (int | None) – Max size of operations in bytes after which an intermediate commit is performed automatically.

  • allow_dirty_read (bool | None) – Allow reads from followers in a cluster.

Returns:

Return value of command.

Return type:

Any

Raises:

arango.exceptions.TransactionExecuteError – If execution fails.

property foxx: Foxx

Return Foxx API wrapper.

Returns:

Foxx API wrapper.

Return type:

arango.foxx.Foxx

graph(name: str) Graph

Return the graph API wrapper.

Parameters:

name (str) – Graph name.

Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

graphs() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

List all graphs in the database.

Returns:

Graphs in the database.

Return type:

[dict]

Raises:

arango.exceptions.GraphListError – If retrieval fails.

has_collection(name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if collection exists in the database.

Parameters:

name (str) – Collection name.

Returns:

True if collection exists, False otherwise.

Return type:

bool

has_database(name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if a database exists.

Parameters:

name (str) – Database name.

Returns:

True if database exists, False otherwise.

Return type:

bool

has_document(document: Dict[str, Any], rev: str | None = None, check_rev: bool = True) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if a document exists.

Parameters:
  • document (str | dict) – Document ID or body with “_id” field.

  • rev (str | None) – Expected document revision. Overrides value of “_rev” field in document if present.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

Returns:

True if document exists, False otherwise.

Return type:

bool

Raises:
has_graph(name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if a graph exists in the database.

Parameters:

name (str) – Graph name.

Returns:

True if graph exists, False otherwise.

Return type:

bool

has_user(username: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Check if user exists.

Parameters:

username (str) – Username.

Returns:

True if user exists, False otherwise.

Return type:

bool

insert_document(collection: str, document: Dict[str, Any], return_new: bool = False, sync: bool | None = None, silent: bool = False, overwrite: bool = False, return_old: bool = False, overwrite_mode: str | None = None, keep_none: bool | None = None, merge: bool | None = None) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

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.

  • return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

  • overwrite (bool) – If set to True, operation does not fail on duplicate key and the existing document is replaced.

  • return_old (bool) – Include body of the old document if replaced. Applies only when value of overwrite is set to True.

  • overwrite_mode (str | None) – Overwrite behavior used when the document key exists already. Allowed values are “replace” (replace-insert) or “update” (update-insert). Implicitly sets the value of parameter overwrite.

  • keep_none (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 (bool | None) – If set to True (default), sub-dictionaries are merged instead of the new one overwriting the old one. Applies only when overwrite_mode is set to “update” (update-insert).

Returns:

Document metadata (e.g. document key, revision) or True if parameter silent was set to True.

Return type:

bool | dict

Raises:

arango.exceptions.DocumentInsertError – If insert fails.

jwt_secrets() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return information on currently loaded JWT secrets.

Returns:

Information on currently loaded JWT secrets.

Return type:

dict

license() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

View the license information and status of an Enterprise Edition instance. Can be called on single servers, Coordinators, and DB-Servers.

Returns:

Server license.

Return type:

dict

Raises:

arango.exceptions.ServerLicenseGetError – If retrieval fails.

list_transactions() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return the list of running stream transactions.

Returns:

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

Return type:

List[Dict[str, Any]]

Raises:

arango.exceptions.TransactionListError – If retrieval fails.

log_levels(server_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return current logging levels.

Parameters:

server_id (str) – Forward log level to a specific server. This makes it easier to adjust the log levels in clusters because DB-Servers require JWT authentication whereas Coordinators also support authentication using usernames and passwords.

Returns:

Current logging levels.

Return type:

dict

log_settings() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the structured log settings.

Returns:

Current log settings. False values are not returned.

Return type:

dict

metrics() str | AsyncJob[str] | BatchJob[str] | None

Return server metrics in Prometheus format.

Returns:

Server metrics in Prometheus format.

Return type:

str

mode() str | AsyncJob[str] | BatchJob[str] | None

Return the server mode (default or read-only)

In a read-only server, all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

Returns:

Server mode. Possible values are “default” or “readonly”.

Return type:

str

Raises:

arango.exceptions.ServerModeError – If retrieval fails.

property name: str

Return database name.

Returns:

Database name.

Return type:

str

permission(username: str, database: str, collection: str | None = None) str | AsyncJob[str] | BatchJob[str] | None

Return user permission for a specific database or collection.

Parameters:
  • username (str) – Username.

  • database (str) – Database name.

  • collection (str | None) – Collection name.

Returns:

Permission for given database or collection.

Return type:

str

Raises:

arango.exceptions.PermissionGetError – If retrieval fails.

permissions(username: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return user permissions for all databases and collections.

Parameters:

username (str) – Username.

Returns:

User permissions for all databases and collections.

Return type:

dict

Raises:

arango.exceptions.PermissionListError – If retrieval fails.

property pregel: Pregel

Return Pregel API wrapper.

Returns:

Pregel API wrapper.

Return type:

arango.pregel.Pregel

properties() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return database properties.

Returns:

Database properties.

Return type:

dict

Raises:

arango.exceptions.DatabasePropertiesError – If retrieval fails.

read_log(upto: int | str | None = None, level: int | str | None = None, start: int | None = None, size: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None
Read the global log from server. This method is deprecated

in ArangoDB 3.8 and will be removed in a future version of the driver. Use arango.database.Database.read_log_entries() instead.

Parameters:
  • upto (int | str) – Return the log entries up to the given level (mutually exclusive with parameter level). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • level (int | str) – Return the log entries of only the given level (mutually exclusive with upto). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • start (int) – Return the log entries whose ID is greater or equal to the given value.

  • size (int) – Restrict the size of the result to the given value. This can be used for pagination.

  • offset (int) – Number of entries to skip (e.g. for pagination).

  • search (str) – Return only the log entries containing the given text.

  • sort (str) – Sort the log entries according to the given fashion, which can be “sort” or “desc”.

Returns:

Server log entries.

Return type:

dict

Raises:

arango.exceptions.ServerReadLogError – If read fails.

read_log_entries(upto: int | str | None = None, level: int | str | None = None, start: int | None = None, size: int | None = None, offset: int | None = None, search: str | None = None, sort: str | None = None, server_id: str | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Read the global log from server.

Parameters:
  • upto (int | str) – Return the log entries up to the given level (mutually exclusive with parameter level). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • level (int | str) – Return the log entries of only the given level (mutually exclusive with upto). Allowed values are “fatal”, “error”, “warning”, “info” (default) and “debug”.

  • start (int) – Return the log entries whose ID is greater or equal to the given value.

  • size (int) – Restrict the size of the result to the given value. This can be used for pagination.

  • offset (int) – Number of entries to skip (e.g. for pagination).

  • search (str) – Return only the log entries containing the given text.

  • sort (str) – Sort the log entries according to the given fashion, which can be “sort” or “desc”.

  • server_id (str) – Returns all log entries of the specified server. All other query parameters remain valid. If no serverId is given, the asked server will reply. This parameter is only meaningful on Coordinators.

Returns:

Server log entries.

Return type:

dict

Raises:

arango.exceptions.ServerReadLogError – If read fails.

reload_jwt_secrets() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Hot-reload JWT secrets.

Calling this without payload reloads JWT secrets from disk. Only files specified via arangod startup option --server.jwt-secret-keyfile or --server.jwt-secret-folder are used. It is not possible to change the location where files are loaded from without restarting the server.

Returns:

Information on reloaded JWT secrets.

Return type:

dict

reload_routing() bool | AsyncJob[bool] | BatchJob[bool] | None

Reload the routing information.

Returns:

True if routing was reloaded successfully.

Return type:

bool

Raises:

arango.exceptions.ServerReloadRoutingError – If reload fails.

reload_tls() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Reload TLS data (server key, client-auth CA).

Returns:

New TLS data.

Return type:

dict

rename_view(name: str, new_name: str) bool | AsyncJob[bool] | BatchJob[bool] | None

Rename a view.

Parameters:
  • name (str) – View name.

  • new_name (str) – New view name.

Returns:

True if view was renamed successfully.

Return type:

bool

Raises:

arango.exceptions.ViewRenameError – If delete fails.

replace_arangosearch_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Replace an ArangoSearch view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

replace_document(document: Dict[str, Any], check_rev: bool = True, return_new: bool = False, return_old: bool = False, sync: bool | None = None, silent: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

Replace a document.

Parameters:
  • document (dict) – New document to replace the old one with. It must contain the “_id” field. Edge document must also have “_from” and “_to” fields.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

  • return_new (bool) – Include body of the new document in the result.

  • return_old (bool) – Include body of the old document in the result.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

Returns:

Document metadata (e.g. document key, revision) or True if parameter silent was set to True.

Return type:

bool | dict

Raises:
replace_user(username: str, password: str, active: bool | None = None, extra: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Replace a user.

Parameters:
  • username (str) – Username.

  • password (str) – New password.

  • active (bool | None) – Whether the user is active.

  • extra (dict | None) – Additional data for the user.

Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserReplaceError – If replace fails.

replace_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Replace a view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

property replication: Replication

Return Replication API wrapper.

Returns:

Replication API wrapper.

Return type:

arango.replication.Replication

required_db_version() str | AsyncJob[str] | BatchJob[str] | None

Return required version of target database.

Returns:

Required version of target database.

Return type:

str

Raises:

arango.exceptions.ServerRequiredDBVersionError – If retrieval fails.

reset_permission(username: str, database: str, collection: str | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Reset user permission for a specific database or collection.

Parameters:
  • username (str) – Username.

  • database (str) – Database name.

  • collection (str) – Collection name.

Returns:

True if permission was reset successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionRestError – If reset fails.

role() str | AsyncJob[str] | BatchJob[str] | None

Return server role.

Returns:

Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY”, “AGENT” (Agency node in a cluster) or “UNDEFINED”.

Return type:

str

Raises:

arango.exceptions.ServerRoleError – If retrieval fails.

run_tests(tests: Sequence[str]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Run available unittests on the server.

Parameters:

tests ([str]) – List of files containing the test suites.

Returns:

Test results.

Return type:

dict

Raises:

arango.exceptions.ServerRunTestsError – If execution fails.

set_license(license: str, force: bool = False) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Set a new license for an Enterprise Edition instance. Can be called on single servers, Coordinators, and DB-Servers.

Parameters:
  • license (str) – The Base64-encoded license string.

  • force (bool) – If set to True, the new license will be set even if it expires sooner than the current license.

Returns:

Server license.

Return type:

dict

Raises:

arango.exceptions.ServerLicenseError – If retrieval fails.

set_log_levels(server_id: str | None = None, **kwargs: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

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:

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

Keys that are not valid logger names are ignored.

Parameters:
  • server_id (str | None) – Forward log level to a specific server. This makes it easier to adjust the log levels in clusters because DB-Servers require JWT authentication whereas Coordinators also support authentication using usernames and passwords.

  • kwargs (Dict[str, Any]) – Logging levels.

Returns:

New logging levels.

Return type:

dict

set_log_settings(**kwargs: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

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.

arango.set_log_settings(
    database=True,
    url=True,
    username=False,
)
Parameters:

kwargs (Dict[str, Any]) – Structured log parameters.

Returns:

New log settings. False values are not returned.

Return type:

dict

set_mode(mode: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Set the server mode to read-only or default.

Update mode information about a server. The JSON response will contain a field mode with the value readonly or default. In a read-only server all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping of databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

This is a protected API. It requires authentication and administrative server rights.

Parameters:

mode (str) – Server mode. Possible values are “default” or “readonly”.

Returns:

Server mode.

Return type:

str

Raises:

arango.exceptions.ServerModeSetError – If set fails.

shutdown(soft: bool = False) bool | AsyncJob[bool] | BatchJob[bool] | None

Initiate server shutdown sequence.

Parameters:

soft (bool) – If set to true, this initiates a soft shutdown. This is only available on Coordinators. When issued, the Coordinator tracks a number of ongoing operations, waits until all have finished, and then shuts itself down normally. It will still accept new operations.

Returns:

True if the server was shutdown successfully.

Return type:

bool

Raises:

arango.exceptions.ServerShutdownError – If shutdown fails.

shutdown_progress() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None
Query the soft shutdown progress. This call reports progress about a

soft Coordinator shutdown (DELETE /_admin/shutdown?soft=true). This API is only available on Coordinators.

Returns:

Information about the shutdown progress.

Return type:

dict

Raises:

arango.exceptions.ServerShutdownError – If shutdown fails.

statistics(description: bool = False) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return server statistics.

Returns:

Server statistics.

Return type:

dict

Raises:

arango.exceptions.ServerStatisticsError – If retrieval fails.

status() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return ArangoDB server status.

Returns:

Server status.

Return type:

dict

Raises:

arango.exceptions.ServerStatusError – If retrieval fails.

support_info() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return information about the deployment.

Retrieves deployment information for support purposes. The endpoint returns data about the ArangoDB version used, the host (operating system, server ID, CPU and storage capacity, current utilization, a few metrics) and the other servers in the deployment (in case of Active Failover or cluster deployments).

NOTE: This method can only be accessed from inside the _system database. The is a policy control startup option –server.support-info-api that controls if and to whom the API is made available.

Returns:

Deployment information.

Return type:

dict

Raises:

arango.exceptions.DatabaseSupportInfoError – If retrieval fails.

task(task_id: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the details of an active server task.

Parameters:

task_id (str) – Server task ID.

Returns:

Server task details.

Return type:

dict

Raises:

arango.exceptions.TaskGetError – If retrieval fails.

tasks() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return all currently active server tasks.

Returns:

Currently active server tasks.

Return type:

[dict]

Raises:

arango.exceptions.TaskListError – If retrieval fails.

time() datetime | AsyncJob[datetime] | BatchJob[datetime] | None

Return server system time.

Returns:

Server system time.

Return type:

datetime.datetime

Raises:

arango.exceptions.ServerTimeError – If retrieval fails.

tls() Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return TLS data (server key, client-auth CA).

Returns:

TLS data.

Return type:

dict

update_arangosearch_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Update an ArangoSearch view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

update_document(document: Dict[str, Any], check_rev: bool = True, merge: bool = True, keep_none: bool = True, return_new: bool = False, return_old: bool = False, sync: bool | None = None, silent: bool = False) bool | Dict[str, Any] | AsyncJob[bool | Dict[str, Any]] | BatchJob[bool | Dict[str, Any]] | None

Update a document.

Parameters:
  • document (dict) – Partial or full document with the updated values. It must contain the “_id” field.

  • check_rev (bool) – If set to True, revision of document (if given) is compared against the revision of target document.

  • merge (bool | None) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.

  • keep_none (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.

  • return_new (bool) – Include body of the new document in the result.

  • return_old (bool) – Include body of the old document in the result.

  • sync (bool | None) – Block until operation is synchronized to disk.

  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.

Returns:

Document metadata (e.g. document key, revision) or True if parameter silent was set to True.

Return type:

bool | dict

Raises:
update_permission(username: str, permission: str, database: str, collection: str | None = None) bool | AsyncJob[bool] | BatchJob[bool] | None

Update user permission for a specific database or collection.

Parameters:
  • username (str) – Username.

  • permission (str) – Allowed values are “rw” (read and write), “ro” (read only) or “none” (no access).

  • database (str) – Database name.

  • collection (str | None) – Collection name.

Returns:

True if access was granted successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionUpdateError – If update fails.

update_user(username: str, password: str | None = None, active: bool | None = None, extra: Dict[str, Any] | None = None) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Update a user.

Parameters:
  • username (str) – Username.

  • password (str | None) – New password.

  • active (bool | None) – Whether the user is active.

  • extra (dict | None) – Additional data for the user.

Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserUpdateError – If update fails.

update_view(name: str, properties: Dict[str, Any]) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Update a view.

Parameters:
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

user(username: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return user details.

Parameters:

username (str) – Username.

Returns:

User details.

Return type:

dict

Raises:

arango.exceptions.UserGetError – If retrieval fails.

property username: str | None

Return the username.

Returns:

Username.

Return type:

str

users() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return all user details.

Returns:

List of user details.

Return type:

[dict]

Raises:

arango.exceptions.UserListError – If retrieval fails.

version(details: bool = False) Any | AsyncJob[Any] | BatchJob[Any] | None

Return ArangoDB server version. :param details: Return more detailed version output :type details: bool | None :return: Server version. :rtype: str :raise arango.exceptions.ServerVersionError: If retrieval fails.

view(name: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the properties of a View.

Returns:

The View properties.

Return type:

dict

Raises:

arango.exceptions.ViewGetError – If retrieval fails.

view_info(name: str) Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the id, name and type of a View.

Returns:

Some View information.

Return type:

dict

Raises:

arango.exceptions.ViewGetError – If retrieval fails.

views() List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return list of views and their summaries.

Returns:

List of views.

Return type:

[dict]

Raises:

arango.exceptions.ViewListError – If retrieval fails.

property wal: WAL

Return WAL (Write-Ahead Log) API wrapper.

Returns:

WAL API wrapper.

Return type:

arango.wal.WAL

BatchJob

class arango.job.BatchJob(response_handler: Callable[[Response], T])[source]

Job for tracking and retrieving result of batch API execution.

Parameters:

response_handler (callable) – HTTP response handler.

property id: str

Return the batch job ID.

Returns:

Batch job ID.

Return type:

str

status() str[source]

Return the batch job status.

Returns:

Batch job status. Possible values are “pending” (job is still waiting for batch to be committed), or “done” (batch was committed and the job is updated with the result).

Return type:

str

result() T[source]

Return the batch job result.

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

Returns:

Batch job result.

Raises:

Cluster

class arango.cluster.Cluster(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, executor: DefaultApiExecutor | AsyncApiExecutor | BatchApiExecutor | TransactionApiExecutor | OverloadControlApiExecutor)[source]
server_id() str | AsyncJob[str] | BatchJob[str] | None[source]

Return the server ID.

Returns:

Server ID.

Return type:

str

Raises:

arango.exceptions.ClusterServerIDError – If retrieval fails.

server_role() str | AsyncJob[str] | BatchJob[str] | None[source]

Return the server role.

Returns:

Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY”, “AGENT” (Agency server in a cluster) or “UNDEFINED”.

Return type:

str

Raises:

arango.exceptions.ClusterServerRoleError – If retrieval fails.

server_mode() str | AsyncJob[str] | BatchJob[str] | None[source]

Return the server mode.

In a read-only server, all write operations will fail with an error code of 1004 (ERROR_READ_ONLY). Creating or dropping databases and collections will also fail with error code 11 (ERROR_FORBIDDEN).

Returns:

Server mode. Possible values are “default” or “readonly”.

Return type:

str

Raises:

arango.exceptions.ClusterServerModeError – If retrieval fails.