Helper Types

The driver comes with a set of helper types and wrappers to make it easier to work with the ArangoDB API. These are designed to behave like dictionaries, but with some additional features and methods. See the arangoasync.typings.JsonWrapper class for more details.

Example:

from arangoasync import ArangoClient
from arangoasync.auth import Auth
from arangoasync.typings import QueryProperties

# Initialize the client for ArangoDB.
async with ArangoClient(hosts="http://localhost:8529") as client:
    auth = Auth(username="root", password="passwd")

    # Connect to "test" database as root user.
    db = await client.db("test", auth=auth)

    properties = QueryProperties(
        allow_dirty_reads=True,
        allow_retry=False,
        fail_on_warning=True,
        fill_block_cache=False,
        full_count=True,
        intermediate_commit_count=1000,
        intermediate_commit_size=1048576,
        max_dnf_condition_members=10,
        max_nodes_per_callstack=100,
        max_number_of_plans=5,
        max_runtime=60.0,
        max_transaction_size=10485760,
        max_warning_count=10,
        optimizer={"rules": ["-all", "+use-indexes"]},
        profile=1,
        satellite_sync_wait=10.0,
        skip_inaccessible_collections=True,
        spill_over_threshold_memory_usage=10485760,
        spill_over_threshold_num_rows=100000,
        stream=True,
        use_plan_cache=True,
    )

    # The types are fully serializable.
    print(properties)

    await db.aql.execute(
        "FOR doc IN students RETURN doc",
        batch_size=1,
        options=properties,
    )

You can easily customize the data representation using formatters. By default, keys are in the format used by the ArangoDB API, but you can change them to snake_case if you prefer. See arangoasync.typings.JsonWrapper.format() for more details.

Example:

from arangoasync.typings import Json, UserInfo

data = {
    "user": "john",
    "password": "secret",
    "active": True,
    "extra": {"role": "admin"},
}
user_info = UserInfo(**data)

def uppercase_formatter(data: Json) -> Json:
    result: Json = {}
    for key, value in data.items():
        result[key.upper()] = value
    return result

print(user_info.format(uppercase_formatter))

Helpers

Below are all the available helpers.

arangoasync.typings.Json

Type definition for request/response body

alias of Dict[str, Any]

arangoasync.typings.Jsons

Type definition for a list of JSON objects

alias of List[Dict[str, Any]]

arangoasync.typings.RequestHeaders

Type definition for request HTTP headers

alias of MutableMapping[str, str] | MultiDict[str]

arangoasync.typings.ResponseHeaders

Type definition for response HTTP headers

alias of MutableMapping[str, str] | MultiDict[str] | CIMultiDictProxy[str]

arangoasync.typings.Params

Type definition for URL (query) parameters

alias of MutableMapping[str, bool | int | str | float]

arangoasync.typings.Formatter

Type definition for a JSON formatter

alias of Callable[[Dict[str, Any]], Dict[str, Any]]

class arangoasync.typings.CollectionType(*values)

Collection types.

static from_int(value)

Return a collection type from its integer value.

Parameters:

value (int) – Collection type integer value.

Returns:

Collection type.

Return type:

CollectionType

static from_str(value)

Return a collection type from its string value.

Parameters:

value (str) – Collection type string value.

Returns:

Collection type.

Return type:

CollectionType

class arangoasync.typings.CollectionStatus(*values)

Collection status.

static from_int(value)

Return a collection status from its integer value.

Parameters:

value (int) – Collection status integer value.

Returns:

Collection status.

Return type:

CollectionStatus

class arangoasync.typings.JsonWrapper(data)

Wrapper over server request/response objects.

get(key, default=None)

Return the value for key if key is in the dictionary, else default.

items()

Return an iterator over the dictionary’s key-value pairs.

keys()

Return an iterator over the dictionary’s keys.

values()

Return an iterator over the dictionary’s values.

to_dict()

Return the dictionary.

format(formatter=None)

