API Specification 

Raises:

arango.exceptions.CollectionCreateError – If create fails.

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 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:

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 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 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:

name (str) – View name.
view_type (str) – View type (e.g. “arangosearch” or “search-alias”).
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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 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:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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.

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:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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 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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

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:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

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:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

arango.exceptions.ArangoError – If the job raised an exception.
arango.exceptions.AsyncJobResultError – If retrieval fails.

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

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

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 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:

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.

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 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

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 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

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

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.

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:

arango.exceptions.BatchStateError – If batch state is invalid (e.g. batch was already committed or the response size did not match expected).
arango.exceptions.BatchExecuteError – If commit fails.

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 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 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:

name (str) – View name.
properties (dict | None) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

Raises:

arango.exceptions.CollectionCreateError – If create fails.

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 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:

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 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 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:

name (str) – View name.
view_type (str) – View type (e.g. “arangosearch” or “search-alias”).
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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 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:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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.

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:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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 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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

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:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

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:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

arango.exceptions.ArangoError – If the job raised an exception.
arango.exceptions.BatchJobResultError – If job result is not available (i.e. batch is not committed yet).

Cluster

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.

server_version(server_id: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the version of the given server.

Parameters:: server_id (str) – Server ID.
Returns:: Version of the given server.
Return type:: dict
Raises:: arango.exceptions.ClusterServerVersionError – If retrieval fails.

server_engine(server_id: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the engine details for the given server.

Parameters:: server_id (str) – Server ID.
Returns:: Engine details of the given server.
Return type:: dict
Raises:: arango.exceptions.ClusterServerEngineError – If retrieval fails.

server_count() → int | AsyncJob[int] | BatchJob[int] | None[source]

Return the number of servers in the cluster.

Returns:: Number of servers in the cluster.
Return type:: int
Raises:: arango.exceptions.ClusterServerCountError – If retrieval fails.

server_statistics(server_id: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the statistics for the given server.

Parameters:: server_id (str) – Server ID.
Returns:: Statistics for the given server.
Return type:: dict
Raises:: arango.exceptions.ClusterServerStatisticsError – If retrieval fails.

server_maintenance_mode(server_id: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the maintenance status for the given server.

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

toggle_server_maintenance_mode(server_id: str, mode: str, timeout: int | None = None) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Enable or disable the maintenance mode for the given server.

Parameters:

server_id (str) – Server ID.
mode (str) – Maintenance mode. Allowed values are “normal” and “maintenance”.
timeout (Optional[int]) – Timeout in seconds.

Returns:

Result of the operation.

Return type:

dict

Raises:

arango.exceptions.ClusterMaintenanceModeError – If toggle fails.

health() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the cluster health.

Returns:: Cluster health.
Return type:: dict
Raises:: arango.exceptions.ClusterHealthError – If retrieval fails.

toggle_maintenance_mode(mode: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

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

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

endpoints() → List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None[source]

Return coordinate endpoints. This method is for clusters only.

Returns:: List of endpoints.
Return type:: [str]
Raises:: arango.exceptions.ServerEndpointsError – If retrieval fails.

calculate_imbalance() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Compute the current cluster imbalance, including the amount of ongoing and pending move shard operations.

Returns:: Cluster imbalance information.
Return type:: dict
Raise:: arango.exceptions.ClusterRebalanceError: If retrieval fails.

Compute and execute a cluster rebalance plan.

Parameters:

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

Returns:

Cluster rebalance plan that has been executed.

Return type:

dict

Raise:

arango.exceptions.ClusterRebalanceError: If retrieval fails.

Compute the cluster rebalance plan.

Parameters:

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

Returns:

Cluster rebalance plan.

Return type:

dict

Raise:

arango.exceptions.ClusterRebalanceError: If retrieval fails.

execute_rebalance_plan(moves: List[Dict[str, Any]], version: int = 1) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Execute the given set of move shard operations.

You can use Cluster.calculate_rebalance_plan() to calculate these operations to improve the balance of shards, leader shards, and follower shards.

Parameters:

moves ([dict]) – List of move shard operations.
version (int) – Must be set to 1.

Returns:

True if the methods have been accepted and scheduled for execution.

Return type:

bool

Raise:

arango.exceptions.ClusterRebalanceError: If request fails.

Collection

Base class for collection API wrappers.

Parameters:

connection – HTTP connection.
executor – API executor.
name – Collection name.

property name: str

Return collection name.

Returns:: Collection name.
Return type:: str

recalculate_count() → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Recalculate the document count.

Returns:: True if recalculation was successful.
Return type:: bool
Raises:: arango.exceptions.CollectionRecalculateCountError – If operation fails.

responsible_shard(document: Dict[str, Any]) → str | AsyncJob[str] | BatchJob[str] | None[source]

Return the ID of the shard responsible for given document.

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

Returns:: Shard ID
Return type:: str

rename(new_name: str) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Rename the collection.

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

Parameters:: new_name (str) – New collection name.
Returns:: True if collection was renamed successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionRenameError – If rename fails.

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

Return collection properties.

Returns:: Collection properties.
Return type:: dict
Raises:: arango.exceptions.CollectionPropertiesError – If retrieval fails.

shards(details: bool = False) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return collection shards and properties.

Available only in a cluster setup.

Parameters:: details (bool) – Include responsible servers for each shard.
Returns:: Collection shards and properties.
Return type:: dict
Raises:: arango.exceptions.CollectionShardsError – If retrieval fails.

info() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the collection information.

Returns:: Information about the collection.
Return type:: dict
Raises:: arango.exceptions.CollectionInformationError – If retrieval fails.

Configure collection properties.

Parameters:

sync (bool | None) – Block until operations are synchronized to disk.
schema (dict) – document schema for validation of objects.
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.
computed_values (dict | None) – Define expressions on the collection level that run on inserts, modifications, or both.

Returns:

New collection properties.

Return type:

dict

Raises:

arango.exceptions.CollectionConfigureError – If operation fails.

statistics() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return collection statistics.

Returns:: Collection statistics.
Return type:: dict
Raises:: arango.exceptions.CollectionStatisticsError – If retrieval fails.

revision() → str | AsyncJob[str] | BatchJob[str] | None[source]

Return collection revision.

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

checksum(with_rev: bool = False, with_data: bool = False) → str | AsyncJob[str] | BatchJob[str] | None[source]

Return collection checksum.

Parameters:

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

Returns:

Collection checksum.

Return type:

str

Raises:

arango.exceptions.CollectionChecksumError – If retrieval fails.

compact() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Compact a collection.

Compacts the data of a collection in order to reclaim disk space. The operation will compact the document and index data by rewriting the underlying .sst files and only keeping the relevant entries.

Under normal circumstances, running a compact operation is not necessary, as the collection data will eventually get compacted anyway. However, in some situations, e.g. after running lots of update/replace or remove operations, the disk data for a collection may contain a lot of outdated data for which the space shall be reclaimed. In this case the compaction operation can be used.

Returns:: Collection compact.
Return type:: dict
Raises:: arango.exceptions.CollectionCompactError – If retrieval fails.

load() → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Load the collection into memory.

Returns:: True if collection was loaded successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionLoadError – If operation fails.

unload() → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Unload the collection from memory.

Returns:: True if collection was unloaded successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionUnloadError – If operation fails.

truncate() → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Delete all documents in the collection.

Returns:: True if collection was truncated successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionTruncateError – If operation fails.

count() → int | AsyncJob[int] | BatchJob[int] | None[source]

Return the total document count.

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

Check if a document exists in the collection.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
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.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

True if document exists, False otherwise.

Return type:

bool

Raises:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

ids(allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None[source]

Return the IDs of all documents in the collection.

Parameters:: allow_dirty_read (bool) – Allow reads from followers in a cluster.
Returns:: Document ID cursor.
Return type:: arango.cursor.Cursor
Raises:: arango.exceptions.DocumentIDsError – If retrieval fails.

keys(allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None[source]

Return the keys of all documents in the collection.

Parameters:: allow_dirty_read (bool) – Allow reads from followers in a cluster.
Returns:: Document key cursor.
Return type:: arango.cursor.Cursor
Raises:: arango.exceptions.DocumentKeysError – If retrieval fails.

Return all documents in the collection.

Parameters:

skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Return all documents that match the given filters.

Parameters:

filters (dict) – Document filters.
skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_near(latitude: Number, longitude: Number, limit: int | None = None, allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None[source]

Return documents near a given coordinate.

Documents returned are sorted according to distance, with the nearest document being the first. If there are documents of equal distance, they are randomly chosen from the set until the limit is reached. A geo index must be defined in the collection to use this method.

Parameters:

latitude (int | float) – Latitude.
longitude (int | float) – Longitude.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Return documents within a given range in a random order.

A skiplist index must be defined in the collection to use this method.

Parameters:

field (str) – Document field name.
lower (int) – Lower bound (inclusive).
upper (int) – Upper bound (exclusive).
skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_in_radius(latitude: Number, longitude: Number, radius: Number, distance_field: str | None = None, allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None[source]

Return documents within a given radius around a coordinate.

A geo index must be defined in the collection to use this method.

Parameters:

latitude (int | float) – Latitude.
longitude (int | float) – Longitude.
radius (int | float) – Max radius.
distance_field (str) – Document field used to indicate the distance to the given coordinate. This parameter is ignored in transactions.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Return all documents in a rectangular area.

Parameters:

latitude1 (int | float) – First latitude.
longitude1 (int | float) – First longitude.
latitude2 (int | float) – Second latitude.
longitude2 (int | float) – Second longitude
skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
index (str | None) – ID of the geo index to use (without the collection prefix). This parameter is ignored in transactions.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_by_text(field: str, query: str, limit: int | None = None, allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None[source]

Return documents that match the given fulltext query.

Parameters:

field (str) – Document field with fulltext index.
query (str) – Fulltext query.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

arango.collection.EdgeCollection

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

get_many(documents: Sequence[str | Dict[str, Any]], allow_dirty_read: bool = False) → List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return multiple documents ignoring any missing ones.

Parameters:

documents ([str | dict]) – List of document keys, IDs or bodies. Document bodies must contain the “_id” or “_key” fields.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Documents. Missing ones are not included.

Return type:

[dict]

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Return a random document from the collection. Returns None if the collection is empty.

Parameters:: allow_dirty_read (bool) – Allow reads from followers in a cluster.
Returns:: A random document.
Return type:: dict
Raises:: arango.exceptions.DocumentGetError – If retrieval fails.

indexes() → List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return the collection indexes.

Returns:: Collection indexes.
Return type:: [dict]
Raises:: arango.exceptions.IndexListError – If retrieval fails.

get_index(id: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the index with the given id.

Parameters:: id (str) – The id of the index
Returns:: Index details
Return type:: dict
Raises:: arango.exceptions.IndexGetError – If retrieval fails.

Create a new hash index.

Parameters:

fields ([str]) – Document fields to index.
unique (bool | None) – Whether the index is unique.
sparse (bool | None) – If set to True, documents with None in the field are also indexed. If set to False, they are skipped.
deduplicate (bool | None) – If set to True, inserting duplicate index values from the same document triggers unique constraint errors.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new skiplist index.

Parameters:

fields ([str]) – Document fields to index.
unique (bool | None) – Whether the index is unique.
sparse (bool | None) – If set to True, documents with None in the field are also indexed. If set to False, they are skipped.
deduplicate (bool | None) – If set to True, inserting duplicate index values from the same document triggers unique constraint errors.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new geo-spatial index.

Parameters:

fields (str | [str]) – A single document field or a list of document fields. If a single field is given, the field must have values that are lists with at least two floats. Documents with missing fields or invalid values are excluded.
geo_json (bool | None) – Whether to use GeoJSON data-format or not. This parameter has been renamed from ordered. See Github Issue #234 for more details.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.
legacyPolygons (bool | None) – Whether or not to use use the old, pre-3.10 rules for the parsing GeoJSON polygons

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new fulltext index. This method is deprecated: in ArangoDB 3.10 and will be removed in a future version of the driver.

Parameters:

fields ([str]) – Document fields to index.
min_length (int | None) – Minimum number of characters to index.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new persistent index.

Unique persistent indexes on non-sharded keys are not supported in a cluster.

Parameters:

fields ([str]) – Document fields to index.
unique (bool | None) – Whether the index is unique.
sparse (bool | None) – Exclude documents that do not contain at least one of the indexed fields, or documents that have a value of None in any of the indexed fields.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.
storedValues ([str]) – Additional attributes to include in a persistent index. These additional attributes cannot be used for index lookups or sorts, but they can be used for projections. Must be an array of index attribute paths. There must be no overlap of attribute paths between fields and storedValues. The maximum number of values is 32.
cacheEnabled (bool | None) – Enable an in-memory cache for index values for persistent indexes.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new TTL (time-to-live) index.

Parameters:

fields ([str]) – Document field to index.
expiry_time (int) – Time of expiry in seconds after document creation.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new inverted index, introduced in version 3.10.

Parameters:

fields (Json) – Document fields to index.
name (str | None) – Optional name for the index.
inBackground (bool | None) – Do not hold the collection lock.
parallelism (int | None) – The number of threads to use for indexing the fields.
primarySort (Optional[Json]) – Primary sort order to enable an AQL optimization.
storedValues (Sequence[Json] | None) – An array of objects with paths to additional attributes to store in the index.
analyzer (Optional[str]) – Analyzer to use by default.
features (Sequence[str] | None) – List of Analyzer features.
includeAllFields (bool | None) – This option only applies if you use the inverted index in search-alias views.
trackListPositions (bool | None) – This option only applies if you use the inverted index in search-alias views, and searchField is true.
searchField (bool | None) – This option only applies if you use the inverted index in search-alias views
primaryKeyCache (bool | None) – Always cache the primary key column in memory.
cache (bool | None) – Always cache the field normalization values in memory for all fields by default.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new ZKD Index.

Parameters:

fields (Sequence[str]) – Document fields to index. Unlike for other indexes the order of the fields does not matter.
field_value_types (str) – The type of the field values. The only allowed value is “double” at the moment. Defaults to “double”.
name (str | None) – Optional name for the index.
unique (bool | None) – Whether the index is unique.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new MDI index, previously known as ZKD index. This method: is only usable with ArangoDB 3.12 and later.

Parameters:

fields (Sequence[str]) – Document fields to index. Unlike for other indexes the order of the fields does not matter.
field_value_types (str) – The type of the field values. The only allowed value is “double” at the moment. Defaults to “double”.
name (str | None) – Optional name for the index.
unique (bool | None) – Whether the index is unique.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

delete_index(index_id: str, ignore_missing: bool = False) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Delete an index.

Parameters:

index_id (str) – Index ID.
ignore_missing (bool) – Do not raise an exception on missing index.

Returns:

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

Return type:

bool

Raises:

arango.exceptions.IndexDeleteError – If delete fails.

load_indexes() → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Cache all indexes in the collection into memory.

Returns:: True if index was loaded successfully.
Return type:: bool
Raises:: arango.exceptions.IndexLoadError – If operation fails.

Insert multiple documents.

Note

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

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single insert operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – List of new documents to insert. If they contain the “_key” or “_id” fields, the values are used as the keys of the new documents (auto-generated otherwise). Any “_rev” field is ignored.
return_new (bool) – Include bodies of the new documents 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 keys and the existing documents are replaced.
return_old (bool) – Include body of the old documents 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), “update” (update-insert), “ignore” or “conflict”. 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).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

List of document metadata (e.g. document keys, revisions) and any exception, or True if parameter silent was set to True.

Return type:

[dict | ArangoServerError] | bool

Raises:

arango.exceptions.DocumentInsertError – If insert fails.

Update multiple documents.

Note

If updating a document fails, the exception is not raised but returned as an object in the result list. It is up to you to inspect the list to determine which documents were updated successfully (returns document metadata) and which were not (returns exception object). Alternatively, you can rely on setting raise_on_document_error to True (defaults to False).

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single update operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – Partial or full documents with the updated values. They must contain the “_id” or “_key” fields.
check_rev (bool) – If set to True, revisions of documents (if given) are compared against the revisions of target documents.
merge (bool | None) – If set to True, sub-dictionaries are merged instead of the new ones overwriting the old ones.
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 returned metadata. Ignored if parameter silent is set to True.
return_old (bool) – Include body of the old 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
raise_on_document_error (bool) – Whether to raise if a DocumentRevisionError or a DocumentUpdateError is encountered on an individual document, as opposed to returning the error as an object in the result list. Defaults to False.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

List of document metadata (e.g. document keys, revisions) and any exceptions, or True if parameter silent was set to True.

Return type:

[dict | ArangoError] | bool

Raises:

arango.exceptions.DocumentUpdateError – If update fails.

Update matching documents.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single update operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

filters (dict) – Document filters.
body (dict) – Full or partial document body with the updates.
limit (int | None) – Max number of documents to update. If the limit is lower than the number of matched documents, random documents are chosen. This parameter is not supported on sharded collections.
keep_none (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.
sync (bool | None) – Block until operation is synchronized to disk.
merge (bool | None) – If set to True, sub-dictionaries are merged instead of the new ones overwriting the old ones.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Number of documents updated.

Return type:

int

Raises:

arango.exceptions.DocumentUpdateError – If update fails.

Replace multiple documents.

Note

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

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single replace operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – New documents to replace the old ones with. They must contain the “_id” or “_key” fields. Edge documents must also have “_from” and “_to” fields.
check_rev (bool) – If set to True, revisions of documents (if given) are compared against the revisions of target documents.
return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.
return_old (bool) – Include body of the old 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

List of document metadata (e.g. document keys, revisions) and any exceptions, or True if parameter silent was set to True.

Return type:

[dict | ArangoServerError] | bool

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.

Replace matching documents.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single replace operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

filters (dict) – Document filters.
body (dict) – New document body.
limit (int | None) – Max number of documents to replace. If the limit is lower than the number of matched documents, random documents are chosen.
sync (bool | None) – Block until operation is synchronized to disk.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Number of documents replaced.

Return type:

int

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.

Delete multiple documents.

Note

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

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single delete operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([str | dict]) – Document IDs, keys or bodies. Document bodies must contain the “_id” or “_key” fields.
return_old (bool) – Include bodies of the old documents in the result.
check_rev (bool) – If set to True, revisions of documents (if given) are compared against the revisions of target documents.
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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.

Returns:

List of document metadata (e.g. document keys, revisions) and any exceptions, or True if parameter silent was set to True.

Return type:

[dict | ArangoServerError] | bool

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.

Delete matching documents.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single delete operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

filters (dict) – Document filters.
limit (int | None) – Max number of documents to delete. If the limit is lower than the number of matched documents, random documents are chosen.
sync (bool | None) – Block until operation is synchronized to disk.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Number of documents deleted.

Return type:

int

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.

Insert multiple documents into the collection.

Note

This method is faster than arango.collection.Collection.insert_many() but does not return as many details.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single insert operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – List of new documents to insert. If they contain the “_key” or “_id” fields, the values are used as the keys of the new documents (auto-generated otherwise). Any “_rev” field is ignored.
halt_on_error (bool) – Halt the entire import on an error.
details (bool) – If set to True, the returned result will include an additional list of detailed error messages.
from_prefix (str) – String prefix prepended to the value of “_from” field in each edge document inserted. For example, prefix “foo” prepended to “_from”: “bar” will result in “_from”: “foo/bar”. Applies only to edge collections.
to_prefix (str) – String prefix prepended to the value of “_to” field in edge document inserted. For example, prefix “foo” prepended to “_to”: “bar” will result in “_to”: “foo/bar”. Applies only to edge collections.
overwrite (bool) – If set to True, all existing documents are removed prior to the import. Indexes are still preserved.
on_duplicate (str) – Action to take on unique key constraint violations (for documents with “_key” fields). Allowed values are “error” (do not import the new documents and count them as errors), “update” (update the existing documents while preserving any fields missing in the new ones), “replace” (replace the existing documents with new ones), and “ignore” (do not import the new documents and count them as ignored, as opposed to counting them as errors). Options “update” and “replace” may fail on secondary unique key constraint violations.
sync (bool | None) – Block until operation is synchronized to disk.
batch_size (int) – Split up documents into batches of max length batch_size and import them in a loop on the client side. If batch_size is specified, the return type of this method changes from a result object to a list of result objects. IMPORTANT NOTE: this parameter may go through breaking changes in the future where the return type may not be a list of result objects anymore. Use it at your own risk, and avoid depending on the return value if possible. Cannot be used with parameter overwrite.

Returns:

Result of the bulk import.

Return type:

dict | list[dict]

Raises:

arango.exceptions.DocumentInsertError – If import fails.

Cursor

class arango.cursor.Cursor(connection: BaseConnection, init_data: Dict[str, Any], cursor_type: str = 'cursor', allow_retry: bool = False)[source]

Cursor API wrapper.

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

Parameters:

connection – HTTP connection.
init_data (dict) – Cursor initialization data.
cursor_type (str) – Cursor type (“cursor” or “export”).
allow_retry (bool) – If set to True, the cursor will always attempt to fetch the latest batch from server even if the previous attempt failed. This option is only available for server versions 3.11 and above.

property id: str | None

Return the cursor ID.

Returns:: Cursor ID.
Return type:: str

property type: str

Return the cursor type.

Returns:: Cursor type (“cursor” or “export”).
Return type:: str

batch() → Deque[Any] | None[source]

Return the current batch of results.

Returns:: Current batch.
Return type:: collections.deque

has_more() → bool | None[source]

Return True if more results are available on the server.

Returns:: True if more results are available on the server.
Return type:: bool

count() → int | None[source]

Return the total number of documents in the entire result set.

Returns:: Total number of documents, or None if the count option was not enabled during cursor initialization.
Return type:: int | None

cached() → bool | None[source]

Return True if results are cached.

Returns:: True if results are cached.
Return type:: bool

statistics() → Dict[str, Any] | None[source]

Return cursor statistics.

Returns:: Cursor statistics.
Return type:: dict

profile() → Dict[str, Any] | None[source]

Return cursor performance profile.

Returns:: Cursor performance profile.
Return type:: dict

warnings() → Sequence[Dict[str, Any]] | None[source]

Return any warnings from the query execution.

Returns:: Warnings, or None if there are none.
Return type:: [str]

empty() → bool[source]

Check if the current batch is empty.

Returns:: True if current batch is empty, False otherwise.
Return type:: bool

next() → Any[source]

Pop the next item from the current batch.

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

Returns:

Next item in current batch.

Raises:

StopIteration – If the result set is depleted.
arango.exceptions.CursorNextError – If batch retrieval fails.
arango.exceptions.CursorStateError – If cursor ID is not set.

pop() → Any[source]

Pop the next item from current batch.

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

Returns:: Next item in current batch.
Raises:: arango.exceptions.CursorEmptyError – If current batch is empty.

fetch() → Dict[str, Any][source]

Fetch the next batch from server and update the cursor.

Returns:

New batch details.

Return type:

dict

Raises:

arango.exceptions.CursorNextError – If batch retrieval fails.
arango.exceptions.CursorStateError – If cursor ID is not set.

close(ignore_missing: bool = False) → bool | None[source]

Close the cursor and free any server resources tied to it.

Parameters:

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

Returns:

True if cursor was closed successfully, False if cursor was missing on the server and ignore_missing was set to True, None if there are no cursors to close server-side (e.g. result set is smaller than the batch size).

Return type:

bool | None

Raises:

arango.exceptions.CursorCloseError – If operation fails.
arango.exceptions.CursorStateError – If cursor ID is not set.

DefaultHTTPClient

class arango.http.DefaultHTTPClient(request_timeout: int | float | None = 60, retry_attempts: int = 3, backoff_factor: float = 1.0, pool_connections: int = 10, pool_maxsize: int = 10, pool_timeout: int | float | None = None)[source]

Default HTTP client implementation.

Parameters:

request_timeout (int | float) – Timeout in seconds for each individual connection.
retry_attempts (int) – Number of retry attempts.
backoff_factor (float) – Backoff factor for retry attempts.
pool_connections (int) – The number of urllib3 connection pools to cache.
pool_maxsize (int) – The maximum number of connections to save in the pool.
pool_timeout (int | float | None) – If set, then the pool will be set to block=True, and requests will block for pool_timeout seconds and raise EmptyPoolError if no connection is available within the time period.

create_session(host: str) → Session[source]

Create and return a new session/connection.

Parameters:: host (str) – ArangoDB host URL.
Returns:: requests session object
Return type:: requests.Session

Send an HTTP request.

Parameters:

session (requests.Session) – Requests session object.
method (str) – HTTP method in lowercase (e.g. “post”).
url (str) – Request URL.
headers (dict) – Request headers.
params (dict) – URL (query) parameters.
data (str | bytes | MultipartEncoder | None) – Request payload.
auth (tuple) – Username and password.

Returns:

HTTP response.

Return type:

arango.response.Response

DeflateRequestCompression

class arango.http.DeflateRequestCompression(threshold: int = 1024, level: int = 6)[source]

Compress requests using the ‘deflate’ algorithm.

needs_compression(data: str) → bool[source]

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

compress(data: str) → bytes[source]

Parameters:: data (str) – Data to be compressed.
Returns:: Compressed data.
Return type:: bytes

encoding() → str[source]

Return the content encoding exactly as it should: appear in the headers.

Returns:: Content encoding.
Return type:: str

EdgeCollection

ArangoDB edge collection API wrapper.

Parameters:

connection – HTTP connection.
executor – API executor.
graph – Graph name.
name – Edge collection name.

property graph: str

Return the graph name.

Returns:: Graph name.
Return type:: str

Return an edge document.

Parameters:

edge (str | dict) – Edge document ID, key or body. Document body must contain the “_id” or “_key” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in edge if present.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.

Returns:

Edge document or None if not found.

Return type:

dict | None

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Insert a new edge document.

Parameters:

edge (dict) – New edge document to insert. It must contain “_from” and “_to” fields. If it has “_key” or “_id” field, its value is used as key of the new edge document (otherwise it is auto-generated). Any “_rev” field is ignored.
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.
return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.

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.

Update an edge document.

Parameters:

edge (dict) – Partial or full edge document with updated values. It must contain the “_key” or “_id” field.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.
keep_none (bool | None) – If set to True, fields with value None are retained in the document. If set to False, they are removed completely.
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.
return_old (bool) – Include body of the old document in the returned metadata. Ignored if parameter silent is set to True.
return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.

Returns:

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

Return type:

bool | dict

Raises:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Replace an edge document.

Parameters:

edge (dict) – New edge document to replace the old one with. It must contain the “_key” or “_id” field. It must also contain the “_from” and “_to” fields.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.
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.
return_old (bool) – Include body of the old document in the returned metadata. Ignored if parameter silent is set to True.
return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.

Returns:

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

Return type:

bool | dict

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Delete an edge document.

Parameters:

edge (str | dict) – Edge document ID, key or body. Document body must contain the “_id” or “_key” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in edge if present.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge 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.
sync (bool | None) – Block until operation is synchronized to disk.
return_old (bool) – Return body of the old document in the result.

Returns:

True if edge was deleted successfully, False if edge was not found and ignore_missing was set to True (does not apply in transactions).

Return type:

bool

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Insert a new edge document linking the given vertices.

Parameters:

from_vertex (str | dict) – “From” vertex document ID or body with “_id” field.
to_vertex (str | dict) – “To” vertex document ID or body with “_id” field.
data (dict | None) – Any extra data for the new edge document. If it has “_key” or “_id” field, its value is used as key of the new edge document (otherwise it is auto-generated).
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.
return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.

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.

Return the edge documents coming in and/or out of the vertex.

Parameters:

vertex (str | dict) – Vertex document ID or body with “_id” field.
direction (str) – The direction of the edges. Allowed values are “in” and “out”. If not set, edges in both directions are returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

List of edges and statistics.

Return type:

dict

Raises:

arango.exceptions.EdgeListError – If retrieval fails.

Foxx

Foxx API wrapper.

services(exclude_system: bool = False) → List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

List installed services.

Parameters:: exclude_system (bool) – If set to True, system services are excluded.
Returns:: List of installed service.
Return type:: [dict]
Raises:: arango.exceptions.FoxxServiceListError – If retrieval fails.

service(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return service metadata.

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

Install a new service using JSON definition.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
source (str) – Fully qualified URL or absolute path on the server file system. Must be accessible by the server, or by all servers if in a cluster.
config (dict | None) – Configuration values.
dependencies (dict | None) – Dependency settings.
development (bool | None) – Enable development mode.
setup (bool | None) – Run service setup script.
legacy (bool | None) – Install the service in 2.8 legacy compatibility mode.

Returns:

Service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceCreateError – If install fails.

Install a new service using a javascript file or zip bundle.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
filename (str) – Full path to the javascript file or zip bundle.
development (bool | None) – Enable development mode.
setup (bool | None) – Run service setup script.
legacy (bool | None) – Install the service in 2.8 legacy compatibility mode.
config (dict | None) – Configuration values.
dependencies (dict | None) – Dependency settings.

Returns:

Service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceCreateError – If install fails.

Update (upgrade) a service.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
source (str) – Fully qualified URL or absolute path on the server file system. Must be accessible by the server, or by all servers if in a cluster.
config (dict | None) – Configuration values.
dependencies (dict | None) – Dependency settings.
teardown (bool | None) – Run service teardown script.
setup (bool | None) – Run service setup script.
legacy (bool | None) – Update the service in 2.8 legacy compatibility mode.
force (bool | None) – Force update if no service is found.

Returns:

Updated service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceUpdateError – If update fails.

Update (upgrade) a service using a javascript file or zip bundle.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
filename (str) – Full path to the javascript file or zip bundle.
teardown (bool | None) – Run service teardown script.
setup (bool | None) – Run service setup script.
legacy (bool | None) – Update the service in 2.8 legacy compatibility mode.
force (bool | None) – Force update if no service is found.
config (dict | None) – Configuration values.
dependencies (dict | None) – Dependency settings.

Returns:

Updated service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceUpdateError – If update fails.

Replace a service by removing the old one and installing a new one.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
source (str) – Fully qualified URL or absolute path on the server file system. Must be accessible by the server, or by all servers if in a cluster.
config (dict | None) – Configuration values.
dependencies (dict | None) – Dependency settings.
teardown (bool | None) – Run service teardown script.
setup (bool | None) – Run service setup script.
legacy (bool | None) – Replace the service in 2.8 legacy compatibility mode.
force (bool | None) – Force install if no service is found.

Returns:

Replaced service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceReplaceError – If replace fails.

Replace a service using a javascript file or zip bundle.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
filename (str) – Full path to the javascript file or zip bundle.
teardown (bool | None) – Run service teardown script.
setup (bool | None) – Run service setup script.
legacy (bool | None) – Replace the service in 2.8 legacy compatibility mode.
force (bool | None) – Force install if no service is found.
config (dict | None) – Configuration values.
dependencies (dict | None) – Dependency settings.

Returns:

Replaced service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceReplaceError – If replace fails.

delete_service(mount: str, teardown: bool | None = None) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Uninstall a service.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
teardown (bool | None) – Run service teardown script.

Returns:

True if service was deleted successfully.

Return type:

bool

Raises:

arango.exceptions.FoxxServiceDeleteError – If delete fails.

config(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return service configuration.

Parameters:: mount (str) – Service mount path (e.g “/_admin/aardvark”).
Returns:: Configuration values.
Return type:: dict
Raises:: arango.exceptions.FoxxConfigGetError – If retrieval fails.

update_config(mount: str, config: Dict[str, Any]) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Update service configuration.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
config (dict) – Configuration values. Omitted options are ignored.

Returns:

Updated configuration values.

Return type:

dict

Raises:

arango.exceptions.FoxxConfigUpdateError – If update fails.

replace_config(mount: str, config: Dict[str, Any]) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Replace service configuration.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
config (dict) – Configuration values. Omitted options are reset to their default values or marked as un-configured.

Returns:

Replaced configuration values.

Return type:

dict

Raises:

arango.exceptions.FoxxConfigReplaceError – If replace fails.

dependencies(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return service dependencies.

Parameters:: mount (str) – Service mount path (e.g “/_admin/aardvark”).
Returns:: Dependency settings.
Return type:: dict
Raises:: arango.exceptions.FoxxDependencyGetError – If retrieval fails.

update_dependencies(mount: str, dependencies: Dict[str, Any]) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Update service dependencies.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
dependencies (dict) – Dependencies settings. Omitted ones are ignored.

Returns:

Updated dependency settings.

Return type:

dict

Raises:

arango.exceptions.FoxxDependencyUpdateError – If update fails.

replace_dependencies(mount: str, dependencies: Dict[str, Any]) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Replace service dependencies.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
dependencies (dict) – Dependencies settings. Omitted ones are disabled.

Returns:

Replaced dependency settings.

Return type:

dict

Raises:

arango.exceptions.FoxxDependencyReplaceError – If replace fails.

enable_development(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Put the service into development mode.

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

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

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

disable_development(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Put the service into production mode.

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

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

readme(mount: str) → str | AsyncJob[str] | BatchJob[str] | None[source]

Return the service readme.

Parameters:: mount (str) – Service mount path (e.g “/_admin/aardvark”).
Returns:: Service readme.
Return type:: str
Raises:: arango.exceptions.FoxxReadmeGetError – If retrieval fails.

swagger(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the Swagger API description for the given service.

Parameters:: mount (str) – Service mount path (e.g “/_admin/aardvark”).
Returns:: Swagger API description.
Return type:: dict
Raises:: arango.exceptions.FoxxSwaggerGetError – If retrieval fails.

download(mount: str) → str | AsyncJob[str] | BatchJob[str] | None[source]

Download service bundle.

When development mode is enabled, a new bundle is created every time. Otherwise, the bundle represents the version of the service installed on the server.

Parameters:: mount (str) – Service mount path (e.g “/_admin/aardvark”).
Returns:: Service bundle in raw string form.
Return type:: str
Raises:: arango.exceptions.FoxxDownloadError – If download fails.

commit(replace: bool | None = None) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Commit local service state of the coordinator to the database.

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

Parameters:: replace (bool | None) – Overwrite any existing service files in database.
Returns:: True if the state was committed successfully.
Return type:: bool
Raises:: arango.exceptions.FoxxCommitError – If commit fails.

scripts(mount: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

List service scripts.

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

run_script(mount: str, name: str, arg: Any = None) → Any | AsyncJob[Any] | BatchJob[Any] | None[source]

Run a service script.

Parameters:

mount (str) – Service mount path (e.g “/_admin/aardvark”).
name (str) – Script name.
arg (Any) – Arbitrary value passed into the script as first argument.

Returns:

Result of the script, if any.

Return type:

Any

Raises:

arango.exceptions.FoxxScriptRunError – If script fails.

Run service tests.

Parameters:

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

Type:

bool

Returns:

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

Return type:

str

Raises:

arango.exceptions.FoxxTestRunError – If test fails.

Graph

Graph API wrapper.

property name: str

Return the graph name.

Returns:: Graph name.
Return type:: str

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

Return graph properties.

Returns:: Graph properties.
Return type:: dict
Raises:: arango.exceptions.GraphPropertiesError – If retrieval fails.

has_vertex_collection(name: str) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Check if the graph has the given vertex collection.

Parameters:: name (str) – Vertex collection name.
Returns:: True if vertex collection exists, False otherwise.
Return type:: bool

vertex_collections() → List[str] | AsyncJob[List[str]] | BatchJob[List[str]] | None[source]

Return vertex collections in the graph.

Returns:: Names of vertex collections in Edge Definitions and Orphan Collections.
Return type:: [str]
Raises:: arango.exceptions.VertexCollectionListError – If retrieval fails.

vertex_collection(name: str) → VertexCollection[source]

Return the vertex collection API wrapper.

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

create_vertex_collection(name: str) → VertexCollection | AsyncJob[VertexCollection] | BatchJob[VertexCollection] | None[source]

Create a vertex collection in the graph.

Parameters:: name (str) – Vertex collection name.
Returns:: Vertex collection API wrapper.
Return type:: arango.collection.VertexCollection
Raises:: arango.exceptions.VertexCollectionCreateError – If create fails.

delete_vertex_collection(name: str, purge: bool = False) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Remove a vertex collection from the graph.

Parameters:

name (str) – Vertex collection name.
purge (bool) – If set to True, the vertex collection is not just deleted from the graph but also from the database completely.

Returns:

True if vertex collection was deleted successfully.

Return type:

bool

Raises:

arango.exceptions.VertexCollectionDeleteError – If delete fails.

has_edge_definition(name: str) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Check if the graph has the given edge definition.

Parameters:: name (str) – Edge collection name.
Returns:: True if edge definition exists, False otherwise.
Return type:: bool

has_edge_collection(name: str) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Check if the graph has the given edge collection.

Parameters:: name (str) – Edge collection name.
Returns:: True if edge collection exists, False otherwise.
Return type:: bool

edge_collection(name: str) → EdgeCollection[source]

Return the edge collection API wrapper.

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

edge_definitions() → List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None[source]

Return the edge definitions of the graph.

Returns:: Edge definitions of the graph.
Return type:: [dict]
Raises:: arango.exceptions.EdgeDefinitionListError – If retrieval fails.

create_edge_definition(edge_collection: str, from_vertex_collections: Sequence[str], to_vertex_collections: Sequence[str]) → EdgeCollection | AsyncJob[EdgeCollection] | BatchJob[EdgeCollection] | None[source]

Create a new edge definition.

An edge definition consists of an edge collection, “from” vertex collection(s) and “to” vertex collection(s). Here is an example entry:

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

Parameters:

edge_collection (str) – Edge collection name.
from_vertex_collections ([str]) – Names of “from” vertex collections.
to_vertex_collections ([str]) – Names of “to” vertex collections.

Returns:

Edge collection API wrapper.

Return type:

Raises:

arango.exceptions.EdgeDefinitionCreateError – If create fails.

replace_edge_definition(edge_collection: str, from_vertex_collections: Sequence[str], to_vertex_collections: Sequence[str]) → EdgeCollection | AsyncJob[EdgeCollection] | BatchJob[EdgeCollection] | None[source]

Replace an edge definition.

Parameters:

edge_collection (str) – Edge collection name.
from_vertex_collections ([str]) – Names of “from” vertex collections.
to_vertex_collections ([str]) – Names of “to” vertex collections.

Returns:

Edge collection API wrapper.

Return type:

arango.collection.EdgeCollection

Raises:

arango.exceptions.EdgeDefinitionReplaceError – If replace fails.

delete_edge_definition(name: str, purge: bool = False) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Delete an edge definition from the graph.

Parameters:

name (str) – Edge collection name.
purge (bool) – If set to True, the edge definition is not just removed from the graph but the edge collection is also deleted completely from the database.

Returns:

True if edge definition was deleted successfully.

Return type:

bool

Raises:

arango.exceptions.EdgeDefinitionDeleteError – If delete fails.

Traverse the graph and return the visited vertices and edges.

Parameters:

start_vertex (str | dict) – Start vertex document ID or body with “_id” field.
direction (str) – Traversal direction. Allowed values are “outbound” (default), “inbound” and “any”.
item_order (str) – Item iteration order. Allowed values are “forward” (default) and “backward”.
strategy (str | None) – Traversal strategy. Allowed values are “depthfirst” and “breadthfirst”.
order (str | None) – Traversal order. Allowed values are “preorder”, “postorder”, and “preorder-expander”.
edge_uniqueness (str | None) – Uniqueness for visited edges. Allowed values are “global”, “path” or “none”.
vertex_uniqueness (str | None) – Uniqueness for visited vertices. Allowed values are “global”, “path” or “none”.
max_iter (int | None) – If set, halt the traversal after the given number of iterations. This parameter can be used to prevent endless loops in cyclic graphs.
min_depth (int | None) – Minimum depth of the nodes to visit.
max_depth (int | None) – Maximum depth of the nodes to visit.
init_func (str | None) – Initialization function in Javascript with signature (config, result) -> void. This function is used to initialize values in the result.
sort_func (str | None) – Sorting function in Javascript with signature (left, right) -> integer, which returns -1 if left < right, +1 if left > right and 0 if left == right.
filter_func (str | None) – Filter function in Javascript with signature (config, vertex, path) -> mixed, where mixed can have one of the following values (or an array with multiple): “exclude” (do not visit the vertex), “prune” (do not follow the edges of the vertex), or “undefined” (visit the vertex and follow its edges).
visitor_func (str | None) – Visitor function in Javascript with signature (config, result, vertex, path, connected) -> void. The return value is ignored, result is modified by reference, and connected is populated only when parameter order is set to “preorder-expander”.
expander_func (str | None) – Expander function in Javascript with signature (config, vertex, path) -> mixed. The function must return an array of connections for vertex. Each connection is an object with attributes “edge” and “vertex”.

Returns:

Visited edges and vertices.

Return type:

dict

Raises:

arango.exceptions.GraphTraverseError – If traversal fails.

Check if the given vertex document exists in the graph.

Parameters:

vertex (str | dict) – Vertex document ID or body with “_id” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in vertex if present.
check_rev (bool) – If set to True, revision of vertex (if given) is compared against the revision of target vertex document.

Returns:

True if vertex document exists, False otherwise.

Return type:

bool

Raises:

arango.exceptions.DocumentGetError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Return a vertex document.

Parameters:

vertex (str | dict) – Vertex document ID or body with “_id” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in vertex if present.
check_rev (bool) – If set to True, revision of vertex (if given) is compared against the revision of target vertex document.

Returns:

Vertex document or None if not found.

Return type:

dict | None

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Insert a new vertex document.

Parameters:

collection (str) – Vertex collection name.
vertex (dict) – New vertex document to insert. If it has “_key” or “_id” field, its value is used as key of the new vertex (otherwise it is auto-generated). Any “_rev” field is ignored.
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:

arango.exceptions.DocumentInsertError – If insert fails.

Update a vertex document.

Parameters:

vertex (dict) – Partial or full vertex document with updated values. It must contain the “_id” field.
check_rev (bool) – If set to True, revision of vertex (if given) is compared against the revision of target vertex document.
keep_none (bool) – If set to True, fields with value None are retained in the document. If set to False, they are removed completely.
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:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Replace a vertex document.

Parameters:

vertex (dict) – New vertex document to replace the old one with. It must contain the “_id” field.
check_rev (bool) – If set to True, revision of vertex (if given) is compared against the revision of target vertex document.
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:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Delete a vertex document.

Parameters:

vertex (str | dict) – Vertex document ID or body with “_id” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in vertex if present.
check_rev (bool) – If set to True, revision of vertex (if given) is compared against the revision of target vertex 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.
sync (bool | None) – Block until operation is synchronized to disk.

Returns:

True if vertex was deleted successfully, False if vertex was not found and ignore_missing was set to True (does not apply in transactions).

Return type:

bool

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Check if the given edge document exists in the graph.

Parameters:

edge (str | dict) – Edge document ID or body with “_id” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in edge if present.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.

Returns:

True if edge document exists, False otherwise.

Return type:

bool

Raises:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Return an edge document.

Parameters:

edge (str | dict) – Edge document ID or body with “_id” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in edge if present.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.

Returns:

Edge document or None if not found.

Return type:

dict | None

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Insert a new edge document.

Parameters:

collection (str) – Edge collection name.
edge (dict) – New edge document to insert. It must contain “_from” and “_to” fields. If it has “_key” or “_id” field, its value is used as key of the new edge document (otherwise it is auto-generated). Any “_rev” field is ignored.
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:

arango.exceptions.DocumentInsertError – If insert fails.

Update an edge document.

Parameters:

edge (dict) – Partial or full edge document with updated values. It must contain the “_id” field.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.
keep_none (bool | None) – If set to True, fields with value None are retained in the document. If set to False, they are removed completely.
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:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Replace an edge document.

Parameters:

edge (dict) – New edge document to replace the old one with. It must contain the “_id” field. It must also contain the “_from” and “_to” fields.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge document.
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:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Delete an edge document.

Parameters:

edge (str | dict) – Edge document ID or body with “_id” field.
rev (str | None) – Expected document revision. Overrides the value of “_rev” field in edge if present.
check_rev (bool) – If set to True, revision of edge (if given) is compared against the revision of target edge 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.
sync (bool | None) – Block until operation is synchronized to disk.

Returns:

True if edge was deleted successfully, False if edge was not found and ignore_missing was set to True (does not apply in transactions).

Return type:

bool

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Insert a new edge document linking the given vertices.

Parameters:

collection (str) – Edge collection name.
from_vertex (str | dict) – “From” vertex document ID or body with “_id” field.
to_vertex (str | dict) – “To” vertex document ID or body with “_id” field.
data (dict) – Any extra data for the new edge document. If it has “_key” or “_id” field, its value is used as key of the new edge document (otherwise it is auto-generated).
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:

arango.exceptions.DocumentInsertError – If insert fails.

Return the edge documents coming in and/or out of given vertex.

Parameters:

collection (str) – Edge collection name.
vertex (str | dict) – Vertex document ID or body with “_id” field.
direction (str) – The direction of the edges. Allowed values are “in” and “out”. If not set, edges in both directions are returned.

Returns:

List of edges and statistics.

Return type:

dict

Raises:

arango.exceptions.EdgeListError – If retrieval fails.

HTTPClient

class arango.http.HTTPClient[source]

Abstract base class for HTTP clients.

abstract create_session(host: str) → Session[source]

Return a new requests session given the host URL.

This method must be overridden by the user.

Parameters:: host (str) – ArangoDB host URL.
Returns:: Requests session object.
Return type:: requests.Session

Send an HTTP request.

This method must be overridden by the user.

Parameters:

session (requests.Session) – Requests session object.
method (str) – HTTP method in lowercase (e.g. “post”).
url (str) – Request URL.
headers (dict) – Request headers.
params (dict) – URL (query) parameters.
data (str | bytes | MultipartEncoder | None) – Request payload.
auth (tuple) – Username and password.

Returns:

HTTP response.

Return type:

arango.response.Response

OverloadControlDatabase

class arango.database.OverloadControlDatabase(connection: BasicConnection | JwtConnection | JwtSuperuserConnection, max_queue_time_seconds: float | None = None)[source]

Database API wrapper tailored to gracefully handle server overload scenarios.

See arango.database.StandardDatabase.begin_controlled_execution().

Parameters:

connection – HTTP connection.
max_queue_time_seconds (Optional[float]) – Maximum server-side queuing time in seconds. If the server-side queuing time exceeds the client’s specified limit, the request will be rejected.

property last_queue_time: float

Return the most recently recorded server-side queuing time in seconds.

Returns:: Server-side queuing time in seconds.
Return type:: float

property max_queue_time: float | None

Return the maximum server-side queuing time in seconds.

Returns:: Maximum server-side queuing time in seconds.
Return type:: Optional[float]

adjust_max_queue_time(max_queue_time_seconds: float | None) → None[source]

Adjust the maximum server-side queuing time in seconds.

Parameters:: max_queue_time_seconds (Optional[float]) – New maximum server-side queuing time in seconds. Setting it to None disables the limit.

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 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 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:

name (str) – View name.
properties (dict | None) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

Raises:

arango.exceptions.CollectionCreateError – If create fails.

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 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:

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 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 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:

name (str) – View name.
view_type (str) – View type (e.g. “arangosearch” or “search-alias”).
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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 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:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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.

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:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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 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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

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:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

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:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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

Pregel

Pregel API wrapper.

job(job_id: int) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the details of a Pregel job.

Parameters:: job_id (int) – Pregel job ID.
Returns:: Details of the Pregel job.
Return type:: dict
Raises:: arango.exceptions.PregelJobGetError – If retrieval fails.

Start a new Pregel job.

Parameters:

graph (str) – Graph name.
algorithm (str) – Algorithm (e.g. “pagerank”).
store (bool) – If set to True, Pregel engine writes results back to the database. If set to False, results can be queried via AQL.
max_gss (int | None) – Max number of global iterations for the algorithm.
thread_count (int | None) – Number of parallel threads to use per worker. This does not influence the number of threads used to load or store data from the database (it depends on the number of shards).
async_mode (bool | None) – If set to True, algorithms which support async mode run without synchronized global iterations. This might lead to performance increase if there are load imbalances.
result_field (str | None) – If specified, most algorithms will write their results into this field.
algorithm_params (dict | None) – Additional algorithm parameters.
vertexCollections (Sequence[str] | None) – List of vertex collection names.
edgeCollections (Sequence[str] | None) – List of edge collection names.

Returns:

Pregel job ID.

Return type:

int

Raises:

arango.exceptions.PregelJobCreateError – If create fails.

delete_job(job_id: int) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Delete a Pregel job.

Parameters:: job_id (int) – Pregel job ID.
Returns:: True if Pregel job was deleted successfully.
Return type:: bool
Raises:: arango.exceptions.PregelJobDeleteError – If delete fails.

jobs() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Returns a list of currently running and recently: finished Pregel jobs without retrieving their results.

Returns:: Details of each running or recently finished Pregel job.
Return type:: dict
Raises:: arango.exceptions.PregelJobGetError – If retrieval fails.

Replication

Return an overview of collections and indexes.

Parameters:

batch_id (str) – Batch ID.
include_system (bool | None) – Include system collections in the result. Default value is True.
all_databases (bool | None) – Include all databases. Only works on “_system” database. Default value is False.

Returns:

Overview of collections and indexes.

Return type:

dict

Raises:

arango.exceptions.ReplicationInventoryError – If retrieval fails.

create_dump_batch(ttl: int | None = None) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Create a new dump batch.

Parameters:: ttl (int | None) – Time-to-live for the new batch in seconds.
Returns:: ID of the batch.
Return type:: dict
Raises:: arango.exceptions.ReplicationDumpBatchCreateError – If create fails.

delete_dump_batch(batch_id: str) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Delete a dump batch.

Parameters:: batch_id (str) – Dump batch ID.
Returns:: True if deletion was successful.
Return type:: bool
Raises:: arango.exceptions.ReplicationDumpBatchDeleteError – If delete fails.

extend_dump_batch(batch_id: str, ttl: int) → bool | AsyncJob[bool] | BatchJob[bool] | None[source]

Extend a dump batch.

Parameters:

batch_id (str) – Dump batch ID.
ttl (int) – Time-to-live for the new batch in seconds.

Returns:

True if operation was successful.

Return type:

bool

Raises:

arango.exceptions.ReplicationDumpBatchExtendError – If dump fails.

Return the events data of one collection.

Parameters:

collection (str) – Name or ID of the collection to dump.
batch_id (str | None) – Batch ID.
chunk_size (int | None) – Size of the result in bytes. This value is honored approximately only.
deserialize (bool) – Deserialize the response content. Default is False.

Returns:

Collection events data.

Return type:

str | [dict]

Raises:

arango.exceptions.ReplicationDumpError – If retrieval fails.

Synchronize data from a remote endpoint.

Parameters:

endpoint (str) – Master endpoint (e.g. “tcp://192.168.173.13:8529”).
database (str | None) – Database name.
username (str | None) – Username.
password (str | None) – Password.
include_system (bool | None) – Whether to include system collection operations.
incremental (bool | None) – If set to True, then an incremental synchronization method is used for synchronizing data in collections. This method is useful when collections already exist locally, and only the remaining differences need to be transferred from the remote endpoint. In this case, the incremental synchronization can be faster than a full synchronization. Default value is False, meaning complete data is transferred.
restrict_type (str | None) – Optional string value for collection filtering. Allowed values are “include” or “exclude”.
restrict_collections ([str] | None) – Optional list of collections for use with argument restrict_type. If restrict_type set to “include”, only the specified collections are synchronised. Otherwise, all but the specified ones are synchronized.
initial_sync_wait_time (int | None) – Maximum wait time in seconds that the initial synchronization will wait for a response from master when fetching collection data. This can be used to control after what time the initial synchronization will give up waiting for response and fail. Value is ignored if set to 0.

Returns:

Collections transferred and last log tick.

Return type:

dict

Raises:

arango.exceptions.ReplicationSyncError – If sync fails.

cluster_inventory(include_system: bool | None = None) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return an overview of collections and indexes in a cluster.

Parameters:: include_system (bool) – Include system collections in the result. Default value is True.
Returns:: Overview of collections and indexes on the cluster.
Return type:: dict
Raises:: arango.exceptions.ReplicationClusterInventoryError – If retrieval fails.

logger_state() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the state of the replication logger.

Returns:: Logger state.
Return type:: dict
Raises:: arango.exceptions.ReplicationLoggerStateError – If retrieval fails.

logger_first_tick() → str | AsyncJob[str] | BatchJob[str] | None[source]

Return the first available tick value from the server.

Returns:: First tick value.
Return type:: str
Raises:: arango.exceptions.ReplicationLoggerFirstTickError – If retrieval fails.

applier_config() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the configuration of the replication applier.

Returns:: Configuration of the replication applier.
Return type:: dict
Raises:: arango.exceptions.ReplicationApplierConfigError – If retrieval fails.

Set configuration values of the replication applier.

Parameters:

endpoint (str) – Server endpoint (e.g. “tcp://192.168.173.13:8529”).
database (str | None) – Database name.
username (str | None) – Username.
password (str | None) – Password.
max_connect_retries (int | None) – Maximum number of connection attempts the applier makes in a row before stopping itself.
connect_timeout (int | None) – Timeout in seconds when attempting to connect to the endpoint. This value is used for each connection attempt.
request_timeout (int | None) – Timeout in seconds for individual requests to the endpoint.
chunk_size (int | None) – Requested maximum size in bytes for log transfer packets when the endpoint is contacted.
auto_start (bool | None) – Whether to auto-start the replication applier on (next and following) server starts.
adaptive_polling (bool | None) – If set to True, replication applier sleeps for an increasingly long period in case the logger server at the endpoint has no replication events to apply. Using adaptive polling reduces the amount of work done by both the applier and the logger server when there are infrequent changes. The downside is that it might take longer for the replication applier to detect new events.
include_system (bool | None) – Whether system collection operations are applied.
auto_resync (bool | None) – Whether the slave should perform a full automatic resynchronization with the master in case the master cannot serve log data requested by the slave, or when the replication is started and no tick value can be found.
auto_resync_retries (int | None) – Max number of resynchronization retries. Setting this to 0 disables it.
initial_sync_max_wait_time (int | None) – Max wait time in seconds the initial synchronization waits for master on collection data. This value is relevant even for continuous replication when auto_resync is set to True because this may re-start the initial synchronization when master cannot provide log data slave requires. This value is ignored if set to 0.
connection_retry_wait_time (int | None) – Time in seconds the applier idles before trying to connect to master in case of connection problems. This value is ignored if set to 0.
idle_min_wait_time (int | None) – Minimum wait time in seconds the applier idles before fetching more log data from the master in case the master has already sent all its log data. This wait time can be used to control the frequency with which the replication applier sends HTTP log fetch requests to the master in case there is no write activity on the master. This value is ignored if set to 0.
idle_max_wait_time (int | None) – Maximum wait time in seconds the applier idles before fetching more log data from the master in case the master has already sent all its log data. This wait time can be used to control the maximum frequency with which the replication applier sends HTTP log fetch requests to the master in case there is no write activity on the master. Applies only when argument adaptive_polling is set to True. This value is ignored if set to 0.
require_from_present (bool | None) – If set to True, replication applier checks at start whether the start tick from which it starts or resumes replication is still present on the master. If not, then there would be data loss. If set to True, the replication applier aborts with an appropriate error message. If set to False, the applier still starts and ignores the data loss.
verbose (bool | None) – If set to True, a log line is emitted for all operations performed by the replication applier. This should be used for debugging replication problems only.
restrict_type (str | None) – Optional string value for collection filtering. Allowed values are “include” or “exclude”.
restrict_collections ([str] | None) – Optional list of collections for use with argument restrict_type. If restrict_type set to “include”, only the specified collections are included. Otherwise, only the specified collections are excluded.

Returns:

Updated configuration.

Return type:

dict

Raises:

arango.exceptions.ReplicationApplierConfigSetError – If update fails.

applier_state() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Return the state of the replication applier

Returns:: Applier state and details.
Return type:: dict
Raises:: arango.exceptions.ReplicationApplierStateError – If retrieval fails.

start_applier(last_tick: str | None = None) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Start the replication applier.

Parameters:: last_tick (str) – The remote last log tick value from which to start applying replication. If not specified, the last saved tick from the previous applier run is used. If there is no previous applier state saved, the applier starts at the beginning of the logger server’s log.
Returns:: Applier state and details.
Return type:: dict
Raises:: arango.exceptions.ReplicationApplierStartError – If operation fails.

stop_applier() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None[source]

Stop the replication applier.

Returns:: Applier state and details.
Return type:: dict
Raises:: arango.exceptions.ReplicationApplierStopError – If operation fails.

Change the server role to slave.

Parameters:

endpoint (str) – Master endpoint (e.g. “tcp://192.168.173.13:8529”).
database (str | None) – Database name.
username (str | None) – Username.
password (str | None) – Password.
restrict_type (str | None) – Optional string value for collection filtering. Allowed values are “include” or “exclude”.
restrict_collections ([str] | None) – Optional list of collections for use with argument restrict_type. If restrict_type set to “include”, only the specified collections are included. Otherwise, only the specified collections are excluded.
include_system (bool | None) – Whether system collection operations are applied.
max_connect_retries (int | None) – Maximum number of connection attempts the applier makes in a row before stopping itself.
connect_timeout (int | None) – Timeout in seconds when attempting to connect to the endpoint. This value is used for each connection attempt.
request_timeout (int | None) – Timeout in seconds for individual requests to the endpoint.
chunk_size (int | None) – Requested maximum size in bytes for log transfer packets when the endpoint is contacted.
adaptive_polling (bool | None) – If set to True, replication applier sleeps for an increasingly long period in case the logger server at the endpoint has no replication events to apply. Using adaptive polling reduces the amount of work done by both the applier and the logger server when there are infrequent changes. The downside is that it might take longer for the replication applier to detect new events.
auto_resync (bool | None) – Whether the slave should perform a full automatic resynchronization with the master in case the master cannot serve log data requested by the slave, or when the replication is started and no tick value can be found.
auto_resync_retries (int | None) – Max number of resynchronization retries. Setting this to 0 disables it.
initial_sync_max_wait_time (int | None) – Max wait time in seconds the initial synchronization waits for master on collection data. This value is relevant even for continuous replication when auto_resync is set to True because this may restart the initial synchronization when master cannot provide log data slave requires. This value is ignored if set to 0.
connection_retry_wait_time (int | None) – Time in seconds the applier idles before trying to connect to master in case of connection problems. This value is ignored if set to 0.
idle_min_wait_time (int | None) – Minimum wait time in seconds the applier idles before fetching more log data from the master in case the master has already sent all its log data. This wait time can be used to control the frequency with which the replication applier sends HTTP log fetch requests to the master in case there is no write activity on the master. This value is ignored if set to 0.
idle_max_wait_time (int | None) – Maximum wait time in seconds the applier idles before fetching more log data from the master in case the master has already sent all its log data. This wait time can be used to control the maximum frequency with which the replication applier sends HTTP log fetch requests to the master in case there is no write activity on the master. Applies only when argument adaptive_polling is set to True. This value is ignored if set to 0.
require_from_present (bool | None) – If set to True, replication applier checks at start whether the start tick from which it starts or resumes replication is still present on the master. If not, then there would be data loss. If set to True, the replication applier aborts with an appropriate error message. If set to False, the applier still starts and ignores the data loss.
verbose (bool | None) – If set to True, a log line is emitted for all operations performed by the replication applier. This should be used for debugging replication problems only.

Returns:

Replication details.

Return type:

dict

Raises:

arango.exceptions.ReplicationApplierStopError – If operation fails.

server_id() → str | AsyncJob[str] | BatchJob[str] | None[source]

Return this server’s ID.

Returns:: Server ID.
Return type:: str
Raises:: arango.exceptions.ReplicationServerIDError – If retrieval fails.

Request

HTTP request.

Parameters:

method (str) – HTTP method in lowercase (e.g. “post”).
endpoint (str) – API endpoint.
headers (dict | None) – Request headers.
params (dict | None) – URL parameters.
data (str | bool | int | float | list | dict | None | MultipartEncoder) – Request payload.
read (str | [str] | None) – Names of collections read during transaction.
write (str | [str] | None) – Name(s) of collections written to during transaction with shared access.
exclusive (str | [str] | None) – Name(s) of collections written to during transaction with exclusive access.
deserialize (bool) – Whether the response body can be deserialized.
driver_flags (list) – List of flags for the driver

Variables:

method (str) – HTTP method in lowercase (e.g. “post”).
endpoint (str) – API endpoint.
headers (dict | None) – Request headers.
params (dict | None) – URL (query) parameters.
data (str | bool | int | float | list | dict | None) – Request payload.
read (str | [str] | None) – Names of collections read during transaction.
write (str | [str] | None) – Name(s) of collections written to during transaction with shared access.
exclusive (str | [str] | None) – Name(s) of collections written to during transaction with exclusive access.
deserialize (bool) – Whether the response body can be deserialized.
driver_flags (list) – List of flags for the driver

Response

class arango.response.Response(method: str, url: str, headers: MutableMapping[str, str], status_code: int, status_text: str, raw_body: str)[source]

HTTP response.

Parameters:

method (str) – HTTP method in lowercase (e.g. “post”).
url (str) – API URL.
headers (MutableMapping) – Response headers.
status_code (int) – Response status code.
status_text (str) – Response status text.
raw_body (str) – Raw response body.

Variables:

method (str) – HTTP method in lowercase (e.g. “post”).
url (str) – API URL.
headers (MutableMapping) – Response headers.
status_code (int) – Response status code.
status_text (str) – Response status text.
raw_body (str) – Raw response body.
body (str | bool | int | float | list | dict | None) – JSON-deserialized response body.
error_code (int) – Error code from ArangoDB server.
error_message (str) – Error message from ArangoDB server.
is_success (bool) – True if response status code was 2XX.

StandardCollection

Standard ArangoDB collection API wrapper.

Return a document.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” 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.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document, or None if not found.

Return type:

dict | None

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Insert a new document.

Parameters:

document (dict) – Document to insert. If it contains the “_key” or “_id” field, the value is used as the key of the new document (otherwise it is auto-generated). Any “_rev” field is ignored.
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 existing document is overwritten (replace-insert).
return_old (bool) – Include body of the old document if overwritten. Ignored if parameter silent 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).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

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.

Update a document.

Parameters:

document (dict) – Partial or full document with the updated values. It must contain the “_id” or “_key” 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 returned metadata. Ignored if parameter silent is set to True.
return_old (bool) – Include body of the old 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

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

Return type:

bool | dict

Raises:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Replace a document.

Parameters:

document (dict) – New document to replace the old one with. It must contain the “_id” or “_key” 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 returned metadata. Ignored if parameter silent is set to True.
return_old (bool) – Include body of the old 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

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

Return type:

bool | dict

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Delete a document.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” 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 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.

Returns:

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:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

Create a new fulltext index. This method is deprecated: in ArangoDB 3.10 and will be removed in a future version of the driver.

Parameters:

fields ([str]) – Document fields to index.
min_length (int | None) – Minimum number of characters to index.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new geo-spatial index.

Parameters:

fields (str | [str]) – A single document field or a list of document fields. If a single field is given, the field must have values that are lists with at least two floats. Documents with missing fields or invalid values are excluded.
geo_json (bool | None) – Whether to use GeoJSON data-format or not. This parameter has been renamed from ordered. See Github Issue #234 for more details.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.
legacyPolygons (bool | None) – Whether or not to use use the old, pre-3.10 rules for the parsing GeoJSON polygons

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new hash index.

Parameters:

fields ([str]) – Document fields to index.
unique (bool | None) – Whether the index is unique.
sparse (bool | None) – If set to True, documents with None in the field are also indexed. If set to False, they are skipped.
deduplicate (bool | None) – If set to True, inserting duplicate index values from the same document triggers unique constraint errors.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new inverted index, introduced in version 3.10.

Parameters:

fields (Json) – Document fields to index.
name (str | None) – Optional name for the index.
inBackground (bool | None) – Do not hold the collection lock.
parallelism (int | None) – The number of threads to use for indexing the fields.
primarySort (Optional[Json]) – Primary sort order to enable an AQL optimization.
storedValues (Sequence[Json] | None) – An array of objects with paths to additional attributes to store in the index.
analyzer (Optional[str]) – Analyzer to use by default.
features (Sequence[str] | None) – List of Analyzer features.
includeAllFields (bool | None) – This option only applies if you use the inverted index in search-alias views.
trackListPositions (bool | None) – This option only applies if you use the inverted index in search-alias views, and searchField is true.
searchField (bool | None) – This option only applies if you use the inverted index in search-alias views
primaryKeyCache (bool | None) – Always cache the primary key column in memory.
cache (bool | None) – Always cache the field normalization values in memory for all fields by default.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new MDI index, previously known as ZKD index. This method: is only usable with ArangoDB 3.12 and later.

Parameters:

fields (Sequence[str]) – Document fields to index. Unlike for other indexes the order of the fields does not matter.
field_value_types (str) – The type of the field values. The only allowed value is “double” at the moment. Defaults to “double”.
name (str | None) – Optional name for the index.
unique (bool | None) – Whether the index is unique.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new persistent index.

Unique persistent indexes on non-sharded keys are not supported in a cluster.

Parameters:

fields ([str]) – Document fields to index.
unique (bool | None) – Whether the index is unique.
sparse (bool | None) – Exclude documents that do not contain at least one of the indexed fields, or documents that have a value of None in any of the indexed fields.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.
storedValues ([str]) – Additional attributes to include in a persistent index. These additional attributes cannot be used for index lookups or sorts, but they can be used for projections. Must be an array of index attribute paths. There must be no overlap of attribute paths between fields and storedValues. The maximum number of values is 32.
cacheEnabled (bool | None) – Enable an in-memory cache for index values for persistent indexes.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new skiplist index.

Parameters:

fields ([str]) – Document fields to index.
unique (bool | None) – Whether the index is unique.
sparse (bool | None) – If set to True, documents with None in the field are also indexed. If set to False, they are skipped.
deduplicate (bool | None) – If set to True, inserting duplicate index values from the same document triggers unique constraint errors.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new TTL (time-to-live) index.

Parameters:

fields ([str]) – Document field to index.
expiry_time (int) – Time of expiry in seconds after document creation.
name (str | None) – Optional name for the index.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Create a new ZKD Index.

Parameters:

fields (Sequence[str]) – Document fields to index. Unlike for other indexes the order of the fields does not matter.
field_value_types (str) – The type of the field values. The only allowed value is “double” at the moment. Defaults to “double”.
name (str | None) – Optional name for the index.
unique (bool | None) – Whether the index is unique.
in_background (bool | None) – Do not hold the collection lock.

Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

Return all documents in the collection.

Parameters:

skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

checksum(with_rev: bool = False, with_data: bool = False) → str | AsyncJob[str] | BatchJob[str] | None

Return collection checksum.

Parameters:

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

Returns:

Collection checksum.

Return type:

str

Raises:

arango.exceptions.CollectionChecksumError – If retrieval fails.

compact() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Compact a collection.

Compacts the data of a collection in order to reclaim disk space. The operation will compact the document and index data by rewriting the underlying .sst files and only keeping the relevant entries.

Under normal circumstances, running a compact operation is not necessary, as the collection data will eventually get compacted anyway. However, in some situations, e.g. after running lots of update/replace or remove operations, the disk data for a collection may contain a lot of outdated data for which the space shall be reclaimed. In this case the compaction operation can be used.

Returns:: Collection compact.
Return type:: dict
Raises:: arango.exceptions.CollectionCompactError – If retrieval fails.

Configure collection properties.

Parameters:

sync (bool | None) – Block until operations are synchronized to disk.
schema (dict) – document schema for validation of objects.
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.
computed_values (dict | None) – Define expressions on the collection level that run on inserts, modifications, or both.

Returns:

New collection properties.

Return type:

dict

Raises:

arango.exceptions.CollectionConfigureError – If operation 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

count() → int | AsyncJob[int] | BatchJob[int] | None

Return the total document count.

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

property db_name: str

Return the name of the current database.

Returns:: Database name.
Return type:: str

delete_index(index_id: str, ignore_missing: bool = False) → bool | AsyncJob[bool] | BatchJob[bool] | None

Delete an index.

Parameters:

index_id (str) – Index ID.
ignore_missing (bool) – Do not raise an exception on missing index.

Returns:

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

Return type:

bool

Raises:

arango.exceptions.IndexDeleteError – If delete fails.

Delete multiple documents.

Note

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

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single delete operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([str | dict]) – Document IDs, keys or bodies. Document bodies must contain the “_id” or “_key” fields.
return_old (bool) – Include bodies of the old documents in the result.
check_rev (bool) – If set to True, revisions of documents (if given) are compared against the revisions of target documents.
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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.

Returns:

List of document metadata (e.g. document keys, revisions) and any exceptions, or True if parameter silent was set to True.

Return type:

[dict | ArangoServerError] | bool

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.

Delete matching documents.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single delete operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

filters (dict) – Document filters.
limit (int | None) – Max number of documents to delete. If the limit is lower than the number of matched documents, random documents are chosen.
sync (bool | None) – Block until operation is synchronized to disk.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Number of documents deleted.

Return type:

int

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.

Return all documents that match the given filters.

Parameters:

filters (dict) – Document filters.
skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_by_text(field: str, query: str, limit: int | None = None, allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None

Return documents that match the given fulltext query.

Parameters:

field (str) – Document field with fulltext index.
query (str) – Fulltext query.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Return all documents in a rectangular area.

Parameters:

latitude1 (int | float) – First latitude.
longitude1 (int | float) – First longitude.
latitude2 (int | float) – Second latitude.
longitude2 (int | float) – Second longitude
skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
index (str | None) – ID of the geo index to use (without the collection prefix). This parameter is ignored in transactions.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_in_radius(latitude: Number, longitude: Number, radius: Number, distance_field: str | None = None, allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None

Return documents within a given radius around a coordinate.

A geo index must be defined in the collection to use this method.

Parameters:

latitude (int | float) – Latitude.
longitude (int | float) – Longitude.
radius (int | float) – Max radius.
distance_field (str) – Document field used to indicate the distance to the given coordinate. This parameter is ignored in transactions.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Return documents within a given range in a random order.

A skiplist index must be defined in the collection to use this method.

Parameters:

field (str) – Document field name.
lower (int) – Lower bound (inclusive).
upper (int) – Upper bound (exclusive).
skip (int | None) – Number of documents to skip.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_near(latitude: Number, longitude: Number, limit: int | None = None, allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None

Return documents near a given coordinate.

Documents returned are sorted according to distance, with the nearest document being the first. If there are documents of equal distance, they are randomly chosen from the set until the limit is reached. A geo index must be defined in the collection to use this method.

Parameters:

latitude (int | float) – Latitude.
longitude (int | float) – Longitude.
limit (int | None) – Max number of documents returned.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Document cursor.

Return type:

arango.database.BatchDatabase

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

get_index(id: str) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the index with the given id.

Parameters:: id (str) – The id of the index
Returns:: Index details
Return type:: dict
Raises:: arango.exceptions.IndexGetError – If retrieval fails.

get_many(documents: Sequence[str | Dict[str, Any]], allow_dirty_read: bool = False) → List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return multiple documents ignoring any missing ones.

Parameters:

documents ([str | dict]) – List of document keys, IDs or bodies. Document bodies must contain the “_id” or “_key” fields.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Documents. Missing ones are not included.

Return type:

[dict]

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

Check if a document exists in the collection.

Parameters:

document (str | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
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.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

True if document exists, False otherwise.

Return type:

bool

Raises:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

ids(allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None

Return the IDs of all documents in the collection.

Parameters:: allow_dirty_read (bool) – Allow reads from followers in a cluster.
Returns:: Document ID cursor.
Return type:: arango.cursor.Cursor
Raises:: arango.exceptions.DocumentIDsError – If retrieval fails.

Insert multiple documents into the collection.

Note

This method is faster than arango.collection.Collection.insert_many() but does not return as many details.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single insert operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – List of new documents to insert. If they contain the “_key” or “_id” fields, the values are used as the keys of the new documents (auto-generated otherwise). Any “_rev” field is ignored.
halt_on_error (bool) – Halt the entire import on an error.
details (bool) – If set to True, the returned result will include an additional list of detailed error messages.
from_prefix (str) – String prefix prepended to the value of “_from” field in each edge document inserted. For example, prefix “foo” prepended to “_from”: “bar” will result in “_from”: “foo/bar”. Applies only to edge collections.
to_prefix (str) – String prefix prepended to the value of “_to” field in edge document inserted. For example, prefix “foo” prepended to “_to”: “bar” will result in “_to”: “foo/bar”. Applies only to edge collections.
overwrite (bool) – If set to True, all existing documents are removed prior to the import. Indexes are still preserved.
on_duplicate (str) – Action to take on unique key constraint violations (for documents with “_key” fields). Allowed values are “error” (do not import the new documents and count them as errors), “update” (update the existing documents while preserving any fields missing in the new ones), “replace” (replace the existing documents with new ones), and “ignore” (do not import the new documents and count them as ignored, as opposed to counting them as errors). Options “update” and “replace” may fail on secondary unique key constraint violations.
sync (bool | None) – Block until operation is synchronized to disk.
batch_size (int) – Split up documents into batches of max length batch_size and import them in a loop on the client side. If batch_size is specified, the return type of this method changes from a result object to a list of result objects. IMPORTANT NOTE: this parameter may go through breaking changes in the future where the return type may not be a list of result objects anymore. Use it at your own risk, and avoid depending on the return value if possible. Cannot be used with parameter overwrite.

Returns:

Result of the bulk import.

Return type:

dict | list[dict]

Raises:

arango.exceptions.DocumentInsertError – If import fails.

indexes() → List[Dict[str, Any]] | AsyncJob[List[Dict[str, Any]]] | BatchJob[List[Dict[str, Any]]] | None

Return the collection indexes.

Returns:: Collection indexes.
Return type:: [dict]
Raises:: arango.exceptions.IndexListError – If retrieval fails.

info() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return the collection information.

Returns:: Information about the collection.
Return type:: dict
Raises:: arango.exceptions.CollectionInformationError – If retrieval fails.

Insert multiple documents.

Note

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

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single insert operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – List of new documents to insert. If they contain the “_key” or “_id” fields, the values are used as the keys of the new documents (auto-generated otherwise). Any “_rev” field is ignored.
return_new (bool) – Include bodies of the new documents 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 keys and the existing documents are replaced.
return_old (bool) – Include body of the old documents 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), “update” (update-insert), “ignore” or “conflict”. 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).
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document insertions affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

List of document metadata (e.g. document keys, revisions) and any exception, or True if parameter silent was set to True.

Return type:

[dict | ArangoServerError] | bool

Raises:

arango.exceptions.DocumentInsertError – If insert fails.

keys(allow_dirty_read: bool = False) → Cursor | AsyncJob[Cursor] | BatchJob[Cursor] | None

Return the keys of all documents in the collection.

Parameters:: allow_dirty_read (bool) – Allow reads from followers in a cluster.
Returns:: Document key cursor.
Return type:: arango.cursor.Cursor
Raises:: arango.exceptions.DocumentKeysError – If retrieval fails.

load() → bool | AsyncJob[bool] | BatchJob[bool] | None

Load the collection into memory.

Returns:: True if collection was loaded successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionLoadError – If operation fails.

load_indexes() → bool | AsyncJob[bool] | BatchJob[bool] | None

Cache all indexes in the collection into memory.

Returns:: True if index was loaded successfully.
Return type:: bool
Raises:: arango.exceptions.IndexLoadError – If operation fails.

property name: str

Return collection name.

Returns:: Collection name.
Return type:: str

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

Return collection properties.

Returns:: Collection properties.
Return type:: dict
Raises:: arango.exceptions.CollectionPropertiesError – If retrieval fails.

Return a random document from the collection. Returns None if the collection is empty.

Parameters:: allow_dirty_read (bool) – Allow reads from followers in a cluster.
Returns:: A random document.
Return type:: dict
Raises:: arango.exceptions.DocumentGetError – If retrieval fails.

recalculate_count() → bool | AsyncJob[bool] | BatchJob[bool] | None

Recalculate the document count.

Returns:: True if recalculation was successful.
Return type:: bool
Raises:: arango.exceptions.CollectionRecalculateCountError – If operation fails.

rename(new_name: str) → bool | AsyncJob[bool] | BatchJob[bool] | None

Rename the collection.

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

Parameters:: new_name (str) – New collection name.
Returns:: True if collection was renamed successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionRenameError – If rename fails.

Replace multiple documents.

Note

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

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single replace operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – New documents to replace the old ones with. They must contain the “_id” or “_key” fields. Edge documents must also have “_from” and “_to” fields.
check_rev (bool) – If set to True, revisions of documents (if given) are compared against the revisions of target documents.
return_new (bool) – Include body of the new document in the returned metadata. Ignored if parameter silent is set to True.
return_old (bool) – Include body of the old 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

List of document metadata (e.g. document keys, revisions) and any exceptions, or True if parameter silent was set to True.

Return type:

[dict | ArangoServerError] | bool

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.

Replace matching documents.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single replace operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

filters (dict) – Document filters.
body (dict) – New document body.
limit (int | None) – Max number of documents to replace. If the limit is lower than the number of matched documents, random documents are chosen.
sync (bool | None) – Block until operation is synchronized to disk.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Number of documents replaced.

Return type:

int

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.

responsible_shard(document: Dict[str, Any]) → str | AsyncJob[str] | BatchJob[str] | None

Return the ID of the shard responsible for given document.

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

Returns:: Shard ID
Return type:: str

revision() → str | AsyncJob[str] | BatchJob[str] | None

Return collection revision.

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

shards(details: bool = False) → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return collection shards and properties.

Available only in a cluster setup.

Parameters:: details (bool) – Include responsible servers for each shard.
Returns:: Collection shards and properties.
Return type:: dict
Raises:: arango.exceptions.CollectionShardsError – If retrieval fails.

statistics() → Dict[str, Any] | AsyncJob[Dict[str, Any]] | BatchJob[Dict[str, Any]] | None

Return collection statistics.

Returns:: Collection statistics.
Return type:: dict
Raises:: arango.exceptions.CollectionStatisticsError – If retrieval fails.

truncate() → bool | AsyncJob[bool] | BatchJob[bool] | None

Delete all documents in the collection.

Returns:: True if collection was truncated successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionTruncateError – If operation fails.

unload() → bool | AsyncJob[bool] | BatchJob[bool] | None

Unload the collection from memory.

Returns:: True if collection was unloaded successfully.
Return type:: bool
Raises:: arango.exceptions.CollectionUnloadError – If operation fails.

Update multiple documents.

Note

If updating a document fails, the exception is not raised but returned as an object in the result list. It is up to you to inspect the list to determine which documents were updated successfully (returns document metadata) and which were not (returns exception object). Alternatively, you can rely on setting raise_on_document_error to True (defaults to False).

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single update operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

documents ([dict]) – Partial or full documents with the updated values. They must contain the “_id” or “_key” fields.
check_rev (bool) – If set to True, revisions of documents (if given) are compared against the revisions of target documents.
merge (bool | None) – If set to True, sub-dictionaries are merged instead of the new ones overwriting the old ones.
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 returned metadata. Ignored if parameter silent is set to True.
return_old (bool) – Include body of the old 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.
refill_index_caches (bool | None) – Whether to add new entries to in-memory index caches if document operations affect the edge index or cache-enabled persistent indexes.
raise_on_document_error (bool) – Whether to raise if a DocumentRevisionError or a DocumentUpdateError is encountered on an individual document, as opposed to returning the error as an object in the result list. Defaults to False.
version_attribute (str) – support for simple external versioning to document operations.

Returns:

List of document metadata (e.g. document keys, revisions) and any exceptions, or True if parameter silent was set to True.

Return type:

[dict | ArangoError] | bool

Raises:

arango.exceptions.DocumentUpdateError – If update fails.

Update matching documents.

Note

In edge/vertex collections, this method does NOT provide the transactional guarantees and validations that single update operation does for graphs. If these properties are required, see arango.database.StandardDatabase.begin_batch_execution() for an alternative approach.

Parameters:

filters (dict) – Document filters.
body (dict) – Full or partial document body with the updates.
limit (int | None) – Max number of documents to update. If the limit is lower than the number of matched documents, random documents are chosen. This parameter is not supported on sharded collections.
keep_none (bool | None) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.
sync (bool | None) – Block until operation is synchronized to disk.
merge (bool | None) – If set to True, sub-dictionaries are merged instead of the new ones overwriting the old ones.
allow_dirty_read (bool) – Allow reads from followers in a cluster.

Returns:

Number of documents updated.

Return type:

int

Raises:

arango.exceptions.DocumentUpdateError – If update fails.

property username: str | None

Return the username.

Returns:: Username.
Return type:: str

StandardDatabase

class arango.database.StandardDatabase(connection: BasicConnection | JwtConnection | JwtSuperuserConnection)[source]

Standard database API wrapper.

begin_async_execution(return_result: bool = True) → AsyncDatabase[source]

Begin async execution.

Parameters:: 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.
Returns:: Database API wrapper object specifically for async execution.
Return type:: arango.database.AsyncDatabase

begin_batch_execution(return_result: bool = True, max_workers: int | None = 1) → BatchDatabase[source]

Begin batch execution.

Warning

The batch request API is deprecated since ArangoDB 3.8.0. This functionality should no longer be used. To send multiple documents at once to an ArangoDB instance, please use any of arango.collection.Collection methods that accept a list of documents as input. See insert_many(), update_many(), replace_many(), delete_many().

Parameters:

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]) – Maximum number of workers to use for submitting requests asynchronously. If None, the default value is the minimum between os.cpu_count() and the number of requests.

Returns:

Database API wrapper object specifically for batch execution.

Return type:

fetch_transaction(transaction_id: str) → TransactionDatabase[source]

Fetch an existing transaction.

Parameters:: transaction_id (str) – The ID of the existing transaction.

Begin a transaction.

Parameters:

read (str | [str] | None) – Name(s) of collections read during transaction. Read-only collections are added lazily but should be declared if possible to avoid deadlocks.
write (str | [str] | None) – Name(s) of collections written to during transaction with shared access.
exclusive (str | [str] | None) – Name(s) of collections written to during transaction with exclusive access.
sync (bool | None) – Block until operation is synchronized to disk.
allow_implicit (bool | None) – Allow reading from undeclared collections.
lock_timeout (int | None) – Timeout for waiting on collection locks. If not given, a default value is used. Setting it to 0 disables the timeout.
max_size (int | None) – Max transaction size in bytes.

Returns:

Database API wrapper object specifically for transactions.

Return type:

arango.database.TransactionDatabase

begin_controlled_execution(max_queue_time_seconds: float | None = None) → OverloadControlDatabase[source]

Begin a controlled connection, with options to handle server-side overload.

Parameters:: max_queue_time_seconds (Optional[float]) – Maximum time in seconds a request can be queued on the server-side. If set to 0 or None, the server ignores this setting.
Returns:: Database API wrapper object specifically for queue bounded execution.
Return type:: arango.database.OverloadControlDatabase

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 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 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:

name (str) – View name.
properties (dict | None) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

Raises:

arango.exceptions.CollectionCreateError – If create fails.

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 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:

See arango.database.StandardDatabase.begin_transaction().

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 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 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:

name (str) – View name.
view_type (str) – View type (e.g. “arangosearch” or “search-alias”).
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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 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:

arango.exceptions.DocumentDeleteError – If delete fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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.

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:

arango.exceptions.DocumentGetError – If retrieval fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

arango.exceptions.DocumentInError – If check fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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 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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

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:

arango.exceptions.DocumentReplaceError – If replace fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

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:

arango.exceptions.DocumentUpdateError – If update fails.
arango.exceptions.DocumentRevisionError – If revisions mismatch.

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 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:

name (str) – View name.
properties (dict) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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

TransactionDatabase

Database API wrapper tailored specifically for transactions.

Parameters:

connection – HTTP connection.
read (str | [str] | None) – Name(s) of collections read during transaction. Read-only collections are added lazily but should be declared if possible to avoid deadlocks.
write (str | [str] | None) – Name(s) of collections written to during transaction with shared access.
exclusive (str | [str] | None) – Name(s) of collections written to during transaction with exclusive access.
sync (bool | None) – Block until operation is synchronized to disk.
allow_implicit (bool | None) – Allow reading from undeclared collections.
lock_timeout (int | None) – Timeout for waiting on collection locks. If not given, a default value is used. Setting it to 0 disables the timeout.
max_size (int | None) – Max transaction size in bytes.
transaction_id (str | None) – Initialize using an existing transaction instead of creating a new transaction.

property transaction_id: str

Return the transaction ID.

Returns:: Transaction ID.
Return type:: str

transaction_status() → str[source]

Return the transaction status.

Returns:: Transaction status.
Return type:: str
Raises:: arango.exceptions.TransactionStatusError – If retrieval fails.

commit_transaction() → bool[source]

Commit the transaction.

Returns:: True if commit was successful.
Return type:: bool
Raises:: arango.exceptions.TransactionCommitError – If commit fails.

abort_transaction() → bool[source]

Abort the transaction.

Returns:: True if the abort operation was successful.
Return type:: bool
Raises:: arango.exceptions.TransactionAbortError – If abort fails.

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 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 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:

name (str) – View name.
properties (dict | None) – View properties. For more information see https://www.arangodb.com/docs/stable/http/views-arangosearch.html

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:

Raises:

arango.exceptions.CollectionCreateError – If create fails.

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 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: