API Specification

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

ArangoClient

class arango.client.ArangoClient(protocol=u'http', host=u'127.0.0.1', port=8529, http_client=None)

ArangoDB client.

Parameters:
  • protocol (str | unicode) – Internet transfer protocol (default: “http”).
  • host (str | unicode) – ArangoDB host (default: “127.0.0.1”).
  • port (int) – ArangoDB port (default: 8529).
  • http_client (arango.http.HTTPClient) – User-defined HTTP client.
base_url

Return the ArangoDB base URL.

Returns:ArangoDB base URL.
Return type:str | unicode
db(name=u'_system', username=u'root', password=u'', verify=False)

Connect to a database and return the database API wrapper.

Parameters:
  • name (str | unicode) – Database name.
  • username (str | unicode) – Username for basic authentication.
  • password (str | unicode) – Password for basic authentication.
  • verify (bool) – Verify the connection by sending a test request.
Returns:

Standard database API wrapper.

Return type:

arango.database.StandardDatabase

Raises:

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

host

Return the ArangoDB host.

Returns:ArangoDB host.
Return type:str | unicode
port

Return the ArangoDB port.

Returns:ArangoDB port.
Return type:int
protocol

Return the internet transfer protocol (e.g. “http”).

Returns:Internet transfer protocol.
Return type:str | unicode
version

Return the client version.

Returns:Client version.
Return type:str | unicode

AsyncDatabase

class arango.database.AsyncDatabase(connection, return_result)

Database API wrapper tailored specifically for async execution.

See arango.database.StandardDatabase.begin_async_execution().

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

Return AQL (ArangoDB Query Language) API wrapper.

Returns:AQL API wrapper.
Return type:arango.aql.AQL
async_jobs(status, count=None)

Return IDs of async jobs with given status.

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

List of job IDs.

Return type:

[str | unicode]

Raises:

arango.exceptions.AsyncJobListError – If retrieval fails.

clear_async_jobs(threshold=None)

Clear async job results from the server.

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

Parameters:threshold (int) – 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.
collection(name)

Return the standard collection API wrapper.

Parameters:name (str | unicode) – Collection name.
Returns:Standard collection API wrapper.
Return type:arango.collection.StandardCollection
collections()

Return the collections in the database.

Returns:Collections in the database and their details.
Return type:[dict]
Raises:arango.exceptions.CollectionListError – If retrieval fails.
context

Return the API execution context.

Returns:API execution context. Possible values are “default”, “async”, “batch” and “transaction”.
Return type:str | unicode
create_collection(name, sync=False, compact=True, system=False, journal_size=None, edge=False, volatile=False, user_keys=True, key_increment=None, key_offset=None, key_generator=u'traditional', shard_fields=None, shard_count=None, index_bucket_count=None, replication_factor=None, shard_like=None, sync_replication=None, enforce_replication_factor=None)

Create a new collection.

Parameters:
  • name (str | unicode) – Collection name.
  • sync (bool) – If set to True, document operations via the collection will block until synchronized to disk by default.
  • compact (bool) – If set to True, the collection is compacted. Applies only to MMFiles storage engine.
  • system (bool) – If set to True, a system collection is created. The collection name must have leading underscore “_” character.
  • journal_size (int) – Max size of the journal in bytes.
  • edge (bool) – If set to True, an edge collection is created.
  • volatile (bool) – If set to True, collection data is kept in-memory only and not made persistent. Unloading the collection will cause the collection data to be discarded. Stopping or re-starting the server will also cause full loss of data.
  • key_generator (str | unicode) – 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 | unicode]) – Field(s) used to determine the target shard.
  • shard_count (int) – Number of shards to create.
  • index_bucket_count (int) – Number of buckets into which indexes using hash tables are split. The default is 16, and this number has to be a power of 2 and less than or equal to 1024. For large collections, one should increase this to avoid long pauses when the hash table has to be initially built or re-sized, since buckets are re-sized individually and can be initially built in parallel. For instance, 64 may be a sensible value for 100 million documents.
  • 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 | unicode) – 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.
Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

Raises:

arango.exceptions.CollectionCreateError – If create fails.

create_database(name, users=None)

Create a new database.

Parameters:
  • name (str | unicode) – 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.
Returns:

True if database was created successfully.

Return type:

bool

Raises:

arango.exceptions.DatabaseCreateError – If create fails.

Here is an example entry for parameter users:

{
    'username': 'john',
    'password': 'password',
    'active': True,
    'extra': {'Department': 'IT'}
}
create_graph(name, edge_definitions=None, orphan_collections=None, smart=None, smart_field=None, shard_count=None)

Create a new graph.

Parameters:
  • name (str | unicode) – Graph name.
  • edge_definitions ([dict]) – 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 | unicode]) – Names of additional vertex collections that are not in edge definitions.
  • smart (bool) – If set to True, sharding is enabled (see parameter smart_field below). Applies only to enterprise version of ArangoDB.
  • smart_field (str | unicode) – 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) – 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.
Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

Raises:

arango.exceptions.GraphCreateError – If create fails.

Here is an example entry for parameter edge_definitions:

{
    'edge_collection': 'teach',
    'from_vertex_collections': ['teachers'],
    'to_vertex_collections': ['lectures']
}
create_task(name, command, params=None, period=None, offset=None, task_id=None)

Create a new server task.

Parameters:
  • name (str | unicode) – Name of the server task.
  • command (str | unicode) – Javascript command to execute.
  • params (dict) – Optional parameters passed into the Javascript command.
  • period (int) – 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) – Initial delay before execution in seconds.
  • task_id (str | unicode) – Pre-defined ID for the new server task.
Returns:

Details of the new task.

Return type:

dict

Raises:

arango.exceptions.TaskCreateError – If create fails.

create_user(username, password, active=True, extra=None)

Create a new user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – Password.
  • active (bool) – True if user is active, False otherwise.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserCreateError – If create fails.

create_view(name, view_type, properties=None)

Create a view.

Parameters:
  • name (str | unicode) – View name.
  • view_type (str | unicode) – View type (e.g. “arangosearch”).
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

databases()

Return the names all databases.

Returns:Database names.
Return type:[str | unicode]
Raises:arango.exceptions.DatabaseListError – If retrieval fails.
db_name

Return the name of the current database.

Returns:Database name.
Return type:str | unicode
delete_collection(name, ignore_missing=False, system=None)

Delete the collection.

Parameters:
  • name (str | unicode) – 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, ignore_missing=False)

Delete the database.

Parameters:
  • name (str | unicode) – Database name.
  • ignore_missing (bool) – Do not raise an exception on missing database.
Returns:

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

Return type:

bool

Raises:

arango.exceptions.DatabaseDeleteError – If delete fails.

delete_document(document, rev=None, check_rev=True, ignore_missing=False, return_old=False, sync=None, silent=False)

Delete a document.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” field.
  • rev (str | unicode) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
delete_graph(name, ignore_missing=False, drop_collections=None)

Drop the graph of the given name from the database.

Parameters:
  • name (str | unicode) – Graph name.
  • ignore_missing (bool) – Do not raise an exception on missing graph.
  • drop_collections (bool) – 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, ignore_missing=False)

Delete a server task.

Parameters:
  • task_id (str | unicode) – 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, ignore_missing=False)

Delete a user.

Parameters:
  • username (str | unicode) – 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, ignore_missing=False)

Delete a view.

Parameters:name (str | unicode) – View name.
Returns:True if view was deleted successfully, False if view was not found and ignore_missing was set to True.
Return type:dict
Raises:arango.exceptions.ViewDeleteError – If delete fails.
details()

Return ArangoDB server details.

Returns:Server details.
Return type:dict
Raises:arango.exceptions.ServerDetailsError – If retrieval fails.
document(document, rev=None, check_rev=True)

Return a document.

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

Document, or None if not found.

Return type:

dict | None

Raises:
echo()

Return details of the last request (e.g. headers, payload).

Returns:Details of the last request.
Return type:dict
Raises:arango.exceptions.ServerEchoError – If retrieval fails.
endpoints()

Return coordinate endpoints. This method is for clusters only.

Returns:List of endpoints.
Return type:[str | unicode]
Raises:arango.exceptions.ServerEndpointsError – If retrieval fails.
engine()

Return the database engine details.

Returns:Database engine details.
Return type:str | unicode
Raises:arango.exceptions.ServerEngineError – If retrieval fails.
execute_transaction(command, params=None, read=None, write=None, sync=None, timeout=None, max_size=None, allow_implicit=None, intermediate_commit_count=None, intermediate_commit_size=None)

Execute raw Javascript command in transaction.

Parameters:
  • command (str | unicode) – Javascript command to execute.
  • read ([str | unicode]) – Names of collections read during transaction. If parameter allow_implicit is set to True, any undeclared read collections are loaded lazily.
  • write ([str | unicode]) – Names of collections written to during transaction. Transaction fails on undeclared write collections.
  • params (dict) – Optional parameters passed into the Javascript command.
  • sync (bool) – Block until operation is synchronized to disk.
  • timeout (int) – 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) – Max transaction size limit in bytes. Applies only to RocksDB storage engine.
  • allow_implicit (bool) – If set to True, undeclared read collections are loaded lazily. If set to False, transaction fails on any undeclared collections.
  • intermediate_commit_count (int) – Max number of operations after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
  • intermediate_commit_size (int) – Max size of operations in bytes after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
Returns:

Return value of command.

Return type:

str | unicode

Raises:

arango.exceptions.TransactionExecuteError – If execution fails.

foxx

Return Foxx API wrapper.

Returns:Foxx API wrapper.
Return type:arango.foxx.Foxx
graph(name)

Return the graph API wrapper.

Parameters:name (str | unicode) – Graph name.
Returns:Graph API wrapper.
Return type:arango.graph.Graph
graphs()

List all graphs in the database.

Returns:Graphs in the database.
Return type:[dict]
Raises:arango.exceptions.GraphListError – If retrieval fails.
has_collection(name)

Check if collection exists in the database.

Parameters:name (str | unicode) – Collection name.
Returns:True if collection exists, False otherwise.
Return type:bool
has_database(name)

Check if a database exists.

Parameters:name (str | unicode) – Database name.
Returns:True if database exists, False otherwise.
Return type:bool
has_document(document, rev=None, check_rev=True)

Check if a document exists.

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

True if document exists, False otherwise.

Return type:

bool

Raises:
has_graph(name)

Check if a graph exists in the database.

Parameters:name (str | unicode) – Graph name.
Returns:True if graph exists, False otherwise.
Return type:bool
has_user(username)

Check if user exists.

Parameters:username (str | unicode) – Username.
Returns:True if user exists, False otherwise.
Return type:bool
insert_document(collection, document, return_new=False, sync=None, silent=False, overwrite=False, return_old=False)

Insert a new document.

Parameters:
  • collection (str | unicode) – 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) – 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.
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.

log_levels()

Return current logging levels.

Returns:Current logging levels.
Return type:dict
name

Return database name.

Returns:Database name.
Return type:str | unicode
permission(username, database, collection=None)

Return user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

Permission for given database or collection.

Return type:

str | unicode

Raise:

arango.exceptions.PermissionGetError: If retrieval fails.

permissions(username)

Return user permissions for all databases and collections.

Parameters:username (str | unicode) – Username.
Returns:User permissions for all databases and collections.
Return type:dict
Raise:arango.exceptions.PermissionListError: If retrieval fails.
ping()

Ping the ArangoDB server by sending a test request.

Returns:Response code from server.
Return type:int
Raises:arango.exceptions.ServerConnectionError – If ping fails.
pregel

Return Pregel API wrapper.

Returns:Pregel API wrapper.
Return type:arango.pregel.Pregel
properties()

Return database properties.

Returns:Database properties.
Return type:dict
Raises:arango.exceptions.DatabasePropertiesError – If retrieval fails.
read_log(upto=None, level=None, start=None, size=None, offset=None, search=None, sort=None)

Read the global log from server.

Parameters:
  • upto (str | unicode | int) – 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 (str | unicode | int) – 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 | unicode) – Return only the log entries containing the given text.
  • sort (str | unicode) – 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.

reload_routing()

Reload the routing information.

Returns:True if routing was reloaded successfully.
Return type:bool
Raises:arango.exceptions.ServerReloadRoutingError – If reload fails.
rename_view(name, new_name)

Rename a view.

