def flush(self,
sync: bool = True,
garbage_collect: bool = True) -> Result[bool]:
"""Synchronize WAL to disk.
:param sync: Block until the synchronization is complete.
:type sync: bool | None
:param garbage_collect: Block until flushed data is garbage collected.
:type garbage_collect: bool
:return: True if WAL was flushed successfully.
:rtype: bool
:raise arango.exceptions.WALFlushError: If flush operation fails.
"""
request = Request(
method="put",
endpoint="/_admin/wal/flush",
params={
"waitForSync": sync,
"waitForCollector": garbage_collect
},
)
def response_handler(resp: Response) -> bool:
if resp.is_success:
return True
raise WALFlushError(resp, request)
return self._execute(request, response_handler)
def inventory(self, batch_id, include_system=None, all_databases=None):
"""Return an overview of collections and indexes.
:param batch_id: Batch ID.
:type batch_id: str
:param include_system: Include system collections in the result.
Default value is True.
:type include_system: bool
:param all_databases: Include all databases. Only works on "_system"
database. Default value is False.
:type all_databases: bool
:return: Overview of collections and indexes.
:rtype: dict
:raise arango.exceptions.ReplicationInventoryError: If retrieval fails.
"""
params = {'batchId': batch_id}
if include_system is not None:
params['includeSystem'] = include_system
if all_databases is not None:
params['global'] = all_databases
request = Request(method='get',
endpoint='/_api/replication/inventory',
params=params)
def response_handler(resp):
if resp.is_success:
return format_replication_inventory(resp.body)
raise ReplicationInventoryError(resp, request)
return self._execute(request, response_handler)
def get(self, key, rev=None):
"""Fetch a document by key from the edge collection.
:param key: the document key
:type key: str | unicode
:param rev: the document revision
:type rev: str | unicode | None
:returns: the vertex document or ``None`` if not found
:rtype: dict | None
:raises arango.exceptions.DocumentRevisionError: if the given revision
does not match the revision of the target document
:raises arango.exceptions.DocumentGetError: if the document cannot
be fetched from the collection
"""
request = Request(method='get',
endpoint='/_api/gharial/{}/edge/{}/{}'.format(
self._graph_name, self._name, key),
headers={'If-Match': rev} if rev else {})
def handler(res):
if res.status_code == 412:
raise DocumentRevisionError(res)
elif res.status_code == 404 and res.error_code == 1202:
return None
elif res.status_code not in HTTP_OK:
raise DocumentGetError(res)
return res.body["edge"]
return request, handler
def create_function(self, name, code):
"""Create a new AQL function.
:param name: AQL function name.
:type name: str | unicode
:param code: Function definition in Javascript.
:type code: str | unicode
:return: Whether the AQL function was newly created or an existing one
was replaced.
:rtype: dict
:raise arango.exceptions.AQLFunctionCreateError: If create fails.
"""
request = Request(method='post',
endpoint='/_api/aqlfunction',
data={
'name': name,
'code': code
})
def response_handler(resp):
if not resp.is_success:
raise AQLFunctionCreateError(resp, request)
return {'is_new': resp.body['isNewlyCreated']}
return self._execute(request, response_handler)
def transactions(self):
"""Return details on currently running WAL transactions.
Fields in the returned details are as follows:
.. code-block:: none
"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.
:return: Details on currently running WAL transactions.
:rtype: dict
:raise arango.exceptions.WALTransactionListError: If retrieval fails.
"""
request = Request(method='get', endpoint='/_admin/wal/transactions')
def response_handler(resp):
if resp.is_success:
return format_wal_transactions(resp.body)
raise WALTransactionListError(resp, request)
return self._execute(request, response_handler)
def commit(self, 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.
:param replace: Overwrite any existing service files in database.
:type replace: bool
:return: True if the state was committed successfully.
:rtype: bool
:raise arango.exceptions.FoxxCommitError: If commit fails.
"""
params = {}
if replace is not None:
params['replace'] = replace
request = Request(
method='post',
endpoint='/_api/foxx/commit',
params=params
)
def response_handler(resp):
if not resp.is_success:
raise FoxxCommitError(resp, request)
return True
return self._execute(request, response_handler)
def configure(self, mode=None, limit=None):
"""Configure the query cache properties.
:param mode: Operation mode. Allowed values are "off", "on" and
"demand".
:type mode: str | unicode
:param limit: Max number of query results to be stored.
:type limit: int
:return: Query cache properties.
:rtype: dict
:raise arango.exceptions.AQLCacheConfigureError: If operation fails.
"""
data = {}
if mode is not None:
data['mode'] = mode
if limit is not None:
data['maxResults'] = limit
request = Request(method='put',
endpoint='/_api/query-cache/properties',
data=data)
def response_handler(resp):
if not resp.is_success:
raise AQLCacheConfigureError(resp, request)
return {
'mode': resp.body['mode'],
'limit': resp.body['maxResults']
}
return self._execute(request, response_handler)
def delete_edge_definition(self,
name: str,
purge: bool = False) -> Result[bool]:
"""Delete an edge definition from the graph.
:param name: Edge collection name.
:type name: str
:param purge: 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.
:type purge: bool
:return: True if edge definition was deleted successfully.
:rtype: bool
:raise arango.exceptions.EdgeDefinitionDeleteError: If delete fails.
"""
request = Request(
method="delete",
endpoint=f"/_api/gharial/{self._name}/edge/{name}",
params={"dropCollections": purge},
)
def response_handler(resp: Response) -> bool:
if resp.is_success:
return True
raise EdgeDefinitionDeleteError(resp, request)
return self._execute(request, response_handler)
def job(self, job_id):
"""Return the details of a Pregel job.
:param job_id: Pregel job ID.
:type job_id: int
:return: Details of the Pregel job.
:rtype: dict
:raise arango.exceptions.PregelJobGetError: If retrieval fails.
"""
request = Request(method='get',
endpoint='/_api/control_pregel/{}'.format(job_id))
def response_handler(resp):
if not resp.is_success:
raise PregelJobGetError(resp, request)
if 'receivedCount' in resp.body:
resp.body['received_count'] = resp.body.pop('receivedCount')
if 'sendCount' in resp.body:
resp.body['send_count'] = resp.body.pop('sendCount')
if 'totalRuntime' in resp.body:
resp.body['total_runtime'] = resp.body.pop('totalRuntime')
if 'edgeCount' in resp.body: # pragma: no cover
resp.body['edge_count'] = resp.body.pop('edgeCount')
if 'vertexCount' in resp.body: # pragma: no cover
resp.body['vertex_count'] = resp.body.pop('vertexCount')
return resp.body
return self._execute(request, response_handler)
def delete_vertex_collection(self,
name: str,
purge: bool = False) -> Result[bool]:
"""Remove a vertex collection from the graph.
:param name: Vertex collection name.
:type name: str
:param purge: If set to True, the vertex collection is not just deleted
from the graph but also from the database completely.
:type purge: bool
:return: True if vertex collection was deleted successfully.
:rtype: bool
:raise arango.exceptions.VertexCollectionDeleteError: If delete fails.
"""
request = Request(
method="delete",
endpoint=f"/_api/gharial/{self._name}/vertex/{name}",
params={"dropCollection": purge},
)
def response_handler(resp: Response) -> bool:
if resp.is_success:
return True
raise VertexCollectionDeleteError(resp, request)
return self._execute(request, response_handler)
def replace_edge_definition(
self,
edge_collection: str,
from_vertex_collections: Sequence[str],
to_vertex_collections: Sequence[str],
) -> Result[EdgeCollection]:
"""Replace an edge definition.
:param edge_collection: Edge collection name.
:type edge_collection: str
:param from_vertex_collections: Names of "from" vertex collections.
:type from_vertex_collections: [str]
:param to_vertex_collections: Names of "to" vertex collections.
:type to_vertex_collections: [str]
:return: Edge collection API wrapper.
:rtype: arango.collection.EdgeCollection
:raise arango.exceptions.EdgeDefinitionReplaceError: If replace fails.
"""
request = Request(
method="put",
endpoint=f"/_api/gharial/{self._name}/edge/{edge_collection}",
data={
"collection": edge_collection,
"from": from_vertex_collections,
"to": to_vertex_collections,
},
)
def response_handler(resp: Response) -> EdgeCollection:
if resp.is_success:
return self.edge_collection(edge_collection)
raise EdgeDefinitionReplaceError(resp, request)
return self._execute(request, response_handler)
def start_applier(self, last_tick: Optional[str] = None) -> Result[Json]:
"""Start the replication applier.
:param last_tick: The remote last log tick value from which to start
applying replication. If not specified, the last saved tick from
the previous applier run is used. If there is no previous applier
state saved, the applier starts at the beginning of the logger
server's log.
:type last_tick: str
:return: Applier state and details.
:rtype: dict
:raise arango.exceptions.ReplicationApplierStartError: If operation fails.
"""
request = Request(
method="put",
endpoint="/_api/replication/applier-start",
params={} if last_tick is None else {"from": last_tick},
)
def response_handler(resp: Response) -> Json:
if resp.is_success:
return format_replication_applier_state(resp.body)
raise ReplicationApplierStartError(resp, request)
return self._execute(request, response_handler)
def replace_edge_definition(self, name, from_collections, to_collections):
"""Replace an edge definition in the graph.
:param name: the name of the edge definition to replace
:type name: str
:param from_collections: the names of the "from" vertex collections
:type from_collections: list
:param to_collections: the names of the "to" vertex collections
:type to_collections: list
:returns: whether the operation was successful
:rtype: bool
:raises arango.exceptions.EdgeDefinitionReplaceError: if the edge
definition cannot be replaced
"""
request = Request(method='put',
endpoint='/_api/gharial/{}/edge/{}'.format(
self._name, name),
data={
'collection': name,
'from': from_collections,
'to': to_collections
})
def handler(res):
if res.status_code not in HTTP_OK:
raise EdgeDefinitionReplaceError(res)
return not res.body['error']
return request, handler
def create_edge_definition(self, name, from_collections, to_collections):
"""Create a new edge definition for the graph.
An edge definition consists of an edge collection, one or more "from"
vertex collections, one or more "to" vertex collections.
:param name: the name of the new edge collection
:type name: str
:param from_collections: the name(s) of the "from" vertex collections
:type from_collections: list
:param to_collections: the names of the "to" vertex collections
:type to_collections: list
:returns: the edge collection object
:rtype: arango.collections.edge.EdgeCollection
:raises arango.exceptions.EdgeDefinitionCreateError: if the edge
definition cannot be created
"""
request = Request(method='post',
endpoint='/_api/gharial/{}/edge'.format(self._name),
data={
'collection': name,
'from': from_collections,
'to': to_collections
})
def handler(res):
if res.status_code not in HTTP_OK:
raise EdgeDefinitionCreateError(res)
return EdgeCollection(self._conn, self._name, name)
return request, handler
def enable_development(self, 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.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:return: Service metadata.
:rtype: dict
:raise arango.exceptions.FoxxDevModeEnableError: If operation fails.
"""
request = Request(
method='post',
endpoint='/_api/foxx/development',
params={'mount': mount},
)
def response_handler(resp):
if not resp.is_success:
raise FoxxDevModeEnableError(resp, request)
return resp.body
return self._execute(request, response_handler)
def cancel(self, ignore_missing: bool = False) -> bool:
"""Cancel the async job.
An async job cannot be cancelled once it is taken out of the queue.
:param ignore_missing: Do not raise an exception on missing job.
:type ignore_missing: bool
:return: True if job was cancelled successfully, False if the job
was not found but **ignore_missing** was set to True.
:rtype: bool
:raise arango.exceptions.AsyncJobCancelError: If cancel fails.
"""
request = Request(method="put",
endpoint=f"/_api/job/{self._id}/cancel")
resp = self._conn.send_request(request)
if resp.status_code == 200:
return True
elif resp.error_code == 404:
if ignore_missing:
return False
error_message = f"job {self._id} not found"
raise AsyncJobCancelError(resp, request, error_message)
else:
raise AsyncJobCancelError(resp, request)
def download(self, 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.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:return: Service bundle in raw string form.
:rtype: str
:raise arango.exceptions.FoxxDownloadError: If download fails.
"""
request = Request(
method='post',
endpoint='/_api/foxx/download',
params={'mount': mount}
)
def response_handler(resp):
if not resp.is_success:
raise FoxxDownloadError(resp, request)
return resp.body
return self._execute(request, response_handler)
def result(self) -> T:
"""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.
:return: Async job result.
:raise arango.exceptions.ArangoError: If the job raised an exception.
:raise arango.exceptions.AsyncJobResultError: If retrieval fails.
"""
request = Request(method="put", endpoint=f"/_api/job/{self._id}")
resp = self._conn.send_request(request)
if "X-Arango-Async-Id" in resp.headers or "x-arango-async-id" in resp.headers:
return self._response_handler(resp)
if resp.status_code == 204:
error_message = f"job {self._id} not done"
raise AsyncJobResultError(resp, request, error_message)
elif resp.error_code == 404:
error_message = f"job {self._id} not found"
raise AsyncJobResultError(resp, request, error_message)
else:
raise AsyncJobResultError(resp, request)
def run_script(self, mount, name, arg=None):
"""Run a service script.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:param name: Script name.
:type name: str
:param arg: Arbitrary value passed into the script as first argument.
:type arg: str | bool | int | list | dict
:return: Result of the script, if any.
:rtype: dict
:raise arango.exceptions.FoxxScriptRunError: If script fails.
"""
request = Request(
method='post',
endpoint='/_api/foxx/scripts/{}'.format(name),
params={'mount': mount},
data=arg or {}
)
def response_handler(resp):
if not resp.is_success:
raise FoxxScriptRunError(resp, request)
return resp.body
return self._execute(request, response_handler)
def result(self):
"""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.
:return: Async job result.
:rtype: str | unicode | bool | int | list | dict
:raise arango.exceptions.ArangoError: If the job raised an exception.
:raise arango.exceptions.AsyncJobResultError: If retrieval fails.
"""
request = Request(method='put',
endpoint='/_api/job/{}'.format(self._id))
resp = self._conn.send_request(request)
headers = resp.headers
if 'X-Arango-Async-Id' in headers or 'x-arango-async-id' in headers:
return self._response_handler(resp)
if resp.status_code == 204:
error_message = 'job {} not done'.format(self._id)
raise AsyncJobResultError(resp, request, error_message)
elif resp.error_code == 404:
error_message = 'job {} not found'.format(self._id)
raise AsyncJobResultError(resp, request, error_message)
else:
raise AsyncJobResultError(resp, request)
def functions(self):
"""List the AQL functions defined in the database.
:return: AQL functions.
:rtype: [dict]
:raise arango.exceptions.AQLFunctionListError: If retrieval fails.
"""
request = Request(method='get', endpoint='/_api/aqlfunction')
def response_handler(resp):
if not resp.is_success:
raise AQLFunctionListError(resp, request)
body = resp.body or {}
if 'result' not in body: # pragma: no cover
return []
for item in body['result']:
if 'isDeterministic' in item:
item['is_deterministic'] = item.pop('isDeterministic')
return body['result']
return self._execute(request, response_handler)
def status(self):
"""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.
:return: 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).
:rtype: str | unicode
:raise arango.exceptions.AsyncJobStatusError: If retrieval fails.
"""
request = Request(method='get',
endpoint='/_api/job/{}'.format(self._id))
resp = self._conn.send_request(request)
if resp.status_code == 204:
return 'pending'
elif resp.is_success:
return 'done'
elif resp.error_code == 404:
error_message = 'job {} not found'.format(self._id)
raise AsyncJobStatusError(resp, request, error_message)
else:
raise AsyncJobStatusError(resp, request)
def delete_function(self, name, group=False, ignore_missing=False):
"""Delete an AQL function.
:param name: AQL function name.
:type name: str | unicode
:param group: 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.
:type group: bool
:param ignore_missing: Do not raise an exception on missing function.
:type ignore_missing: bool
:return: Number of AQL functions deleted if operation was successful,
False if function(s) was not found and **ignore_missing** was set
to True.
:rtype: dict | bool
:raise arango.exceptions.AQLFunctionDeleteError: If delete fails.
"""
request = Request(method='delete',
endpoint='/_api/aqlfunction/{}'.format(name),
params={'group': group})
def response_handler(resp):
if resp.error_code == 1582 and ignore_missing:
return False
if not resp.is_success:
raise AQLFunctionDeleteError(resp, request)
return {'deleted': resp.body['deletedCount']}
return self._execute(request, response_handler)
def service(self, mount):
"""Return service metadata.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:return: Service metadata.
:rtype: dict
:raise arango.exceptions.FoxxServiceGetError: If retrieval fails.
"""
request = Request(
method='get',
endpoint='/_api/foxx/service',
params={'mount': mount}
)
def response_handler(resp):
if not resp.is_success:
raise FoxxServiceGetError(resp, request)
if 'manifest' in resp.body:
mf = resp.body['manifest']
if 'defaultDocument' in mf:
mf['default_document'] = mf.pop('defaultDocument')
return resp.body
return self._execute(request, response_handler)
def cluster_inventory(self, include_system=None):
"""Return an overview of collections and indexes in a cluster.
:param include_system: Include system collections in the result.
Default value is True.
:type include_system: bool
:return: Overview of collections and indexes on the cluster.
:rtype: dict
:raise arango.exceptions.ReplicationClusterInventoryError: If retrieval
fails.
"""
params = {}
if include_system is not None:
params['includeSystem'] = include_system
request = Request(method='get',
endpoint='/_api/replication/clusterInventory',
params=params)
def response_handler(resp):
if resp.is_success: # pragma: no cover
return format_replication_inventory(resp.body)
raise ReplicationClusterInventoryError(resp, request)
return self._execute(request, response_handler)
def delete_service(self, mount, teardown=None):
"""Uninstall a service.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:param teardown: Run service teardown script.
:type teardown: bool
:return: True if service was deleted successfully.
:rtype: bool
:raise arango.exceptions.FoxxServiceDeleteError: If delete fails.
"""
params = {'mount': mount}
if teardown is not None:
params['teardown'] = teardown
request = Request(
method='delete',
endpoint='/_api/foxx/service',
params=params
)
def response_handler(resp):
if not resp.is_success:
raise FoxxServiceDeleteError(resp, request)
return True
return self._execute(request, response_handler)
def replace_edge_definition(self, edge_collection, from_vertex_collections,
to_vertex_collections):
"""Replace an edge definition.
:param edge_collection: Edge collection name.
:type edge_collection: str | unicode
:param from_vertex_collections: Names of "from" vertex collections.
:type from_vertex_collections: [str | unicode]
:param to_vertex_collections: Names of "to" vertex collections.
:type to_vertex_collections: [str | unicode]
:return: True if edge definition was replaced successfully.
:rtype: bool
:raise arango.exceptions.EdgeDefinitionReplaceError: If replace fails.
"""
request = Request(method='put',
endpoint='/_api/gharial/{}/edge/{}'.format(
self._name, edge_collection),
data={
'collection': edge_collection,
'from': from_vertex_collections,
'to': to_vertex_collections
})
def response_handler(resp):
if not resp.is_success:
raise EdgeDefinitionReplaceError(resp, request)
return self.edge_collection(edge_collection)
return self._execute(request, response_handler)
def replace_config(self, mount, config):
"""Replace service configuration.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:param config: Configuration values. Omitted options are reset to their
default values or marked as un-configured.
:type config: dict
:return: Replaced configuration values.
:rtype: dict
:raise arango.exceptions.FoxxConfigReplaceError: If replace fails.
"""
request = Request(
method='put',
endpoint='/_api/foxx/configuration',
params={'mount': mount},
data=config
)
def response_handler(resp):
if not resp.is_success:
raise FoxxConfigReplaceError(resp, request)
return resp.body
return self._execute(request, response_handler)
def insert(self, document, sync=None):
"""Insert a new document into the edge collection.
If the ``"_key"`` field is present in **document**, its value is used
as the key of the new document. Otherwise, the key is auto-generated.
The **document** must contain the fields ``"_from"`` and ``"_to"``.
:param document: the document body
:type document: dict
:param sync: wait for the operation to sync to disk
:type sync: bool | None
:returns: the ID, revision and key of the new document
:rtype: dict
:raises arango.exceptions.DocumentInsertError: if the document cannot
be inserted into the collection
"""
params = {}
if sync is not None:
params['waitForSync'] = sync
request = Request(method='post',
endpoint="/_api/gharial/{}/edge/{}".format(
self._graph_name, self._name),
data=document,
params=params)
def handler(res):
if res.status_code not in HTTP_OK:
raise DocumentInsertError(res)
return res.body["edge"]
return request, handler
def run_script(self,
mount: str,
name: str,
arg: Any = None) -> Result[Any]:
"""Run a service script.
:param mount: Service mount path (e.g "/_admin/aardvark").
:type mount: str
:param name: Script name.
:type name: str
:param arg: Arbitrary value passed into the script as first argument.
:type arg: Any
:return: Result of the script, if any.
:rtype: Any
:raise arango.exceptions.FoxxScriptRunError: If script fails.
"""
request = Request(
method="post",
endpoint=f"/_api/foxx/scripts/{name}",
params={"mount": mount},
data=arg,
)
def response_handler(resp: Response) -> Any:
if resp.is_success:
return resp.body
raise FoxxScriptRunError(resp, request)
return self._execute(request, response_handler)