Apply a formatter to the data.

Returns the unmodified data by default. Should not modify the object in-place.

class arangoasync.typings.KeyOptions(allow_user_keys=True, generator_type='traditional', increment=None, offset=None, data=None)

Additional options for key generation, used on collections.

Parameters:

• allow_user_keys (bool) – If set to True, then you are allowed to supply own key values in the _key attribute of documents. If set to False, then the key generator is solely responsible for generating keys and an error is raised if you supply own key values in the _key attribute of documents.

• generator_type (str) – Specifies the type of the key generator. The currently available generators are “traditional”, “autoincrement”, “uuid” and “padded”.

• increment (int | None) – The increment value for the “autoincrement” key generator. Not allowed for other key generator types.

• offset (int | None) – The initial offset value for the “autoincrement” key generator. Not allowed for other key generator types.

• data (dict | None) – Key options. If this parameter is specified, the other parameters are ignored.

Example

{
    "type": "autoincrement",
    "increment": 5,
    "allowUserKeys": true
}

References

• create-a-collection

validate()

Validate key options.

static compatibility_formatter(data)

python-arango compatibility formatter.

format(formatter=None)

Apply a formatter to the data.

By default, the python-arango compatibility formatter is applied.

class arangoasync.typings.CollectionInfo(data)

Collection information.

Example

{
    "id" : "151",
    "name" : "animals",
    "status" : 3,
    "type" : 2,
    "isSystem" : false,
    "globallyUniqueId" : "hDA74058C1843/151"
}

References

• get-the-collection-information

property globally_unique_id

“A unique identifier of the collection (internal property).

property is_system

Whether the collection is a system collection.

property name

Return the name of the collection.

property status

Return the status of the collection.

property col_type

Return the type of the collection.

static compatibility_formatter(data)

python-arango compatibility formatter.

format(formatter=None)

Apply a formatter to the data.

By default, the python-arango compatibility formatter is applied.

class arangoasync.typings.UserInfo(user, password=None, active=True, extra=None)

User information.

Parameters:

• user (str) – The name of the user.

• password (str | None) – The user password as a string. Note that user password is not returned back by the server.

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

• extra (dict | None) – Additional user information. For internal use only. Should not be set or modified by end users.

Example

{
    "user": "john",
    "password": "secret",
    "active": true,
    "extra": {}
}

References

• create-a-user

static user_management_formatter(data)

Request formatter.

format(formatter=None)

Apply a formatter to the data.

class arangoasync.typings.ServerStatusInformation(data)

Status information about the server.

Example

{
  "server" : "arango",
  "version" : "3.12.2",
  "pid" : 244,
  "license" : "enterprise",
  "mode" : "server",
  "operationMode" : "server",
  "foxxApi" : true,
  "host" : "localhost",
  "hostname" : "ebd1509c9185",
  "serverInfo" : {
    "progress" : {
      "phase" : "in wait",
      "feature" : "",
      "recoveryTick" : 0
    },
    "maintenance" : false,
    "role" : "COORDINATOR",
    "writeOpsEnabled" : true,
    "readOnly" : false,
    "persistedId" : "CRDN-329cfc20-071f-4faf-9727-7e48a7aed1e5",
    "rebootId" : 1,
    "address" : "tcp://localhost:8529",
    "serverId" : "CRDN-329cfc20-071f-4faf-9727-7e48a7aed1e5",
    "state" : "SERVING"
  },
  "coordinator" : {
    "foxxmaster" : "CRDN-0ed76822-3e64-47ed-a61b-510f2a696175",
    "isFoxxmaster" : false
  },
  "agency" : {
    "agencyComm" : {
      "endpoints" : [
        "tcp://localhost:8551",
        "tcp://localhost:8541",
        "tcp://localhost:8531"
      ]
    }
  }
}

References

• get-server-status-information

class arangoasync.typings.DatabaseProperties(data, strip_result=False)

Properties of the database.

References

• get-information-about-the-current-database