Parameters:name (str | unicode) – View name.
Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewRenameError – If delete fails.
replace_document(document, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
replace_user(username, password, active=None, extra=None)

Replace a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserReplaceError – If replace fails.

replace_view(name, properties)

Replace a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

required_db_version()

Return required version of target database.

Returns:Required version of target database.
Return type:str | unicode
Raises:arango.exceptions.ServerRequiredDBVersionError – If retrieval fails.
reset_permission(username, database, collection=None)

Reset user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

True if permission was reset successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionRestError – If reset fails.

role()

Return server role in cluster.

Returns:Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY” or “UNDEFINED”.
Return type:str | unicode
Raises:arango.exceptions.ServerRoleError – If retrieval fails.
run_tests(tests)

Run available unittests on the server.

Parameters:tests ([str | unicode]) – List of files containing the test suites.
Returns:Test results.
Return type:dict
Raises:arango.exceptions.ServerRunTestsError – If execution fails.
set_log_levels(**kwargs)

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.

Returns:New logging levels.
Return type:dict
shutdown()

Initiate server shutdown sequence.

Returns:True if the server was shutdown successfully.
Return type:bool
Raises:arango.exceptions.ServerShutdownError – If shutdown fails.
statistics(description=False)

Return server statistics.

Returns:Server statistics.
Return type:dict
Raises:arango.exceptions.ServerStatisticsError – If retrieval fails.
status()

Return ArangoDB server status.

Returns:Server status.
Return type:dict
Raises:arango.exceptions.ServerStatusError – If retrieval fails.
task(task_id)

Return the details of an active server task.

Parameters:task_id (str | unicode) – Server task ID.
Returns:Server task details.
Return type:dict
Raises:arango.exceptions.TaskGetError – If retrieval fails.
tasks()

Return all currently active server tasks.

Returns:Currently active server tasks.
Return type:[dict]
Raises:arango.exceptions.TaskListError – If retrieval fails.
time()

Return server system time.

Returns:Server system time.
Return type:datetime.datetime
Raises:arango.exceptions.ServerTimeError – If retrieval fails.
update_document(document, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

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) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.
  • keep_none (bool) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update_permission(username, permission, database, collection=None)

Update user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
  • permission (str | unicode) – Allowed values are “rw” (read and write), “ro” (read only) or “none” (no access).
Returns:

True if access was granted successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionUpdateError – If update fails.

update_user(username, password=None, active=None, extra=None)

Update a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserUpdateError – If update fails.

update_view(name, properties)

Update a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

user(username)

Return user details.

Parameters:username (str | unicode) – Username.
Returns:User details.
Return type:dict
Raises:arango.exceptions.UserGetError – If retrieval fails.
username

Return the username.

Returns:Username.
Return type:str | unicode
users()

Return all user details.

Returns:List of user details.
Return type:[dict]
Raises:arango.exceptions.UserListError – If retrieval fails.
version()

Return ArangoDB server version.

Returns:Server version.
Return type:str | unicode
Raises:arango.exceptions.ServerVersionError – If retrieval fails.
view(name)

Return view details.

Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewGetError – If retrieval fails.
views()

Return list of views.

Returns:List of views.
Return type:[dict]
Raises:arango.exceptions.ViewListError – If retrieval fails.
wal

Return WAL (Write-Ahead Log) API wrapper.

Returns:WAL API wrapper.
Return type:arango.wal.WAL

AsyncJob

class arango.job.AsyncJob(connection, job_id, response_handler)

Job for tracking and retrieving result of an async execution.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • job_id (str | unicode) – Async job ID.
  • response_handler (callable) – HTTP response handler.
cancel(ignore_missing=False)

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=False)

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

Return the async job ID.

Returns:Async job ID.
Return type:str | unicode
result()

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.

Return type:

str | unicode | bool | int | list | dict

Raises:
status()

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 | unicode
Raises:arango.exceptions.AsyncJobStatusError – If retrieval fails.

AQL

class arango.aql.AQL(connection, executor)

AQL (ArangoDB Query Language) API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
cache

Return the query cache API wrapper.

Returns:Query cache API wrapper.
Return type:arango.aql.AQLQueryCache
clear_slow_queries()

Clear slow AQL queries.

Returns:True if slow queries were cleared successfully.
Return type:bool
Raises:arango.exceptions.AQLQueryClearError – If operation fails.
create_function(name, code)

Create a new AQL function.

Parameters:
  • name (str | unicode) – AQL function name.
  • code (str | unicode) – Function definition in Javascript.
Returns:

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

Return type:

dict

Raises:

arango.exceptions.AQLFunctionCreateError – If create fails.

delete_function(name, group=False, ignore_missing=False)

Delete an AQL function.

Parameters:
  • name (str | unicode) – 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.

execute(query, count=False, batch_size=None, ttl=None, bind_vars=None, full_count=None, max_plans=None, optimizer_rules=None, cache=None, memory_limit=0, fail_on_warning=None, profile=None, max_transaction_size=None, max_warning_count=None, intermediate_commit_count=None, intermediate_commit_size=None, satellite_sync_wait=None, read_collections=None, write_collections=None, stream=None, skip_inaccessible_cols=None)

Execute the query and return the result cursor.

Parameters:
  • query (str | unicode) – 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 teh 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 | unicode]) – 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. Applies only to RocksDB storage engine.
  • 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. Applies only to RocksDB storage engine.
  • intermediate_commit_size (int) – Max size of operations in bytes after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
  • 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.
  • read_collections ([str | unicode]) – Names of collections read during query execution. Required for transactions.
  • write_collections ([str | unicode]) – Names of collections written to during query execution. Required for transactions.
  • 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 (write-locks on MMFiles). 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.
Returns:

Result cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.AQLQueryExecuteError – If execute fails.

explain(query, all_plans=False, max_plans=None, opt_rules=None)

Inspect the query and return its metadata without executing it.

Parameters:
  • query (str | unicode) – 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.
Returns:

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

Return type:

dict | list

Raises:

arango.exceptions.AQLQueryExplainError – If explain fails.

functions()

List the AQL functions defined in the database.

Returns:AQL functions.
Return type:[dict]
Raises:arango.exceptions.AQLFunctionListError – If retrieval fails.
kill(query_id)

Kill a running query.

Parameters:query_id (str | unicode) – Query ID.
Returns:True if kill request was sent successfully.
Return type:bool
Raises:arango.exceptions.AQLQueryKillError – If the send fails.
queries()

Return the currently running AQL queries.

Returns:Running AQL queries.
Return type:[dict]
Raises:arango.exceptions.AQLQueryListError – If retrieval fails.
set_tracking(enabled=None, max_slow_queries=None, slow_query_threshold=None, max_query_string_length=None, track_bind_vars=None, track_slow_queries=None)

Configure AQL query tracking properties

Returns:Updated AQL query tracking properties.
Return type:dict
Raises:arango.exceptions.AQLQueryTrackingSetError – If operation fails.
slow_queries()

Return a list of all slow AQL queries.

Returns:Slow AQL queries.
Return type:[dict]
Raises:arango.exceptions.AQLQueryListError – If retrieval fails.
tracking()

Return AQL query tracking properties.

Returns:AQL query tracking properties.
Return type:dict
Raises:arango.exceptions.AQLQueryTrackingGetError – If retrieval fails.
validate(query)

Parse and validate the query without executing it.

Parameters:query (str | unicode) – Query to validate.
Returns:Query details.
Return type:dict
Raises:arango.exceptions.AQLQueryValidateError – If validation fails.

AQLQueryCache

class arango.aql.AQLQueryCache(connection, executor)

AQL Query Cache API wrapper.

clear()

Clear the query cache.

Returns:True if query cache was cleared successfully.
Return type:dict
Raises:arango.exceptions.AQLCacheClearError – If operation fails.
configure(mode=None, limit=None)

Configure the query cache properties.

Parameters:
  • mode (str | unicode) – Operation mode. Allowed values are “off”, “on” and “demand”.
  • limit (int) – Max number of query results to be stored.
Returns:

Query cache properties.

Return type:

dict

Raises:

arango.exceptions.AQLCacheConfigureError – If operation fails.

entries()

Return the query cache entries.

Returns:Query cache entries.
Return type:list
Raises:AQLCacheEntriesError – If retrieval fails.
properties()

Return the query cache properties.

Returns:Query cache properties.
Return type:dict
Raises:arango.exceptions.AQLCachePropertiesError – If retrieval fails.

BatchDatabase

class arango.database.BatchDatabase(connection, return_result)

Database API wrapper tailored specifically for batch execution.

See arango.database.StandardDatabase.begin_batch_execution().

Parameters:
  • connection (arango.connection.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.
aql

Return AQL (ArangoDB Query Language) API wrapper.

Returns:AQL API wrapper.
Return type:arango.aql.AQL
async_jobs(status, count=None)

Return IDs of async jobs with given status.

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

List of job IDs.

Return type:

[str | unicode]

Raises:

arango.exceptions.AsyncJobListError – If retrieval fails.

clear_async_jobs(threshold=None)

Clear async job results from the server.

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

Parameters:threshold (int) – 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.
collection(name)

Return the standard collection API wrapper.

Parameters:name (str | unicode) – Collection name.
Returns:Standard collection API wrapper.
Return type:arango.collection.StandardCollection
collections()

Return the collections in the database.

Returns:Collections in the database and their details.
Return type:[dict]
Raises:arango.exceptions.CollectionListError – If retrieval fails.
commit()

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

Return the API execution context.

Returns:API execution context. Possible values are “default”, “async”, “batch” and “transaction”.
Return type:str | unicode
create_collection(name, sync=False, compact=True, system=False, journal_size=None, edge=False, volatile=False, user_keys=True, key_increment=None, key_offset=None, key_generator=u'traditional', shard_fields=None, shard_count=None, index_bucket_count=None, replication_factor=None, shard_like=None, sync_replication=None, enforce_replication_factor=None)

Create a new collection.

Parameters:
  • name (str | unicode) – Collection name.
  • sync (bool) – If set to True, document operations via the collection will block until synchronized to disk by default.
  • compact (bool) – If set to True, the collection is compacted. Applies only to MMFiles storage engine.
  • system (bool) – If set to True, a system collection is created. The collection name must have leading underscore “_” character.
  • journal_size (int) – Max size of the journal in bytes.
  • edge (bool) – If set to True, an edge collection is created.
  • volatile (bool) – If set to True, collection data is kept in-memory only and not made persistent. Unloading the collection will cause the collection data to be discarded. Stopping or re-starting the server will also cause full loss of data.
  • key_generator (str | unicode) – 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 | unicode]) – Field(s) used to determine the target shard.
  • shard_count (int) – Number of shards to create.
  • index_bucket_count (int) – Number of buckets into which indexes using hash tables are split. The default is 16, and this number has to be a power of 2 and less than or equal to 1024. For large collections, one should increase this to avoid long pauses when the hash table has to be initially built or re-sized, since buckets are re-sized individually and can be initially built in parallel. For instance, 64 may be a sensible value for 100 million documents.
  • 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 | unicode) – 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.
Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

Raises:

arango.exceptions.CollectionCreateError – If create fails.

create_database(name, users=None)

Create a new database.

Parameters:
  • name (str | unicode) – 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.
Returns:

True if database was created successfully.

Return type:

bool

Raises:

arango.exceptions.DatabaseCreateError – If create fails.

Here is an example entry for parameter users:

{
    'username': 'john',
    'password': 'password',
    'active': True,
    'extra': {'Department': 'IT'}
}
create_graph(name, edge_definitions=None, orphan_collections=None, smart=None, smart_field=None, shard_count=None)

Create a new graph.

Parameters:
  • name (str | unicode) – Graph name.
  • edge_definitions ([dict]) – 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 | unicode]) – Names of additional vertex collections that are not in edge definitions.
  • smart (bool) – If set to True, sharding is enabled (see parameter smart_field below). Applies only to enterprise version of ArangoDB.
  • smart_field (str | unicode) – 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) – 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.
Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

Raises:

arango.exceptions.GraphCreateError – If create fails.

Here is an example entry for parameter edge_definitions:

{
    'edge_collection': 'teach',
    'from_vertex_collections': ['teachers'],
    'to_vertex_collections': ['lectures']
}
create_task(name, command, params=None, period=None, offset=None, task_id=None)

Create a new server task.