property name

The name of the current database.

property id

The id of the current database.

property path

The filesystem path of the current database. Removed in ArangoDB 4.0.

property is_system

Whether the database is the _system database.

property sharding

The default sharding method for collections.

property replication_factor

The default replication factor for collections.

property write_concern

The default write concern for collections.

static compatibility_formatter(data)

python-arango compatibility formatter.

format(formatter=None)

Apply a formatter to the data.

By default, the python-arango compatibility formatter is applied.

class arangoasync.typings.CollectionProperties(data)

Properties of a collection.

Example

{
  "writeConcern" : 1,
  "waitForSync" : true,
  "usesRevisionsAsDocumentIds" : true,
  "syncByRevision" : true,
  "statusString" : "loaded",
  "id" : "68452",
  "isSmartChild" : false,
  "schema" : null,
  "name" : "products",
  "type" : 2,
  "status" : 3,
  "cacheEnabled" : false,
  "isSystem" : false,
  "internalValidatorType" : 0,
  "globallyUniqueId" : "hDA74058C1843/68452",
  "keyOptions" : {
    "allowUserKeys" : true,
    "type" : "traditional",
    "lastValue" : 0
  },
  "computedValues" : null,
  "objectId" : "68453"
}

References

• get-the-properties-of-a-collection

static compatibility_formatter(data)

python-arango compatibility formatter.

format(formatter=None)

Apply a formatter to the data.

By default, the python-arango compatibility formatter is applied.

class arangoasync.typings.CollectionStatistics(data)

Statistical information about the collection.

Example

 {
   "figures" : {
     "indexes" : {
       "count" : 1,
       "size" : 1234
     },
     "documentsSize" : 5601,
     "cacheInUse" : false,
     "cacheSize" : 0,
     "cacheUsage" : 0,
     "engine" : {
       "documents" : 1,
       "indexes" : [
         {
           "type" : "primary",
           "id" : 0,
           "count" : 1
         }
       ]
     }
   },
   "writeConcern" : 1,
   "waitForSync" : false,
   "usesRevisionsAsDocumentIds" : true,
   "syncByRevision" : true,
   "statusString" : "loaded",
   "id" : "69123",
   "isSmartChild" : false,
   "schema" : null,
   "name" : "products",
   "type" : 2,
   "status" : 3,
   "count" : 1,
   "cacheEnabled" : false,
   "isSystem" : false,
   "internalValidatorType" : 0,
   "globallyUniqueId" : "hB7C02EE43DCE/69123",
   "keyOptions" : {
     "allowUserKeys" : true,
     "type" : "traditional",
     "lastValue" : 69129
   },
   "computedValues" : null,
   "objectId" : "69124"
}

References

• get-the-collection-statistics

class arangoasync.typings.IndexProperties(data)

Properties of an index.

Example

{
  "fields" : [
    "_key"
  ],
  "id" : "products/0",
  "name" : "primary",
  "selectivityEstimate" : 1,
  "sparse" : false,
  "type" : "primary",
  "unique" : true,
}

References

• get-an-index

static compatibility_formatter(data)

python-arango compatibility formatter.

format(formatter=None)

Apply a formatter to the data.

By default, the python-arango compatibility formatter is applied.

class arangoasync.typings.QueryProperties(allow_dirty_reads=None, allow_retry=None, fail_on_warning=None, fill_block_cache=None, full_count=None, intermediate_commit_count=None, intermediate_commit_size=None, max_dnf_condition_members=None, max_nodes_per_callstack=None, max_number_of_plans=None, max_runtime=None, max_transaction_size=None, max_warning_count=None, optimizer=None, profile=None, satellite_sync_wait=None, skip_inaccessible_collections=None, spill_over_threshold_memory_usage=None, spill_over_threshold_num_rows=None, stream=None, use_plan_cache=None)

Extra options for AQL queries.

Parameters:

• allow_dirty_reads (bool | None) – If set to True, when executing the query against a cluster deployment, the Coordinator is allowed to read from any shard replica and not only from the leader.

• allow_retry (bool | None) – Setting it to True makes it possible to retry fetching the latest batch from a cursor.

• fail_on_warning (bool | None) – If set to True, the query will throw an exception and abort instead of producing a warning.

• fill_block_cache (bool | None) – If set to True, it will make the query store the data it reads via the RocksDB storage engine in the RocksDB block cache.

• full_count (bool | None) – If set to True and the query contains a LIMIT clause, then the result will have some extra attributes.

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

• intermediate_commit_size (int | None) – The maximum total size of operations after which an intermediate commit is performed automatically.

• max_dnf_condition_members (int | None) – A threshold for the maximum number of OR sub-nodes in the internal representation of an AQL FILTER condition.

• max_nodes_per_callstack (int | None) – The number of execution nodes in the query plan after that stack splitting is performed to avoid a potential stack overflow.

• max_number_of_plans (int | None) – Limits the maximum number of plans that are created by the AQL query optimizer.

• max_runtime (float | None) – The query has to be executed within the given runtime or it is killed. The value is specified in seconds. If unspecified, there will be no timeout.

• max_transaction_size (int | None) – The maximum transaction size in bytes.

• max_warning_count (int | None) – Limits the maximum number of warnings a query will return.

• optimizer (dict | None) – Options related to the query optimizer.

• profile (int | None) – Return additional profiling information in the query result. Can be set to 1 or 2 (for more detailed profiling information).

• satellite_sync_wait (flat | None) – How long a DB-Server has time to bring the SatelliteCollections involved in the query into sync (in seconds).

• skip_inaccessible_collections (bool | None) – Treat collections to which a user has no access rights for as if these collections are empty.

• spill_over_threshold_memory_usage (int | None) – This option allows queries to store intermediate and final results temporarily on disk if the amount of memory used (in bytes) exceeds the specified value.

• spill_over_threshold_num_rows (int | None) – This option allows queries to store intermediate and final results temporarily on disk if the number of rows produced by the query exceeds the specified value.

• stream (bool | None) – Can be enabled to execute the query lazily.

• use_plan_cache (bool | None) – Set this option to True to utilize a cached query plan or add the execution plan of this query to the cache if it’s not in the cache yet.

Example

{
  "maxPlans": 1,
  "optimizer": {
    "rules": [
      "-all",
      "+remove-unnecessary-filters"
    ]
  }
}

References

• create-a-cursor

class arangoasync.typings.QueryExecutionPlan(data)

The execution plan of an AQL query.

References

• plan

class arangoasync.typings.QueryExecutionProfile(data)

The duration of the different query execution phases in seconds.

Example

{
  "initializing" : 0.0000028529999838156073,
  "parsing" : 0.000029285000010759177,
  "optimizing ast" : 0.0000040699999885873694,
  "loading collections" : 0.000012807000018710823,
  "instantiating plan" : 0.00002348999998957879,
  "optimizing plan" : 0.00006598600000984334,
  "instantiating executors" : 0.000027471999999306718,
  "executing" : 0.7550992429999894,
  "finalizing" : 0.00004103500000951499
}

References

• profile

class arangoasync.typings.QueryExecutionStats(data)

Statistics of an AQL query.

Example

{
  "writesExecuted" : 0,
  "writesIgnored" : 0,
  "documentLookups" : 0,
  "seeks" : 0,
  "scannedFull" : 2,
  "scannedIndex" : 0,
  "cursorsCreated" : 0,
  "cursorsRearmed" : 0,
  "cacheHits" : 0,
  "cacheMisses" : 0,
  "filtered" : 0,
  "httpRequests" : 0,
  "executionTime" : 0.00019362399999067748,
  "peakMemoryUsage" : 0,
  "intermediateCommits" : 0
}

References

• stats

class arangoasync.typings.QueryExecutionExtra(data)

Extra information about the query result.

References

• extra