Parameters:
  • name (str | unicode) – Name of the server task.
  • command (str | unicode) – Javascript command to execute.
  • params (dict) – Optional parameters passed into the Javascript command.
  • period (int) – 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) – Initial delay before execution in seconds.
  • task_id (str | unicode) – Pre-defined ID for the new server task.
Returns:

Details of the new task.

Return type:

dict

Raises:

arango.exceptions.TaskCreateError – If create fails.

create_user(username, password, active=True, extra=None)

Create a new user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – Password.
  • active (bool) – True if user is active, False otherwise.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserCreateError – If create fails.

create_view(name, view_type, properties=None)

Create a view.

Parameters:
  • name (str | unicode) – View name.
  • view_type (str | unicode) – View type (e.g. “arangosearch”).
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

databases()

Return the names all databases.

Returns:Database names.
Return type:[str | unicode]
Raises:arango.exceptions.DatabaseListError – If retrieval fails.
db_name

Return the name of the current database.

Returns:Database name.
Return type:str | unicode
delete_collection(name, ignore_missing=False, system=None)

Delete the collection.

Parameters:
  • name (str | unicode) – 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, ignore_missing=False)

Delete the database.

Parameters:
  • name (str | unicode) – Database name.
  • ignore_missing (bool) – Do not raise an exception on missing database.
Returns:

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

Return type:

bool

Raises:

arango.exceptions.DatabaseDeleteError – If delete fails.

delete_document(document, rev=None, check_rev=True, ignore_missing=False, return_old=False, sync=None, silent=False)

Delete a document.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” field.
  • rev (str | unicode) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
delete_graph(name, ignore_missing=False, drop_collections=None)

Drop the graph of the given name from the database.

Parameters:
  • name (str | unicode) – Graph name.
  • ignore_missing (bool) – Do not raise an exception on missing graph.
  • drop_collections (bool) – 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, ignore_missing=False)

Delete a server task.

Parameters:
  • task_id (str | unicode) – 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, ignore_missing=False)

Delete a user.

Parameters:
  • username (str | unicode) – 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, ignore_missing=False)

Delete a view.

Parameters:name (str | unicode) – View name.
Returns:True if view was deleted successfully, False if view was not found and ignore_missing was set to True.
Return type:dict
Raises:arango.exceptions.ViewDeleteError – If delete fails.
details()

Return ArangoDB server details.

Returns:Server details.
Return type:dict
Raises:arango.exceptions.ServerDetailsError – If retrieval fails.
document(document, rev=None, check_rev=True)

Return a document.

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

Document, or None if not found.

Return type:

dict | None

Raises:
echo()

Return details of the last request (e.g. headers, payload).

Returns:Details of the last request.
Return type:dict
Raises:arango.exceptions.ServerEchoError – If retrieval fails.
endpoints()

Return coordinate endpoints. This method is for clusters only.

Returns:List of endpoints.
Return type:[str | unicode]
Raises:arango.exceptions.ServerEndpointsError – If retrieval fails.
engine()

Return the database engine details.

Returns:Database engine details.
Return type:str | unicode
Raises:arango.exceptions.ServerEngineError – If retrieval fails.
execute_transaction(command, params=None, read=None, write=None, sync=None, timeout=None, max_size=None, allow_implicit=None, intermediate_commit_count=None, intermediate_commit_size=None)

Execute raw Javascript command in transaction.

Parameters:
  • command (str | unicode) – Javascript command to execute.
  • read ([str | unicode]) – Names of collections read during transaction. If parameter allow_implicit is set to True, any undeclared read collections are loaded lazily.
  • write ([str | unicode]) – Names of collections written to during transaction. Transaction fails on undeclared write collections.
  • params (dict) – Optional parameters passed into the Javascript command.
  • sync (bool) – Block until operation is synchronized to disk.
  • timeout (int) – 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) – Max transaction size limit in bytes. Applies only to RocksDB storage engine.
  • allow_implicit (bool) – If set to True, undeclared read collections are loaded lazily. If set to False, transaction fails on any undeclared collections.
  • intermediate_commit_count (int) – Max number of operations after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
  • intermediate_commit_size (int) – Max size of operations in bytes after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
Returns:

Return value of command.

Return type:

str | unicode

Raises:

arango.exceptions.TransactionExecuteError – If execution fails.

foxx

Return Foxx API wrapper.

Returns:Foxx API wrapper.
Return type:arango.foxx.Foxx
graph(name)

Return the graph API wrapper.

Parameters:name (str | unicode) – Graph name.
Returns:Graph API wrapper.
Return type:arango.graph.Graph
graphs()

List all graphs in the database.

Returns:Graphs in the database.
Return type:[dict]
Raises:arango.exceptions.GraphListError – If retrieval fails.
has_collection(name)

Check if collection exists in the database.

Parameters:name (str | unicode) – Collection name.
Returns:True if collection exists, False otherwise.
Return type:bool
has_database(name)

Check if a database exists.

Parameters:name (str | unicode) – Database name.
Returns:True if database exists, False otherwise.
Return type:bool
has_document(document, rev=None, check_rev=True)

Check if a document exists.

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

True if document exists, False otherwise.

Return type:

bool

Raises:
has_graph(name)

Check if a graph exists in the database.

Parameters:name (str | unicode) – Graph name.
Returns:True if graph exists, False otherwise.
Return type:bool
has_user(username)

Check if user exists.

Parameters:username (str | unicode) – Username.
Returns:True if user exists, False otherwise.
Return type:bool
insert_document(collection, document, return_new=False, sync=None, silent=False, overwrite=False, return_old=False)

Insert a new document.

Parameters:
  • collection (str | unicode) – 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) – 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.
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.

log_levels()

Return current logging levels.

Returns:Current logging levels.
Return type:dict
name

Return database name.

Returns:Database name.
Return type:str | unicode
permission(username, database, collection=None)

Return user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

Permission for given database or collection.

Return type:

str | unicode

Raise:

arango.exceptions.PermissionGetError: If retrieval fails.

permissions(username)

Return user permissions for all databases and collections.

Parameters:username (str | unicode) – Username.
Returns:User permissions for all databases and collections.
Return type:dict
Raise:arango.exceptions.PermissionListError: If retrieval fails.
ping()

Ping the ArangoDB server by sending a test request.

Returns:Response code from server.
Return type:int
Raises:arango.exceptions.ServerConnectionError – If ping fails.
pregel

Return Pregel API wrapper.

Returns:Pregel API wrapper.
Return type:arango.pregel.Pregel
properties()

Return database properties.

Returns:Database properties.
Return type:dict
Raises:arango.exceptions.DatabasePropertiesError – If retrieval fails.
queued_jobs()

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
read_log(upto=None, level=None, start=None, size=None, offset=None, search=None, sort=None)

Read the global log from server.

Parameters:
  • upto (str | unicode | int) – 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 (str | unicode | int) – 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 | unicode) – Return only the log entries containing the given text.
  • sort (str | unicode) – 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.

reload_routing()

Reload the routing information.

Returns:True if routing was reloaded successfully.
Return type:bool
Raises:arango.exceptions.ServerReloadRoutingError – If reload fails.
rename_view(name, new_name)

Rename a view.

Parameters:name (str | unicode) – View name.
Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewRenameError – If delete fails.
replace_document(document, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
replace_user(username, password, active=None, extra=None)

Replace a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserReplaceError – If replace fails.

replace_view(name, properties)

Replace a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

required_db_version()

Return required version of target database.

Returns:Required version of target database.
Return type:str | unicode
Raises:arango.exceptions.ServerRequiredDBVersionError – If retrieval fails.
reset_permission(username, database, collection=None)

Reset user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

True if permission was reset successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionRestError – If reset fails.

role()

Return server role in cluster.

Returns:Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY” or “UNDEFINED”.
Return type:str | unicode
Raises:arango.exceptions.ServerRoleError – If retrieval fails.
run_tests(tests)

Run available unittests on the server.

Parameters:tests ([str | unicode]) – List of files containing the test suites.
Returns:Test results.
Return type:dict
Raises:arango.exceptions.ServerRunTestsError – If execution fails.
set_log_levels(**kwargs)

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.

Returns:New logging levels.
Return type:dict
shutdown()

Initiate server shutdown sequence.

Returns:True if the server was shutdown successfully.
Return type:bool
Raises:arango.exceptions.ServerShutdownError – If shutdown fails.
statistics(description=False)

Return server statistics.

Returns:Server statistics.
Return type:dict
Raises:arango.exceptions.ServerStatisticsError – If retrieval fails.
status()

Return ArangoDB server status.

Returns:Server status.
Return type:dict
Raises:arango.exceptions.ServerStatusError – If retrieval fails.
task(task_id)

Return the details of an active server task.

Parameters:task_id (str | unicode) – Server task ID.
Returns:Server task details.
Return type:dict
Raises:arango.exceptions.TaskGetError – If retrieval fails.
tasks()

Return all currently active server tasks.

Returns:Currently active server tasks.
Return type:[dict]
Raises:arango.exceptions.TaskListError – If retrieval fails.
time()

Return server system time.

Returns:Server system time.
Return type:datetime.datetime
Raises:arango.exceptions.ServerTimeError – If retrieval fails.
update_document(document, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

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) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.
  • keep_none (bool) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update_permission(username, permission, database, collection=None)

Update user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
  • permission (str | unicode) – Allowed values are “rw” (read and write), “ro” (read only) or “none” (no access).
Returns:

True if access was granted successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionUpdateError – If update fails.

update_user(username, password=None, active=None, extra=None)

Update a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserUpdateError – If update fails.

update_view(name, properties)

Update a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

user(username)

Return user details.

Parameters:username (str | unicode) – Username.
Returns:User details.
Return type:dict
Raises:arango.exceptions.UserGetError – If retrieval fails.
username

Return the username.

Returns:Username.
Return type:str | unicode
users()

Return all user details.

Returns:List of user details.
Return type:[dict]
Raises:arango.exceptions.UserListError – If retrieval fails.
version()

Return ArangoDB server version.

Returns:Server version.
Return type:str | unicode
Raises:arango.exceptions.ServerVersionError – If retrieval fails.
view(name)

Return view details.

Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewGetError – If retrieval fails.
views()

Return list of views.

Returns:List of views.
Return type:[dict]
Raises:arango.exceptions.ViewListError – If retrieval fails.
wal

Return WAL (Write-Ahead Log) API wrapper.

Returns:WAL API wrapper.
Return type:arango.wal.WAL

BatchJob

class arango.job.BatchJob(response_handler)

Job for tracking and retrieving result of batch execution.

Parameters:response_handler (callable) – HTTP response handler.
id

Return the batch job ID.

Returns:Batch job ID.
Return type:str | unicode
result()

Return the batch job result.

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

Returns:

Batch job result.

Return type:

str | unicode | bool | int | list | dict

Raises:
status()

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

Cursor

class arango.cursor.Cursor(connection, init_data, cursor_type=u'cursor')

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.

In transactions, the entire result set is loaded into the cursor. Therefore you must be mindful of client-side memory capacity when running queries that can potentially return a large result set.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • init_data (dict | list) – Cursor initialization data.
  • cursor_type (str | unicode) – Cursor type (“cursor” or “export”).
batch()

Return the current batch of results.

Returns:Current batch.
Return type:collections.deque
cached()

Return True if results are cached.

Returns:True if results are cached.
Return type:bool
close(ignore_missing=False)

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, or in transactions).

Return type:

bool | None

Raises:
count()

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
empty()

Check if the current batch is empty.

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

Fetch the next batch from server and update the cursor.

Returns:

New batch details.

Return type:

dict

Raises:
has_more()

Return True if more results are available on the server.

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

Return the cursor ID.

Returns:Cursor ID.
Return type:str | unicode
next()

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.

Return type:

str | unicode | bool | int | list | dict

Raises:
pop()

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.
Return type:str | unicode | bool | int | list | dict
Raises:arango.exceptions.CursorEmptyError – If current batch is empty.
profile()

Return cursor performance profile.

Returns:Cursor performance profile.
Return type:dict
statistics()

Return cursor statistics.

Returns:Cursor statistics.
Return type:dict
type

Return the cursor type.

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

Return any warnings from the query execution.

Returns:Warnings, or None if there are none.
Return type:list

DefaultHTTPClient

class arango.http.DefaultHTTPClient

Default HTTP client implementation.

send_request(method, url, params=None, data=None, headers=None, auth=None)

Send an HTTP request.