class arangoasync.typings.QueryTrackingConfiguration(data)

AQL query tracking configuration.

Example

{
    "enabled": true,
    "trackSlowQueries": true,
    "trackBindVars": true,
    "maxSlowQueries": 64,
    "slowQueryThreshold": 10,
    "slowStreamingQueryThreshold": 10,
    "maxQueryStringLength": 4096
}

References

• get-the-aql-query-tracking-configuration

class arangoasync.typings.QueryExplainOptions(all_plans=None, max_plans=None, optimizer=None)

Options for explaining an AQL query.

Parameters:

• all_plans (bool | None) – If set to True, all possible execution plans are returned.

• max_plans (int | None) – The maximum number of plans to return.

• optimizer (dict | None) – Options related to the query optimizer.

Example

{
  "allPlans" : false,
  "maxNumberOfPlans" : 1,
  "optimizer" : {
    "rules" : [
      "-all",
      "+use-indexe-for-sort"
    ]
  }
}

References

• explain-an-aql-query

class arangoasync.typings.QueryCacheProperties(data)

AQL Cache Configuration.

Example

{
  "mode" : "demand",
  "maxResults" : 128,
  "maxResultsSize" : 268435456,
  "maxEntrySize" : 16777216,
  "includeSystem" : false
}

References

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

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

class arangoasync.typings.GraphProperties(data)

Graph properties.

Example

{
  "_key" : "myGraph",
  "edgeDefinitions" : [
    {
      "collection" : "edges",
      "from" : [
        "startVertices"
      ],
      "to" : [
        "endVertices"
      ]
    }
  ],
  "orphanCollections" : [ ],
  "_rev" : "_jJdpHEy--_",
  "_id" : "_graphs/myGraph",
  "name" : "myGraph"
}

References

• get-a-graph

• list-all-graphs

• create-a-graph

property is_smart

Check if the graph is a smart graph.

property is_satellite

Check if the graph is a satellite graph.

class arangoasync.typings.GraphOptions(number_of_shards=None, replication_factor=None, satellites=None, smart_graph_attribute=None, write_concern=None)

Special options for graph creation.

Parameters:

• number_of_shards (int) – The number of shards that is used for every collection within this graph. Cannot be modified later.

• replication_factor (int | str) – The replication factor used when initially creating collections for this graph. Can be set to “satellite” to create a SatelliteGraph, which then ignores numberOfShards, minReplicationFactor, and writeConcern (Enterprise Edition only).

• satellites (list[str] | None) – An array of collection names that is used to create SatelliteCollections for a (Disjoint) SmartGraph using SatelliteCollections (Enterprise Edition only). Each array element must be a string and a valid collection name.

• smart_graph_attribute (str | None) – The attribute name that is used to smartly shard the vertices of a graph. Only available in Enterprise Edition.

• write_concern (int | None) – The write concern for new collections in the graph.

References

• create-a-graph

class arangoasync.typings.VertexCollectionOptions(satellites=None)

Special options for vertex collection creation.

Parameters:

satellites (list) – An array of collection names that is used to create SatelliteCollections for a (Disjoint) SmartGraph using SatelliteCollections (Enterprise Edition only). Each array element must be a string and a valid collection name.

References

• add-a-vertex-collection

class arangoasync.typings.EdgeDefinitionOptions(satellites=None)

Special options for edge definition creation.

Parameters:

satellites (list) – An array of collection names that is used to create SatelliteCollections for a (Disjoint) SmartGraph using SatelliteCollections (Enterprise Edition only). Each array element must be a string and a valid collection name.

References

• add-an-edge-definition

class arangoasync.typings.AccessToken(data)

User access token.

Example

{
  "id" : 1,
  "name" : "Token for Service A",
  "valid_until" : 1782864000,
  "created_at" : 1765543306,
  "fingerprint" : "v1...71227d",
  "active" : true,
  "token" : "v1.7b2265223a3137471227d"
}

References

• create-an-access-token