Parameters:
  • method (str | unicode) – HTTP method in lowercase (e.g. “post”).
  • url (str | unicode) – Request URL.
  • headers (dict) – Request headers.
  • params (dict) – URL (query) parameters.
  • data (str | unicode | bool | int | list | dict) – Request payload.
  • auth (tuple) – Username and password.
Returns:

HTTP response.

Return type:

arango.response.Response

StandardCollection

class arango.collection.StandardCollection(connection, executor, name)

Standard ArangoDB collection API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
  • name (str | unicode) – Collection name.
add_fulltext_index(fields, min_length=None)

Create a new fulltext index.

Parameters:
  • fields ([str | unicode]) – Document fields to index.
  • min_length (int) – Minimum number of characters to index.
Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

add_geo_index(fields, ordered=None)

Create a new geo-spatial index.

Parameters:
  • fields (str | unicode | list) – 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.
  • ordered (bool) – Whether the order is longitude, then latitude.
Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

add_hash_index(fields, unique=None, sparse=None, deduplicate=None)

Create a new hash index.

Parameters:
  • fields ([str | unicode]) – Document fields to index.
  • unique (bool) – Whether the index is unique.
  • sparse (bool) – If set to True, documents with None in the field are also indexed. If set to False, they are skipped.
  • deduplicate (bool) – If set to True, inserting duplicate index values from the same document triggers unique constraint errors.
Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

add_persistent_index(fields, unique=None, sparse=None)

Create a new persistent index.

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

Parameters:
  • fields ([str | unicode]) – Document fields to index.
  • unique (bool) – Whether the index is unique.
  • sparse (bool) – 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.
Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

add_skiplist_index(fields, unique=None, sparse=None, deduplicate=None)

Create a new skiplist index.

Parameters:
  • fields ([str | unicode]) – Document fields to index.
  • unique (bool) – Whether the index is unique.
  • sparse (bool) – If set to True, documents with None in the field are also indexed. If set to False, they are skipped.
  • deduplicate (bool) – If set to True, inserting duplicate index values from the same document triggers unique constraint errors.
Returns:

New index details.

Return type:

dict

Raises:

arango.exceptions.IndexCreateError – If create fails.

all(skip=None, limit=None)

Return all documents in the collection.

Parameters:
  • skip (int) – Number of documents to skip.
  • limit (int) – Max number of documents returned.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

checksum(with_rev=False, with_data=False)

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

Raises:

arango.exceptions.CollectionChecksumError – If retrieval fails.

configure(sync=None, journal_size=None)

Configure collection properties.

Parameters:
  • sync (bool) – Block until operations are synchronized to disk.
  • journal_size (int) – Journal size in bytes.
Returns:

New collection properties.

Return type:

dict

Raises:

arango.exceptions.CollectionConfigureError – If operation fails.

context

Return the API execution context.

Returns:API execution context. Possible values are “default”, “async”, “batch” and “transaction”.
Return type:str | unicode
count()

Return the total document count.

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

Return the name of the current database.

Returns:Database name.
Return type:str | unicode
delete(document, rev=None, check_rev=True, ignore_missing=False, return_old=False, sync=None, silent=False)

Delete a document.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
delete_index(index_id, ignore_missing=False)

Delete an index.

Parameters:
  • index_id (str | unicode) – 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_many(documents, return_old=False, check_rev=True, sync=None, silent=False)

Delete multiple documents.

If deleting a document fails, the exception object is placed in the result list instead of document metadata.

Parameters:
  • documents ([str | unicode | 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) – 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:

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.DocumentDeleteError – If delete fails.

delete_match(filters, limit=None, sync=None)

Delete matching documents.

Parameters:
  • filters (dict) – Document filters.
  • limit (int) – Max number of documents to delete. If the limit is lower than the number of matched documents, random documents are chosen.
  • sync (bool) – Block until operation is synchronized to disk.
Returns:

Number of documents deleted.

Return type:

dict

Raises:

arango.exceptions.DocumentDeleteError – If delete fails.

export(limit=None, count=False, batch_size=None, flush=False, flush_wait=None, ttl=None, filter_fields=None, filter_type=u'include')

Export all documents in the collection using a server cursor.

Parameters:
  • flush (bool) – If set to True, flush the write-ahead log prior to the export. If set to False, documents in the write-ahead log during the export are not included in the result.
  • flush_wait (int) – Max wait time in seconds for write-ahead log flush.
  • count (bool) – Include the document count in the server cursor.
  • batch_size (int) – Max number of documents in the batch fetched by the cursor in one round trip.
  • limit (int) – Max number of documents fetched by the cursor.
  • ttl (int) – Time-to-live for the cursor on the server.
  • filter_fields ([str | unicode]) – Document fields to filter with.
  • filter_type (str | unicode) – Allowed values are “include” or “exclude”.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If export fails.

find(filters, skip=None, limit=None)

Return all documents that match the given filters.

Parameters:
  • filters (dict) – Document filters.
  • skip (int) – Number of documents to skip.
  • limit (int) – Max number of documents returned.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_by_text(field, query, limit=None)

Return documents that match the given fulltext query.

Parameters:
  • field (str | unicode) – Document field with fulltext index.
  • query (str | unicode) – Fulltext query.
  • limit (int) – Max number of documents returned.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_in_box(latitude1, longitude1, latitude2, longitude2, skip=None, limit=None, index=None)

Return all documents in an 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) – Number of documents to skip.
  • limit (int) – Max number of documents returned.
  • index (str | unicode) – ID of the geo index to use (without the collection prefix). This parameter is ignored in transactions.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_in_radius(latitude, longitude, radius, distance_field=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 | unicode) – Document field used to indicate the distance to the given coordinate. This parameter is ignored in transactions.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_in_range(field, lower, upper, skip=None, limit=None)

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 | unicode) – Document field name.
  • lower (int) – Lower bound (inclusive).
  • upper (int) – Upper bound (exclusive).
  • skip (int) – Number of documents to skip.
  • limit (int) – Max number of documents returned.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

find_near(latitude, longitude, limit=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) – Max number of documents returned.
Returns:

Document cursor.

Return type:

arango.cursor.Cursor

Raises:

arango.exceptions.DocumentGetError – If retrieval fails.

get(document, rev=None, check_rev=True)

Return a document.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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:
get_many(documents)

Return multiple documents ignoring any missing ones.

Parameters:documents ([str | unicode | dict]) – List of document keys, IDs or bodies. Document bodies must contain the “_id” or “_key” fields.
Returns:Documents. Missing ones are not included.
Return type:[dict]
Raises:arango.exceptions.DocumentGetError – If retrieval fails.
has(document, rev=None, check_rev=True)

Check if a document exists in the collection.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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:
ids()

Return the IDs of all documents in the collection.

Returns:Document ID cursor.
Return type:arango.cursor.Cursor
Raises:arango.exceptions.DocumentIDsError – If retrieval fails.
import_bulk(documents, halt_on_error=True, details=True, from_prefix=None, to_prefix=None, overwrite=None, on_duplicate=None, sync=None)

Insert multiple documents into the collection.

This is faster than arango.collection.Collection.insert_many() but does not return as much information.

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 | unicode) – 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 | unicode) – 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 | unicode) – 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) – Block until operation is synchronized to disk.
Returns:

Result of the bulk import.

Return type:

dict

Raises:

arango.exceptions.DocumentInsertError – If import fails.

indexes()

Return the collection indexes.

Returns:Collection indexes.
Return type:[dict]
Raises:arango.exceptions.IndexListError – If retrieval fails.
insert(document, return_new=False, sync=None, silent=False, overwrite=False, return_old=False)

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

insert_many(documents, return_new=False, sync=None, silent=False, overwrite=False, return_old=False)

Insert multiple documents.

If inserting a document fails, the exception object is placed in the result list instead of document metadata.

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) – 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.
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 | ArangoError] | bool

Raises:

arango.exceptions.DocumentInsertError – If insert fails.

keys()

Return the keys of all documents in the collection.

Returns:Document key cursor.
Return type:arango.cursor.Cursor
Raises:arango.exceptions.DocumentKeysError – If retrieval fails.
load()

Load the collection into memory.

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

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

Return collection name.

Returns:Collection name.
Return type:str | unicode
properties()

Return collection properties.

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

Return a random document from the collection.

Returns:A random document.
Return type:dict
Raises:arango.exceptions.DocumentGetError – If retrieval fails.
rename(new_name)

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 | unicode) – New collection name.
Returns:True if collection was renamed successfully.
Return type:bool
Raises:arango.exceptions.CollectionRenameError – If rename fails.
replace(document, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

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 result.
  • return_old (bool) – Include body of the old document in the result.
  • sync (bool) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
replace_many(documents, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

Replace multiple documents.

If replacing a document fails, the exception object is placed in the result list instead of document metadata.

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 bodies of the new documents in the result.
  • return_old (bool) – Include bodies of the old documents in the result.
  • sync (bool) – 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:

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.DocumentReplaceError – If replace fails.

replace_match(filters, body, limit=None, sync=None)

Replace matching documents.

Parameters:
  • filters (dict) – Document filters.
  • body (dict) – New document body.
  • limit (int) – Max number of documents to replace. If the limit is lower than the number of matched documents, random documents are chosen.
  • sync (bool) – Block until operation is synchronized to disk.
Returns:

Number of documents replaced.

Return type:

int

Raises:

arango.exceptions.DocumentReplaceError – If replace fails.

revision()

Return collection revision.

Returns:Collection revision.
Return type:str | unicode
Raises:arango.exceptions.CollectionRevisionError – If retrieval fails.
rotate()

Rotate the collection journal.

Returns:True if collection journal was rotated successfully.
Return type:bool
Raises:arango.exceptions.CollectionRotateJournalError – If rotate fails.
statistics()

Return collection statistics.

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

Delete all documents in the collection.

Returns:True if collection was truncated successfully.
Return type:dict
Raises:arango.exceptions.CollectionTruncateError – If operation fails.
unload()

Unload the collection from memory.

Returns:True if collection was unloaded successfully.
Return type:bool
Raises:arango.exceptions.CollectionUnloadError – If operation fails.
update(document, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

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) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.
  • keep_none (bool) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update_many(documents, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

Update multiple documents.

If updating a document fails, the exception object is placed in the result list instead of document metadata.

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) – If set to True, sub-dictionaries are merged instead of the new ones overwriting the old ones.
  • keep_none (bool) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.
  • return_new (bool) – Include bodies of the new documents in the result.
  • return_old (bool) – Include bodies of the old documents in the result.
  • sync (bool) – 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:

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_match(filters, body, limit=None, keep_none=True, sync=None, merge=True)

Update matching documents.

Parameters:
  • filters (dict) – Document filters.
  • body (dict) – Full or partial document body with the updates.
  • limit (int) – 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) – If set to True, fields with value None are retained in the document. Otherwise, they are removed completely.
  • sync (bool) – Block until operation is synchronized to disk.
  • merge (bool) – If set to True, sub-dictionaries are merged instead of the new ones overwriting the old ones.
Returns:

Number of documents updated.

Return type:

int

Raises:

arango.exceptions.DocumentUpdateError – If update fails.

username

Return the username.

Returns:Username.
Return type:str | unicode

StandardDatabase

class arango.database.StandardDatabase(connection)

Standard database API wrapper.

Parameters:connection (arango.connection.Connection) – HTTP connection.
aql

Return AQL (ArangoDB Query Language) API wrapper.

Returns:AQL API wrapper.
Return type:arango.aql.AQL
async_jobs(status, count=None)

Return IDs of async jobs with given status.

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

List of job IDs.

Return type:

[str | unicode]

Raises:

arango.exceptions.AsyncJobListError – If retrieval fails.

begin_async_execution(return_result=True)

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 built specifically for async execution.
Return type:arango.database.AsyncDatabase
begin_batch_execution(return_result=True)

Begin batch execution.

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.
Returns:Database API wrapper built specifically for batch execution.
Return type:arango.database.BatchDatabase
begin_transaction(return_result=True, timeout=None, sync=None, read=None, write=None)

Begin transaction.

Parameters:
  • return_result (bool) – If set to True, API executions return instances of arango.job.TransactionJob that are populated with results on commit. If set to False, API executions return None and no results are tracked client-side.
  • read ([str | unicode]) – Names of collections read during transaction. If not specified, they are added automatically as jobs are queued.
  • write ([str | unicode]) – Names of collections written to during transaction. If not specified, they are added automatically as jobs are queued.
  • timeout (int) – Timeout for waiting on collection locks. If set to 0, ArangoDB server waits indefinitely. If not set, system default value is used.
  • sync (bool) – Block until the transaction is synchronized to disk.
Returns:

Database API wrapper built specifically for transactions.

Return type:

arango.database.TransactionDatabase

clear_async_jobs(threshold=None)

Clear async job results from the server.

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

Parameters:threshold (int) – 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.
collection(name)

Return the standard collection API wrapper.

Parameters:name (str | unicode) – Collection name.
Returns:Standard collection API wrapper.
Return type:arango.collection.StandardCollection
collections()

Return the collections in the database.

Returns:Collections in the database and their details.
Return type:[dict]
Raises:arango.exceptions.CollectionListError – If retrieval fails.
context

Return the API execution context.

Returns:API execution context. Possible values are “default”, “async”, “batch” and “transaction”.
Return type:str | unicode
create_collection(name, sync=False, compact=True, system=False, journal_size=None, edge=False, volatile=False, user_keys=True, key_increment=None, key_offset=None, key_generator=u'traditional', shard_fields=None, shard_count=None, index_bucket_count=None, replication_factor=None, shard_like=None, sync_replication=None, enforce_replication_factor=None)

Create a new collection.

Parameters:
  • name (str | unicode) – Collection name.
  • sync (bool) – If set to True, document operations via the collection will block until synchronized to disk by default.
  • compact (bool) – If set to True, the collection is compacted. Applies only to MMFiles storage engine.
  • system (bool) – If set to True, a system collection is created. The collection name must have leading underscore “_” character.
  • journal_size (int) – Max size of the journal in bytes.
  • edge (bool) – If set to True, an edge collection is created.
  • volatile (bool) – If set to True, collection data is kept in-memory only and not made persistent. Unloading the collection will cause the collection data to be discarded. Stopping or re-starting the server will also cause full loss of data.
  • key_generator (str | unicode) – 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 | unicode]) – Field(s) used to determine the target shard.
  • shard_count (int) – Number of shards to create.
  • index_bucket_count (int) – Number of buckets into which indexes using hash tables are split. The default is 16, and this number has to be a power of 2 and less than or equal to 1024. For large collections, one should increase this to avoid long pauses when the hash table has to be initially built or re-sized, since buckets are re-sized individually and can be initially built in parallel. For instance, 64 may be a sensible value for 100 million documents.
  • 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 | unicode) – 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.
Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

Raises:

arango.exceptions.CollectionCreateError – If create fails.

create_database(name, users=None)

Create a new database.

Parameters:
  • name (str | unicode) – 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.
Returns:

True if database was created successfully.

Return type:

bool

Raises:

arango.exceptions.DatabaseCreateError – If create fails.

Here is an example entry for parameter users:

{
    'username': 'john',
    'password': 'password',
    'active': True,
    'extra': {'Department': 'IT'}
}
create_graph(name, edge_definitions=None, orphan_collections=None, smart=None, smart_field=None, shard_count=None)

Create a new graph.

Parameters:
  • name (str | unicode) – Graph name.
  • edge_definitions ([dict]) – 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 | unicode]) – Names of additional vertex collections that are not in edge definitions.
  • smart (bool) – If set to True, sharding is enabled (see parameter smart_field below). Applies only to enterprise version of ArangoDB.
  • smart_field (str | unicode) – 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) – 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.
Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

Raises:

arango.exceptions.GraphCreateError – If create fails.

Here is an example entry for parameter edge_definitions:

{
    'edge_collection': 'teach',
    'from_vertex_collections': ['teachers'],
    'to_vertex_collections': ['lectures']
}
create_task(name, command, params=None, period=None, offset=None, task_id=None)

Create a new server task.

Parameters:
  • name (str | unicode) – Name of the server task.
  • command (str | unicode) – Javascript command to execute.
  • params (dict) – Optional parameters passed into the Javascript command.
  • period (int) – 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) – Initial delay before execution in seconds.
  • task_id (str | unicode) – Pre-defined ID for the new server task.
Returns:

Details of the new task.

Return type:

dict

Raises:

arango.exceptions.TaskCreateError – If create fails.

create_user(username, password, active=True, extra=None)

Create a new user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – Password.
  • active (bool) – True if user is active, False otherwise.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserCreateError – If create fails.

create_view(name, view_type, properties=None)

Create a view.

Parameters:
  • name (str | unicode) – View name.
  • view_type (str | unicode) – View type (e.g. “arangosearch”).
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

databases()

Return the names all databases.

Returns:Database names.
Return type:[str | unicode]
Raises:arango.exceptions.DatabaseListError – If retrieval fails.
db_name

Return the name of the current database.

Returns:Database name.
Return type:str | unicode
delete_collection(name, ignore_missing=False, system=None)

Delete the collection.

Parameters:
  • name (str | unicode) – 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, ignore_missing=False)

Delete the database.

Parameters:
  • name (str | unicode) – Database name.
  • ignore_missing (bool) – Do not raise an exception on missing database.
Returns:

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

Return type:

bool

Raises:

arango.exceptions.DatabaseDeleteError – If delete fails.

delete_document(document, rev=None, check_rev=True, ignore_missing=False, return_old=False, sync=None, silent=False)

Delete a document.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” field.
  • rev (str | unicode) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
delete_graph(name, ignore_missing=False, drop_collections=None)

Drop the graph of the given name from the database.

Parameters:
  • name (str | unicode) – Graph name.
  • ignore_missing (bool) – Do not raise an exception on missing graph.
  • drop_collections (bool) – 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, ignore_missing=False)

Delete a server task.

Parameters:
  • task_id (str | unicode) – 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, ignore_missing=False)

Delete a user.

Parameters:
  • username (str | unicode) – 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, ignore_missing=False)

Delete a view.

Parameters:name (str | unicode) – View name.
Returns:True if view was deleted successfully, False if view was not found and ignore_missing was set to True.
Return type:dict
Raises:arango.exceptions.ViewDeleteError – If delete fails.
details()

Return ArangoDB server details.

Returns:Server details.
Return type:dict
Raises:arango.exceptions.ServerDetailsError – If retrieval fails.
document(document, rev=None, check_rev=True)

Return a document.

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

Document, or None if not found.

Return type:

dict | None

Raises:
echo()

Return details of the last request (e.g. headers, payload).

Returns:Details of the last request.
Return type:dict
Raises:arango.exceptions.ServerEchoError – If retrieval fails.
endpoints()

Return coordinate endpoints. This method is for clusters only.

Returns:List of endpoints.
Return type:[str | unicode]
Raises:arango.exceptions.ServerEndpointsError – If retrieval fails.
engine()

Return the database engine details.

Returns:Database engine details.
Return type:str | unicode
Raises:arango.exceptions.ServerEngineError – If retrieval fails.
execute_transaction(command, params=None, read=None, write=None, sync=None, timeout=None, max_size=None, allow_implicit=None, intermediate_commit_count=None, intermediate_commit_size=None)

Execute raw Javascript command in transaction.

Parameters:
  • command (str | unicode) – Javascript command to execute.
  • read ([str | unicode]) – Names of collections read during transaction. If parameter allow_implicit is set to True, any undeclared read collections are loaded lazily.
  • write ([str | unicode]) – Names of collections written to during transaction. Transaction fails on undeclared write collections.
  • params (dict) – Optional parameters passed into the Javascript command.
  • sync (bool) – Block until operation is synchronized to disk.
  • timeout (int) – 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) – Max transaction size limit in bytes. Applies only to RocksDB storage engine.
  • allow_implicit (bool) – If set to True, undeclared read collections are loaded lazily. If set to False, transaction fails on any undeclared collections.
  • intermediate_commit_count (int) – Max number of operations after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
  • intermediate_commit_size (int) – Max size of operations in bytes after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
Returns:

Return value of command.

Return type:

str | unicode

Raises:

arango.exceptions.TransactionExecuteError – If execution fails.

foxx

Return Foxx API wrapper.

Returns:Foxx API wrapper.
Return type:arango.foxx.Foxx
graph(name)

Return the graph API wrapper.

Parameters:name (str | unicode) – Graph name.
Returns:Graph API wrapper.
Return type:arango.graph.Graph
graphs()

List all graphs in the database.

Returns:Graphs in the database.
Return type:[dict]
Raises:arango.exceptions.GraphListError – If retrieval fails.
has_collection(name)

Check if collection exists in the database.

Parameters:name (str | unicode) – Collection name.
Returns:True if collection exists, False otherwise.
Return type:bool
has_database(name)

Check if a database exists.

Parameters:name (str | unicode) – Database name.
Returns:True if database exists, False otherwise.
Return type:bool
has_document(document, rev=None, check_rev=True)

Check if a document exists.

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

True if document exists, False otherwise.

Return type:

bool

Raises:
has_graph(name)

Check if a graph exists in the database.

Parameters:name (str | unicode) – Graph name.
Returns:True if graph exists, False otherwise.
Return type:bool
has_user(username)

Check if user exists.

Parameters:username (str | unicode) – Username.
Returns:True if user exists, False otherwise.
Return type:bool
insert_document(collection, document, return_new=False, sync=None, silent=False, overwrite=False, return_old=False)

Insert a new document.

Parameters:
  • collection (str | unicode) – 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) – 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.
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.

log_levels()

Return current logging levels.

Returns:Current logging levels.
Return type:dict
name

Return database name.

Returns:Database name.
Return type:str | unicode
permission(username, database, collection=None)

Return user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

Permission for given database or collection.

Return type:

str | unicode

Raise:

arango.exceptions.PermissionGetError: If retrieval fails.

permissions(username)

Return user permissions for all databases and collections.

Parameters:username (str | unicode) – Username.
Returns:User permissions for all databases and collections.
Return type:dict
Raise:arango.exceptions.PermissionListError: If retrieval fails.
ping()

Ping the ArangoDB server by sending a test request.

Returns:Response code from server.
Return type:int
Raises:arango.exceptions.ServerConnectionError – If ping fails.
pregel

Return Pregel API wrapper.

Returns:Pregel API wrapper.
Return type:arango.pregel.Pregel
properties()

Return database properties.

Returns:Database properties.
Return type:dict
Raises:arango.exceptions.DatabasePropertiesError – If retrieval fails.
read_log(upto=None, level=None, start=None, size=None, offset=None, search=None, sort=None)

Read the global log from server.

Parameters:
  • upto (str | unicode | int) – 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 (str | unicode | int) – 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 | unicode) – Return only the log entries containing the given text.
  • sort (str | unicode) – 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.

reload_routing()

Reload the routing information.

Returns:True if routing was reloaded successfully.
Return type:bool
Raises:arango.exceptions.ServerReloadRoutingError – If reload fails.
rename_view(name, new_name)

Rename a view.

Parameters:name (str | unicode) – View name.
Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewRenameError – If delete fails.
replace_document(document, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
replace_user(username, password, active=None, extra=None)

Replace a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserReplaceError – If replace fails.

replace_view(name, properties)

Replace a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

required_db_version()

Return required version of target database.

Returns:Required version of target database.
Return type:str | unicode
Raises:arango.exceptions.ServerRequiredDBVersionError – If retrieval fails.
reset_permission(username, database, collection=None)

Reset user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

True if permission was reset successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionRestError – If reset fails.

role()

Return server role in cluster.

Returns:Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY” or “UNDEFINED”.
Return type:str | unicode
Raises:arango.exceptions.ServerRoleError – If retrieval fails.
run_tests(tests)

Run available unittests on the server.

Parameters:tests ([str | unicode]) – List of files containing the test suites.
Returns:Test results.
Return type:dict
Raises:arango.exceptions.ServerRunTestsError – If execution fails.
set_log_levels(**kwargs)

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.

Returns:New logging levels.
Return type:dict
shutdown()

Initiate server shutdown sequence.

Returns:True if the server was shutdown successfully.
Return type:bool
Raises:arango.exceptions.ServerShutdownError – If shutdown fails.
statistics(description=False)

Return server statistics.

Returns:Server statistics.
Return type:dict
Raises:arango.exceptions.ServerStatisticsError – If retrieval fails.
status()

Return ArangoDB server status.

Returns:Server status.
Return type:dict
Raises:arango.exceptions.ServerStatusError – If retrieval fails.
task(task_id)

Return the details of an active server task.

Parameters:task_id (str | unicode) – Server task ID.
Returns:Server task details.
Return type:dict
Raises:arango.exceptions.TaskGetError – If retrieval fails.
tasks()

Return all currently active server tasks.

Returns:Currently active server tasks.
Return type:[dict]
Raises:arango.exceptions.TaskListError – If retrieval fails.
time()

Return server system time.

Returns:Server system time.
Return type:datetime.datetime
Raises:arango.exceptions.ServerTimeError – If retrieval fails.
update_document(document, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

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) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.
  • keep_none (bool) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update_permission(username, permission, database, collection=None)

Update user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
  • permission (str | unicode) – Allowed values are “rw” (read and write), “ro” (read only) or “none” (no access).
Returns:

True if access was granted successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionUpdateError – If update fails.

update_user(username, password=None, active=None, extra=None)

Update a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserUpdateError – If update fails.

update_view(name, properties)

Update a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

user(username)

Return user details.

Parameters:username (str | unicode) – Username.
Returns:User details.
Return type:dict
Raises:arango.exceptions.UserGetError – If retrieval fails.
username

Return the username.

Returns:Username.
Return type:str | unicode
users()

Return all user details.

Returns:List of user details.
Return type:[dict]
Raises:arango.exceptions.UserListError – If retrieval fails.
version()

Return ArangoDB server version.

Returns:Server version.
Return type:str | unicode
Raises:arango.exceptions.ServerVersionError – If retrieval fails.
view(name)

Return view details.

Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewGetError – If retrieval fails.
views()

Return list of views.

Returns:List of views.
Return type:[dict]
Raises:arango.exceptions.ViewListError – If retrieval fails.
wal

Return WAL (Write-Ahead Log) API wrapper.

Returns:WAL API wrapper.
Return type:arango.wal.WAL

EdgeCollection

class arango.collection.EdgeCollection(connection, executor, graph, name)

ArangoDB edge collection API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
  • graph (str | unicode) – Graph name.
  • name (str | unicode) – Edge collection name.
delete(edge, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete an edge document.

Parameters:
  • edge (str | unicode | dict) – Edge document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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) – 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:
edges(vertex, direction=None)

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

Parameters:
  • vertex (str | unicode | dict) – Vertex document ID or body with “_id” field.
  • direction (str | unicode) – 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.

get(edge, rev=None, check_rev=True)

Return an edge document.

Parameters:
  • edge (str | unicode | dict) – Edge document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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:
graph

Return the graph name.

Returns:Graph name.
Return type:str | unicode
insert(edge, sync=None, silent=False)

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

Insert a new edge document linking the given vertices.

Parameters:
  • from_vertex (str | unicode | dict) – “From” vertex document ID or body with “_id” field.
  • to_vertex (str | unicode | 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) – 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.

replace(edge, check_rev=True, sync=None, silent=False)

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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update(edge, check_rev=True, keep_none=True, sync=None, silent=False)

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) – If set to True, fields with value None are retained in the document. If set to False, they are removed completely.
  • sync (bool) – 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:

Foxx

class arango.foxx.Foxx(connection, executor)

Foxx API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
commit(replace=None)

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) – 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.
config(mount)

Return service configuration.

Parameters:mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
Returns:Configuration values.
Return type:dict
Raises:arango.exceptions.FoxxConfigGetError – If retrieval fails.
create_service(mount, source, config=None, dependencies=None, development=None, setup=None, legacy=None)

Install a new service.

Parameters:
  • mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
  • source (str | unicode) – 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) – Configuration values.
  • dependencies (dict) – Dependency settings.
  • development (bool) – Enable development mode.
  • setup (bool) – Run service setup script.
  • legacy (bool) – Install the service in 2.8 legacy compatibility mode.
Returns:

Service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceCreateError – If install fails.

delete_service(mount, teardown=None)

Uninstall a service.

Parameters:
  • mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
  • teardown (bool) – Run service teardown script.
Returns:

True if service was deleted successfully.

Return type:

bool

Raises:

arango.exceptions.FoxxServiceDeleteError – If delete fails.

dependencies(mount)

Return service dependencies.

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

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 | unicode) – Service mount path (e.g “/_admin/aardvark”).
Returns:Service metadata.
Return type:dict
Raises:arango.exceptions.FoxxDevModeDisableError – If operation fails.
download(mount)

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 | unicode) – Service mount path (e.g “/_admin/aardvark”).
Returns:Service bundle in raw string form.
Return type:str | unicode
Raises:arango.exceptions.FoxxDownloadError – If download fails.
enable_development(mount)

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 | unicode) – Service mount path (e.g “/_admin/aardvark”).
Returns:Service metadata.
Return type:dict
Raises:arango.exceptions.FoxxDevModeEnableError – If operation fails.
readme(mount)

Return the service readme.

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

Replace service configuration.

Parameters:
  • mount (str | unicode) – 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.

replace_dependencies(mount, dependencies)

Replace service dependencies.

Parameters:
  • mount (str | unicode) – 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.

replace_service(mount, source, config=None, dependencies=None, teardown=None, setup=None, legacy=None, force=None)

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

Parameters:
  • mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
  • source (str | unicode) – 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) – Configuration values.
  • dependencies (dict) – Dependency settings.
  • teardown (bool) – Run service teardown script.
  • setup (bool) – Run service setup script.
  • legacy (bool) – Install the service in 2.8 legacy compatibility mode.
  • force (bool) – Force install if no service is found.
Returns:

Replaced service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceReplaceError – If replace fails.

run_script(mount, name, arg=None)

Run a service script.

Parameters:
  • mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
  • name (str | unicode) – Script name.
  • arg (str | unicode | bool | int | list | dict) – Arbitrary value passed into the script as first argument.
Returns:

Result of the script, if any.

Return type:

dict

Raises:

arango.exceptions.FoxxScriptRunError – If script fails.

run_tests(mount, reporter=u'default', idiomatic=None, output_format=None)

Run service tests.

Parameters:
  • mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
  • reporter (str | unicode) – 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 | unicode) – 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.
Type:

bool

Returns:

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

Return type:

str | unicode

Raises:

arango.exceptions.FoxxTestRunError – If test fails.

scripts(mount)

List service scripts.

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

Return service metadata.

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

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.
swagger(mount)

Return the Swagger API description for the given service.

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

Update service configuration.

Parameters:
  • mount (str | unicode) – 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.

update_dependencies(mount, dependencies)

Update service dependencies.

Parameters:
  • mount (str | unicode) – 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.

update_service(mount, source=None, config=None, dependencies=None, teardown=None, setup=None, legacy=None)

Update (upgrade) a service.

Parameters:
  • mount (str | unicode) – Service mount path (e.g “/_admin/aardvark”).
  • source (str | unicode) – 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) – Configuration values.
  • dependencies (dict) – Dependency settings.
  • teardown (bool) – Run service teardown script.
  • setup (bool) – Run service setup script.
  • legacy (bool) – Install the service in 2.8 legacy compatibility mode.
Returns:

Updated service metadata.

Return type:

dict

Raises:

arango.exceptions.FoxxServiceUpdateError – If update fails.

Graph

class arango.graph.Graph(connection, executor, name)

Graph API wrapper.

Parameters:
  • executor (arango.executor.Executor) – API executor.
  • name (str | unicode) – Graph name.
create_edge_definition(edge_collection, from_vertex_collections, to_vertex_collections)

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 | unicode) – Edge collection name.
  • from_vertex_collections ([str | unicode]) – Names of “from” vertex collections.
  • to_vertex_collections ([str | unicode]) – Names of “to” vertex collections.
Returns:

Edge collection API wrapper.

Return type:

arango.collection.EdgeCollection

Raises:

arango.exceptions.EdgeDefinitionCreateError – If create fails.

create_vertex_collection(name)

Create a vertex collection in the graph.

Parameters:name (str | unicode) – Vertex collection name.
Returns:Vertex collection API wrapper.
Return type:arango.collection.VertexCollection
Raises:arango.exceptions.VertexCollectionCreateError – If create fails.
delete_edge(edge, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete an edge document.

Parameters:
  • edge (str | unicode | dict) – Edge document ID or body with “_id” field.
  • rev (str | unicode) – 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) – 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:
delete_edge_definition(name, purge=False)

Delete an edge definition from the graph.

Parameters:
  • name (str | unicode) – 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.

delete_vertex(vertex, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete a vertex document.

Parameters:
  • vertex (str | unicode | dict) – Vertex document ID or body with “_id” field.
  • rev (str | unicode) – 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) – 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:
delete_vertex_collection(name, purge=False)

Remove a vertex collection from the graph.

Parameters:
  • name (str | unicode) – 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.

edge(edge, rev=None, check_rev=True)

Return an edge document.

Parameters:
  • edge (str | unicode | dict) – Edge document ID or body with “_id” field.
  • rev (str | unicode) – 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:
edge_collection(name)

Return the edge collection API wrapper.

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

Return the edge definitions of the graph.

Returns:Edge definitions of the graph.
Return type:[dict]
Raises:arango.exceptions.EdgeDefinitionListError – If retrieval fails.
edges(collection, vertex, direction=None)

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

Parameters:
  • collection (str | unicode) – Edge collection name.
  • vertex (str | unicode | dict) – Vertex document ID or body with “_id” field.
  • direction (str | unicode) – 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.

has_edge(edge, rev=None, check_rev=True)

Check if the given edge document exists in the graph.

Parameters:
  • edge (str | unicode | dict) – Edge document ID or body with “_id” field.
  • rev (str | unicode) – 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:
has_edge_collection(name)

Check if the graph has the given edge collection.

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

Check if the graph has the given edge definition.

Parameters:name (str | unicode) – Edge collection name.
Returns:True if edge definition exists, False otherwise.
Return type:bool
has_vertex(vertex, rev=None, check_rev=True)

Check if the given vertex document exists in the graph.

Parameters:
  • vertex (str | unicode | dict) – Vertex document ID or body with “_id” field.
  • rev (str | unicode) – 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:
has_vertex_collection(name)

Check if the graph has the given vertex collection.

Parameters:name (str | unicode) – Vertex collection name.
Returns:True if vertex collection exists, False otherwise.
Return type:bool
insert_edge(collection, edge, sync=None, silent=False)

Insert a new edge document.

Parameters:
  • collection (str | unicode) – 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) – 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.

insert_vertex(collection, vertex, sync=None, silent=False)

Insert a new vertex document.

Parameters:
  • collection (str | unicode) – 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) – 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.

Insert a new edge document linking the given vertices.

Parameters:
  • collection (str | unicode) – Edge collection name.
  • from_vertex (str | unicode | dict) – “From” vertex document ID or body with “_id” field.
  • to_vertex (str | unicode | 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) – 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.

name

Return the graph name.

Returns:Graph name.
Return type:str | unicode
properties()

Return graph properties.

Returns:Graph properties.
Return type:dict
Raises:arango.exceptions.GraphPropertiesError – If retrieval fails.
replace_edge(edge, check_rev=True, sync=None, silent=False)

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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
replace_edge_definition(edge_collection, from_vertex_collections, to_vertex_collections)

Replace an edge definition.

Parameters:
  • edge_collection (str | unicode) – Edge collection name.
  • from_vertex_collections ([str | unicode]) – Names of “from” vertex collections.
  • to_vertex_collections ([str | unicode]) – Names of “to” vertex collections.
Returns:

True if edge definition was replaced successfully.

Return type:

bool

Raises:

arango.exceptions.EdgeDefinitionReplaceError – If replace fails.

replace_vertex(vertex, check_rev=True, sync=None, silent=False)

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) – 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:
traverse(start_vertex, direction=u'outbound', item_order=u'forward', strategy=None, order=None, edge_uniqueness=None, vertex_uniqueness=None, max_iter=None, min_depth=None, max_depth=None, init_func=None, sort_func=None, filter_func=None, visitor_func=None, expander_func=None)

Traverse the graph and return the visited vertices and edges.

Parameters:
  • start_vertex (str | unicode | dict) – Start vertex document ID or body with “_id” field.
  • direction (str | unicode) – Traversal direction. Allowed values are “outbound” (default), “inbound” and “any”.
  • item_order (str | unicode) – Item iteration order. Allowed values are “forward” (default) and “backward”.
  • strategy (str | unicode) – Traversal strategy. Allowed values are “depthfirst” and “breadthfirst”.
  • order (str | unicode) – Traversal order. Allowed values are “preorder”, “postorder”, and “preorder-expander”.
  • vertex_uniqueness (str | unicode) – Uniqueness for visited vertices. Allowed values are “global”, “path” or “none”.
  • edge_uniqueness (str | unicode) – Uniqueness for visited edges. Allowed values are “global”, “path” or “none”.
  • min_depth (int) – Minimum depth of the nodes to visit.
  • max_depth (int) – Maximum depth of the nodes to visit.
  • max_iter (int) – If set, halt the traversal after the given number of iterations. This parameter can be used to prevent endless loops in cyclic graphs.
  • init_func (str | unicode) – Initialization function in Javascript with signature (config, result) -> void. This function is used to initialize values in the result.
  • sort_func (str | unicode) – 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 | unicode) – 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 | unicode) – 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 | unicode) – 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.

update_edge(edge, check_rev=True, keep_none=True, sync=None, silent=False)

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) – If set to True, fields with value None are retained in the document. If set to False, they are removed completely.
  • sync (bool) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update_vertex(vertex, check_rev=True, keep_none=True, sync=None, silent=False)

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) – 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:
vertex(vertex, rev=None, check_rev=True)

Return a vertex document.

Parameters:
  • vertex (str | unicode | dict) – Vertex document ID or body with “_id” field.
  • rev (str | unicode) – 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:
vertex_collection(name)

Return the vertex collection API wrapper.

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

Return vertex collections in the graph that are not orphaned.

Returns:Names of vertex collections that are not orphaned.
Return type:[str | unicode]
Raises:arango.exceptions.VertexCollectionListError – If retrieval fails.

HTTPClient

class arango.http.HTTPClient

Abstract base class for HTTP clients.

send_request(method, url, headers=None, params=None, data=None, auth=None)

Send an HTTP request.

This method must be overridden by the user.

Parameters:
  • method (str | unicode) – HTTP method in lowercase (e.g. “post”).
  • url (str | unicode) – Request URL.
  • headers (dict) – Request headers.
  • params (dict) – URL (query) parameters.
  • data (str | unicode | bool | int | list | dict) – Request payload.
  • auth (tuple) – Username and password.
Returns:

HTTP response.

Return type:

arango.response.Response

Pregel

class arango.pregel.Pregel(connection, executor)

Pregel API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
create_job(graph, algorithm, store=True, max_gss=None, thread_count=None, async_mode=None, result_field=None, algorithm_params=None)

Start a new Pregel job.

Parameters:
  • graph (str | unicode) – Graph name.
  • algorithm (str | unicode) – 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) – Max number of global iterations for the algorithm.
  • thread_count (int) – 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) – 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 | unicode) – If specified, most algorithms will write their results into this field.
  • algorithm_params (dict) – Additional algorithm parameters.
Returns:

Pregel job ID.

Return type:

int

Raises:

arango.exceptions.PregelJobCreateError – If create fails.

delete_job(job_id)

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.
job(job_id)

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.

Request

class arango.request.Request(method, endpoint, headers=None, params=None, data=None, command=None, read=None, write=None)

HTTP request.

Parameters:
  • method (str | unicode) – HTTP method in lowercase (e.g. “post”).
  • endpoint (str | unicode) – API endpoint.
  • headers (dict) – Request headers.
  • params (dict) – URL parameters.
  • data (str | unicode | bool | int | list | dict) – Request payload.
  • command (str | unicode) – ArangoSh command.
  • read (str | unicode | [str | unicode]) – Names of collections read during transaction.
  • write (str | unicode | [str | unicode]) – Names of collections written to during transaction.
Variables:
  • method (str | unicode) – HTTP method in lowercase (e.g. “post”).
  • endpoint (str | unicode) – API endpoint.
  • headers (dict) – Request headers.
  • params (dict) – URL (query) parameters.
  • data (str | unicode | bool | int | list | dict) – Request payload.
  • command (str | unicode | None) – ArangoSh command.
  • read (str | unicode | [str | unicode] | None) – Names of collections read during transaction.
  • write (str | unicode | [str | unicode] | None) – Names of collections written to during transaction.

Response

class arango.response.Response(method, url, headers, status_code, status_text, raw_body)

HTTP response.

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

TransactionDatabase

class arango.database.TransactionDatabase(connection, return_result, read, write, timeout, sync)

Database API wrapper tailored specifically for transactions.

See arango.database.StandardDatabase.begin_transaction().

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • return_result (bool) – If set to True, API executions return instances of arango.job.TransactionJob that are populated with results on commit. If set to False, API executions return None and no results are tracked client-side.
  • read ([str | unicode]) – Names of collections read during transaction.
  • write ([str | unicode]) – Names of collections written to during transaction.
  • timeout (int) – Timeout for waiting on collection locks. If set to 0, the ArangoDB server waits indefinitely. If not set, system default value is used.
  • sync (bool) – Block until operation is synchronized to disk.
aql

Return AQL (ArangoDB Query Language) API wrapper.

Returns:AQL API wrapper.
Return type:arango.aql.AQL
async_jobs(status, count=None)

Return IDs of async jobs with given status.

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

List of job IDs.

Return type:

[str | unicode]

Raises:

arango.exceptions.AsyncJobListError – If retrieval fails.

clear_async_jobs(threshold=None)

Clear async job results from the server.

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

Parameters:threshold (int) – 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.
collection(name)

Return the standard collection API wrapper.

Parameters:name (str | unicode) – Collection name.
Returns:Standard collection API wrapper.
Return type:arango.collection.StandardCollection
collections()

Return the collections in the database.

Returns:Collections in the database and their details.
Return type:[dict]
Raises:arango.exceptions.CollectionListError – If retrieval fails.
commit()

Execute the queued requests in a single transaction API request.

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

Returns:

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

Return type:

[arango.job.TransactionJob] | None

Raises:
context

Return the API execution context.

Returns:API execution context. Possible values are “default”, “async”, “batch” and “transaction”.
Return type:str | unicode
create_collection(name, sync=False, compact=True, system=False, journal_size=None, edge=False, volatile=False, user_keys=True, key_increment=None, key_offset=None, key_generator=u'traditional', shard_fields=None, shard_count=None, index_bucket_count=None, replication_factor=None, shard_like=None, sync_replication=None, enforce_replication_factor=None)

Create a new collection.

Parameters:
  • name (str | unicode) – Collection name.
  • sync (bool) – If set to True, document operations via the collection will block until synchronized to disk by default.
  • compact (bool) – If set to True, the collection is compacted. Applies only to MMFiles storage engine.
  • system (bool) – If set to True, a system collection is created. The collection name must have leading underscore “_” character.
  • journal_size (int) – Max size of the journal in bytes.
  • edge (bool) – If set to True, an edge collection is created.
  • volatile (bool) – If set to True, collection data is kept in-memory only and not made persistent. Unloading the collection will cause the collection data to be discarded. Stopping or re-starting the server will also cause full loss of data.
  • key_generator (str | unicode) – 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 | unicode]) – Field(s) used to determine the target shard.
  • shard_count (int) – Number of shards to create.
  • index_bucket_count (int) – Number of buckets into which indexes using hash tables are split. The default is 16, and this number has to be a power of 2 and less than or equal to 1024. For large collections, one should increase this to avoid long pauses when the hash table has to be initially built or re-sized, since buckets are re-sized individually and can be initially built in parallel. For instance, 64 may be a sensible value for 100 million documents.
  • 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 | unicode) – 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.
Returns:

Standard collection API wrapper.

Return type:

arango.collection.StandardCollection

Raises:

arango.exceptions.CollectionCreateError – If create fails.

create_database(name, users=None)

Create a new database.

Parameters:
  • name (str | unicode) – 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.
Returns:

True if database was created successfully.

Return type:

bool

Raises:

arango.exceptions.DatabaseCreateError – If create fails.

Here is an example entry for parameter users:

{
    'username': 'john',
    'password': 'password',
    'active': True,
    'extra': {'Department': 'IT'}
}
create_graph(name, edge_definitions=None, orphan_collections=None, smart=None, smart_field=None, shard_count=None)

Create a new graph.

Parameters:
  • name (str | unicode) – Graph name.
  • edge_definitions ([dict]) – 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 | unicode]) – Names of additional vertex collections that are not in edge definitions.
  • smart (bool) – If set to True, sharding is enabled (see parameter smart_field below). Applies only to enterprise version of ArangoDB.
  • smart_field (str | unicode) – 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) – 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.
Returns:

Graph API wrapper.

Return type:

arango.graph.Graph

Raises:

arango.exceptions.GraphCreateError – If create fails.

Here is an example entry for parameter edge_definitions:

{
    'edge_collection': 'teach',
    'from_vertex_collections': ['teachers'],
    'to_vertex_collections': ['lectures']
}
create_task(name, command, params=None, period=None, offset=None, task_id=None)

Create a new server task.

Parameters:
  • name (str | unicode) – Name of the server task.
  • command (str | unicode) – Javascript command to execute.
  • params (dict) – Optional parameters passed into the Javascript command.
  • period (int) – 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) – Initial delay before execution in seconds.
  • task_id (str | unicode) – Pre-defined ID for the new server task.
Returns:

Details of the new task.

Return type:

dict

Raises:

arango.exceptions.TaskCreateError – If create fails.

create_user(username, password, active=True, extra=None)

Create a new user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – Password.
  • active (bool) – True if user is active, False otherwise.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserCreateError – If create fails.

create_view(name, view_type, properties=None)

Create a view.

Parameters:
  • name (str | unicode) – View name.
  • view_type (str | unicode) – View type (e.g. “arangosearch”).
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewCreateError – If create fails.

databases()

Return the names all databases.

Returns:Database names.
Return type:[str | unicode]
Raises:arango.exceptions.DatabaseListError – If retrieval fails.
db_name

Return the name of the current database.

Returns:Database name.
Return type:str | unicode
delete_collection(name, ignore_missing=False, system=None)

Delete the collection.

Parameters:
  • name (str | unicode) – 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, ignore_missing=False)

Delete the database.

Parameters:
  • name (str | unicode) – Database name.
  • ignore_missing (bool) – Do not raise an exception on missing database.
Returns:

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

Return type:

bool

Raises:

arango.exceptions.DatabaseDeleteError – If delete fails.

delete_document(document, rev=None, check_rev=True, ignore_missing=False, return_old=False, sync=None, silent=False)

Delete a document.

Parameters:
  • document (str | unicode | dict) – Document ID, key or body. Document body must contain the “_id” field.
  • rev (str | unicode) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
delete_graph(name, ignore_missing=False, drop_collections=None)

Drop the graph of the given name from the database.

Parameters:
  • name (str | unicode) – Graph name.
  • ignore_missing (bool) – Do not raise an exception on missing graph.
  • drop_collections (bool) – 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, ignore_missing=False)

Delete a server task.

Parameters:
  • task_id (str | unicode) – 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, ignore_missing=False)

Delete a user.

Parameters:
  • username (str | unicode) – 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, ignore_missing=False)

Delete a view.

Parameters:name (str | unicode) – View name.
Returns:True if view was deleted successfully, False if view was not found and ignore_missing was set to True.
Return type:dict
Raises:arango.exceptions.ViewDeleteError – If delete fails.
details()

Return ArangoDB server details.

Returns:Server details.
Return type:dict
Raises:arango.exceptions.ServerDetailsError – If retrieval fails.
document(document, rev=None, check_rev=True)

Return a document.

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

Document, or None if not found.

Return type:

dict | None

Raises:
echo()

Return details of the last request (e.g. headers, payload).

Returns:Details of the last request.
Return type:dict
Raises:arango.exceptions.ServerEchoError – If retrieval fails.
endpoints()

Return coordinate endpoints. This method is for clusters only.

Returns:List of endpoints.
Return type:[str | unicode]
Raises:arango.exceptions.ServerEndpointsError – If retrieval fails.
engine()

Return the database engine details.

Returns:Database engine details.
Return type:str | unicode
Raises:arango.exceptions.ServerEngineError – If retrieval fails.
execute_transaction(command, params=None, read=None, write=None, sync=None, timeout=None, max_size=None, allow_implicit=None, intermediate_commit_count=None, intermediate_commit_size=None)

Execute raw Javascript command in transaction.

Parameters:
  • command (str | unicode) – Javascript command to execute.
  • read ([str | unicode]) – Names of collections read during transaction. If parameter allow_implicit is set to True, any undeclared read collections are loaded lazily.
  • write ([str | unicode]) – Names of collections written to during transaction. Transaction fails on undeclared write collections.
  • params (dict) – Optional parameters passed into the Javascript command.
  • sync (bool) – Block until operation is synchronized to disk.
  • timeout (int) – 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) – Max transaction size limit in bytes. Applies only to RocksDB storage engine.
  • allow_implicit (bool) – If set to True, undeclared read collections are loaded lazily. If set to False, transaction fails on any undeclared collections.
  • intermediate_commit_count (int) – Max number of operations after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
  • intermediate_commit_size (int) – Max size of operations in bytes after which an intermediate commit is performed automatically. Applies only to RocksDB storage engine.
Returns:

Return value of command.

Return type:

str | unicode

Raises:

arango.exceptions.TransactionExecuteError – If execution fails.

foxx

Return Foxx API wrapper.

Returns:Foxx API wrapper.
Return type:arango.foxx.Foxx
graph(name)

Return the graph API wrapper.

Parameters:name (str | unicode) – Graph name.
Returns:Graph API wrapper.
Return type:arango.graph.Graph
graphs()

List all graphs in the database.

Returns:Graphs in the database.
Return type:[dict]
Raises:arango.exceptions.GraphListError – If retrieval fails.
has_collection(name)

Check if collection exists in the database.

Parameters:name (str | unicode) – Collection name.
Returns:True if collection exists, False otherwise.
Return type:bool
has_database(name)

Check if a database exists.

Parameters:name (str | unicode) – Database name.
Returns:True if database exists, False otherwise.
Return type:bool
has_document(document, rev=None, check_rev=True)

Check if a document exists.

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

True if document exists, False otherwise.

Return type:

bool

Raises:
has_graph(name)

Check if a graph exists in the database.

Parameters:name (str | unicode) – Graph name.
Returns:True if graph exists, False otherwise.
Return type:bool
has_user(username)

Check if user exists.

Parameters:username (str | unicode) – Username.
Returns:True if user exists, False otherwise.
Return type:bool
insert_document(collection, document, return_new=False, sync=None, silent=False, overwrite=False, return_old=False)

Insert a new document.

Parameters:
  • collection (str | unicode) – 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) – 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.
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.

log_levels()

Return current logging levels.

Returns:Current logging levels.
Return type:dict
name

Return database name.

Returns:Database name.
Return type:str | unicode
permission(username, database, collection=None)

Return user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

Permission for given database or collection.

Return type:

str | unicode

Raise:

arango.exceptions.PermissionGetError: If retrieval fails.

permissions(username)

Return user permissions for all databases and collections.

Parameters:username (str | unicode) – Username.
Returns:User permissions for all databases and collections.
Return type:dict
Raise:arango.exceptions.PermissionListError: If retrieval fails.
ping()

Ping the ArangoDB server by sending a test request.

Returns:Response code from server.
Return type:int
Raises:arango.exceptions.ServerConnectionError – If ping fails.
pregel

Return Pregel API wrapper.

Returns:Pregel API wrapper.
Return type:arango.pregel.Pregel
properties()

Return database properties.

Returns:Database properties.
Return type:dict
Raises:arango.exceptions.DatabasePropertiesError – If retrieval fails.
queued_jobs()

Return the queued transaction jobs.

Returns:Queued transaction jobs, or None if return_result was set to False during initialization.
Return type:[arango.job.TransactionJob] | None
read_log(upto=None, level=None, start=None, size=None, offset=None, search=None, sort=None)

Read the global log from server.

Parameters:
  • upto (str | unicode | int) – 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 (str | unicode | int) – 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 | unicode) – Return only the log entries containing the given text.
  • sort (str | unicode) – 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.

reload_routing()

Reload the routing information.

Returns:True if routing was reloaded successfully.
Return type:bool
Raises:arango.exceptions.ServerReloadRoutingError – If reload fails.
rename_view(name, new_name)

Rename a view.

Parameters:name (str | unicode) – View name.
Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewRenameError – If delete fails.
replace_document(document, check_rev=True, return_new=False, return_old=False, sync=None, silent=False)

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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
replace_user(username, password, active=None, extra=None)

Replace a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserReplaceError – If replace fails.

replace_view(name, properties)

Replace a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewReplaceError – If replace fails.

required_db_version()

Return required version of target database.

Returns:Required version of target database.
Return type:str | unicode
Raises:arango.exceptions.ServerRequiredDBVersionError – If retrieval fails.
reset_permission(username, database, collection=None)

Reset user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
Returns:

True if permission was reset successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionRestError – If reset fails.

role()

Return server role in cluster.

Returns:Server role. Possible values are “SINGLE” (server which is not in a cluster), “COORDINATOR” (cluster coordinator), “PRIMARY”, “SECONDARY” or “UNDEFINED”.
Return type:str | unicode
Raises:arango.exceptions.ServerRoleError – If retrieval fails.
run_tests(tests)

Run available unittests on the server.

Parameters:tests ([str | unicode]) – List of files containing the test suites.
Returns:Test results.
Return type:dict
Raises:arango.exceptions.ServerRunTestsError – If execution fails.
set_log_levels(**kwargs)

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.

Returns:New logging levels.
Return type:dict
shutdown()

Initiate server shutdown sequence.

Returns:True if the server was shutdown successfully.
Return type:bool
Raises:arango.exceptions.ServerShutdownError – If shutdown fails.
statistics(description=False)

Return server statistics.

Returns:Server statistics.
Return type:dict
Raises:arango.exceptions.ServerStatisticsError – If retrieval fails.
status()

Return ArangoDB server status.

Returns:Server status.
Return type:dict
Raises:arango.exceptions.ServerStatusError – If retrieval fails.
task(task_id)

Return the details of an active server task.

Parameters:task_id (str | unicode) – Server task ID.
Returns:Server task details.
Return type:dict
Raises:arango.exceptions.TaskGetError – If retrieval fails.
tasks()

Return all currently active server tasks.

Returns:Currently active server tasks.
Return type:[dict]
Raises:arango.exceptions.TaskListError – If retrieval fails.
time()

Return server system time.

Returns:Server system time.
Return type:datetime.datetime
Raises:arango.exceptions.ServerTimeError – If retrieval fails.
update_document(document, check_rev=True, merge=True, keep_none=True, return_new=False, return_old=False, sync=None, silent=False)

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) – If set to True, sub-dictionaries are merged instead of the new one overwriting the old one.
  • keep_none (bool) – 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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update_permission(username, permission, database, collection=None)

Update user permission for a specific database or collection.

Parameters:
  • username (str | unicode) – Username.
  • database (str | unicode) – Database name.
  • collection (str | unicode) – Collection name.
  • permission (str | unicode) – Allowed values are “rw” (read and write), “ro” (read only) or “none” (no access).
Returns:

True if access was granted successfully.

Return type:

bool

Raises:

arango.exceptions.PermissionUpdateError – If update fails.

update_user(username, password=None, active=None, extra=None)

Update a user.

Parameters:
  • username (str | unicode) – Username.
  • password (str | unicode) – New password.
  • active (bool) – Whether the user is active.
  • extra (dict) – Additional data for the user.
Returns:

New user details.

Return type:

dict

Raises:

arango.exceptions.UserUpdateError – If update fails.

update_view(name, properties)

Update a view.

Parameters:
  • name (str | unicode) – View name.
  • properties (dict) – View properties.
Returns:

View details.

Return type:

dict

Raises:

arango.exceptions.ViewUpdateError – If update fails.

user(username)

Return user details.

Parameters:username (str | unicode) – Username.
Returns:User details.
Return type:dict
Raises:arango.exceptions.UserGetError – If retrieval fails.
username

Return the username.

Returns:Username.
Return type:str | unicode
users()

Return all user details.

Returns:List of user details.
Return type:[dict]
Raises:arango.exceptions.UserListError – If retrieval fails.
version()

Return ArangoDB server version.

Returns:Server version.
Return type:str | unicode
Raises:arango.exceptions.ServerVersionError – If retrieval fails.
view(name)

Return view details.

Returns:View details.
Return type:dict
Raises:arango.exceptions.ViewGetError – If retrieval fails.
views()

Return list of views.

Returns:List of views.
Return type:[dict]
Raises:arango.exceptions.ViewListError – If retrieval fails.
wal

Return WAL (Write-Ahead Log) API wrapper.

Returns:WAL API wrapper.
Return type:arango.wal.WAL

TransactionJob

class arango.job.TransactionJob(response_handler)

Transaction API execution job.

Parameters:response_handler (callable) – HTTP response handler.
id

Return the transaction job ID.

Returns:Transaction job ID.
Return type:str | unicode
result()

Return the transaction job result.

Returns:

Transaction job result.

Return type:

str | unicode | bool | int | list | dict

Raises:
status()

Return the transaction job status.

Returns:Transaction job status. Possible values are “pending” (job is waiting for transaction to be committed, or transaction failed and job is orphaned), or “done” (transaction was committed and job is updated with the result).
Return type:str | unicode

VertexCollection

class arango.collection.VertexCollection(connection, executor, graph, name)

Vertex collection API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
  • graph (str | unicode) – Graph name.
  • name (str | unicode) – Vertex collection name.
delete(vertex, rev=None, check_rev=True, ignore_missing=False, sync=None)

Delete a vertex document.

Parameters:
  • vertex (str | unicode | dict) – Vertex document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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) – 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:
get(vertex, rev=None, check_rev=True)

Return a vertex document.

Parameters:
  • vertex (str | unicode | dict) – Vertex document ID, key or body. Document body must contain the “_id” or “_key” field.
  • rev (str | unicode) – 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:
graph

Return the graph name.

Returns:Graph name.
Return type:str | unicode
insert(vertex, sync=None, silent=False)

Insert a new vertex document.

Parameters:
  • 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) – 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.

replace(vertex, check_rev=True, sync=None, silent=False)

Replace a vertex document.

Parameters:
  • vertex (dict) – New vertex document to replace the old one with. It must contain the “_key” or “_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) – Block until operation is synchronized to disk.
  • silent (bool) – If set to True, no document metadata is returned. This can be used to save resources.
Returns:

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

Return type:

bool | dict

Raises:
update(vertex, check_rev=True, keep_none=True, sync=None, silent=False, return_old=False, return_new=False)

Update a vertex document.

Parameters:
  • vertex (dict) – Partial or full vertex document with updated values. It must contain the “_key” or “_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) – 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:

WAL

class arango.wal.WAL(connection, executor)

WAL (Write-Ahead Log) API wrapper.

Parameters:
  • connection (arango.connection.Connection) – HTTP connection.
  • executor (arango.executor.Executor) – API executor.
configure(oversized_ops=None, log_size=None, historic_logs=None, reserve_logs=None, throttle_wait=None, throttle_limit=None)

Configure WAL properties.

Parameters:
  • oversized_ops (bool) – If set to True, operations bigger than a single log file are allowed to be executed and stored.
  • log_size (int) – Size of each write-ahead log file in bytes.
  • historic_logs (int) – Max number of historic log files to keep.
  • reserve_logs (int) – Max number of reserve log files to allocate.
  • throttle_wait (int) – Wait time before aborting when write-throttled in milliseconds.
  • throttle_limit (int) – Number of pending garbage collector operations that, when reached, activates write-throttling. Value of 0 means no throttling is triggered.
Returns:

New WAL properties.

Return type:

dict

Raises:

arango.exceptions.WALConfigureError – If operation fails.

flush(sync=True, garbage_collect=True)

Synchronize WAL to disk.

Parameters:
  • sync (bool) – Block until the synchronization is complete.
  • garbage_collect (bool) – Block until flushed data is garbage collected.
Returns:

True if WAL was flushed successfully.

Return type:

bool

Raises:

arango.exceptions.WALFlushError – If flush operation fails.

properties()

Return WAL properties.

Returns:WAL properties.
Return type:dict
Raises:arango.exceptions.WALPropertiesError – If retrieval fails.
transactions()

Return details on currently running WAL transactions.

Fields in the returned details are as follows:

"last_collected"    : ID of the last collected log file (at the
                      start of each running transaction) or None
                      if no transactions are running.

"last_sealed"       : ID of the last sealed log file (at the start
                      of each running transaction) or None if no
                      transactions are running.

"count"             : Number of currently running transactions.
Returns:Details on currently running WAL transactions.
Return type:dict
Raises:arango.exceptions.WALTransactionListError – If retrieval fails.