def execute_query(self,
query,
count=False,
batch_size=None,
ttl=None,
bind_vars=None,
full_count=None,
max_plans=None,
optimizer_rules=None):
"""Execute the AQL query and return the result.
For more information on ``full_count`` please refer to:
https://docs.arangodb.com/HttpAqlQueryCursor/AccessingCursors.html
:param query: the AQL query to execute
:type query: str
:param count: whether or not the document count should be returned
:type count: bool
:param batch_size: maximum number of documents in one round trip
:type batch_size: int
:param ttl: time-to-live for the cursor (in seconds)
:type ttl: int
:param bind_vars: key-value pairs of bind parameters
:type bind_vars: dict
:param full_count: whether or not to include count before last LIMIT
:param max_plans: maximum number of plans the optimizer generates
:type max_plans: None or int
:param optimizer_rules: list of optimizer rules
:type optimizer_rules: list
:returns: the cursor from executing the query
:raises: AQLQueryExecuteError, CursorDeleteError
"""
options = {}
if full_count is not None:
options["fullCount"] = full_count
if max_plans is not None:
options["maxNumberOfPlans"] = max_plans
if optimizer_rules is not None:
options["optimizer"] = {"rules": optimizer_rules}
data = {
"query": query,
"count": count,
}
if batch_size is not None:
data["batchSize"] = batch_size
if ttl is not None:
data["ttl"] = ttl
if bind_vars is not None:
data["bindVars"] = bind_vars
if options:
data["options"] = options
res = self.api.post("/_api/cursor", data=data)
if res.status_code not in HTTP_OK:
raise AQLQueryExecuteError(res)
return cursor(self.api, res)
def near(self,
latitude,
longitude,
distance=None,
radius=None,
skip=None,
limit=None,
geo=None):
"""Return all the documents near the given coordinate.
By default number of documents returned is 100. The returned list is
sorted based on the distance, with the nearest document being the first
in the list. Documents of equal distance are ordered randomly.
In order to execute this query a geo index must be defined for the
collection. If there are more than one geo-spatial index, the ``geo``
argument can be used to select a particular index.
if ``distance`` is given, return the distance (in meters) to the
coordinate in a new attribute whose key is the value of the argument.
:param latitude: the latitude of the coordinate
:type latitude: int
:param longitude: the longitude of the coordinate
:type longitude: int
:param distance: return the distance to the coordinate in this key
:type distance: str
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:param geo: the identifier of the geo-index to use
:type geo: str
:returns: the list of documents that are near the coordinate
:rtype: list
:raises: SimpleQueryNearError
"""
data = {
"collection": self.name,
"latitude": latitude,
"longitude": longitude
}
if distance is not None:
data["distance"] = distance
if radius is not None:
data["radius"] = radius
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
if geo is not None:
data["geo"] = geo
res = self.api.put("/_api/simple/near", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryNearError(res)
return cursor(self.api, res)
def within(self,
latitude,
longitude,
radius,
distance=None,
skip=None,
limit=None,
geo=None):
"""Return all documents within the radius around the coordinate.
The returned list is sorted by distance from the coordinate. In order
to execute this query a geo index must be defined for the collection.
If there are more than one geo-spatial index, the ``geo`` argument can
be used to select a particular index.
if ``distance`` is given, return the distance (in meters) to the
coordinate in a new attribute whose key is the value of the argument.
:param latitude: the latitude of the coordinate
:type latitude: int
:param longitude: the longitude of the coordinate
:type longitude: int
:param radius: the maximum radius (in meters)
:type radius: int
:param distance: return the distance to the coordinate in this key
:type distance: str
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:param geo: the identifier of the geo-index to use
:type geo: str
:returns: the list of documents are within the radius
:rtype: list
:raises: SimpleQueryWithinError
"""
data = {
"collection": self.name,
"latitude": latitude,
"longitude": longitude,
"radius": radius
}
if distance is not None:
data["distance"] = distance
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
if geo is not None:
data["geo"] = geo
res = self.api.put("/_api/simple/within", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryWithinError(res)
return cursor(self.api, res)
def near(self, latitude, longitude, distance=None, radius=None, skip=None,
limit=None, geo=None):
"""Return all the documents near the given coordinate.
By default number of documents returned is 100. The returned list is
sorted based on the distance, with the nearest document being the first
in the list. Documents of equal distance are ordered randomly.
In order to execute this query a geo index must be defined for the
collection. If there are more than one geo-spatial index, the ``geo``
argument can be used to select a particular index.
if ``distance`` is given, return the distance (in meters) to the
coordinate in a new attribute whose key is the value of the argument.
:param latitude: the latitude of the coordinate
:type latitude: int
:param longitude: the longitude of the coordinate
:type longitude: int
:param distance: return the distance to the coordinate in this key
:type distance: str
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:param geo: the identifier of the geo-index to use
:type geo: str
:returns: the list of documents that are near the coordinate
:rtype: list
:raises: SimpleQueryNearError
"""
data = {
"collection": self.name,
"latitude": latitude,
"longitude": longitude
}
if distance is not None:
data["distance"] = distance
if radius is not None:
data["radius"] = radius
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
if geo is not None:
data["geo"] = geo
res = self.api.put("/_api/simple/near", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryNearError(res)
return cursor(self.api, res)
def execute_query(self, query, count=False, batch_size=None, ttl=None,
bind_vars=None, full_count=None, max_plans=None,
optimizer_rules=None):
"""Execute the AQL query and return the result.
For more information on ``full_count`` please refer to:
https://docs.arangodb.com/HttpAqlQueryCursor/AccessingCursors.html
:param query: the AQL query to execute
:type query: str
:param count: whether or not the document count should be returned
:type count: bool
:param batch_size: maximum number of documents in one round trip
:type batch_size: int
:param ttl: time-to-live for the cursor (in seconds)
:type ttl: int
:param bind_vars: key-value pairs of bind parameters
:type bind_vars: dict
:param full_count: whether or not to include count before last LIMIT
:param max_plans: maximum number of plans the optimizer generates
:type max_plans: None or int
:param optimizer_rules: list of optimizer rules
:type optimizer_rules: list
:returns: the cursor from executing the query
:raises: AQLQueryExecuteError, CursorDeleteError
"""
options = {}
if full_count is not None:
options["fullCount"] = full_count
if max_plans is not None:
options["maxNumberOfPlans"] = max_plans
if optimizer_rules is not None:
options["optimizer"] = {"rules": optimizer_rules}
data = {
"query": query,
"count": count,
}
if batch_size is not None:
data["batchSize"] = batch_size
if ttl is not None:
data["ttl"] = ttl
if bind_vars is not None:
data["bindVars"] = bind_vars
if options:
data["options"] = options
res = self.api.post("/_api/cursor", data=data)
if res.status_code not in HTTP_OK:
raise AQLQueryExecuteError(res)
return cursor(self.api, res)
def export_documents(self,
flush=None,
flush_wait=None,
count=None,
batch_size=None,
limit=None,
ttl=None,
restrict=None):
""""Export all documents from this collection using a cursor.
:param flush: trigger a WAL flush operation prior to the export
:type flush: bool or None
:param flush_wait: the max wait time in sec for flush operation
:type flush_wait: int or None
:param count: whether the count is returned in an attribute of result
:type count: bool or None
:param batch_size: the max number of result documents in one roundtrip
:type batch_size: int or None
:param limit: the max number of documents to be included in the cursor
:type limit: int or None
:param ttl: time-to-live for the cursor on the server
:type ttl: int or None
:param restrict: object with attributes to be excluded/included
:type restrict: dict
:return: the generator of documents in this collection
:rtype: generator
:raises: DocumentsExportError
"""
params = {"collection": self.name}
options = {}
if flush is not None:
options["flush"] = flush
if flush_wait is not None:
options["flushWait"] = flush_wait
if count is not None:
options["count"] = count
if batch_size is not None:
options["batchSize"] = batch_size
if limit is not None:
options["limit"] = limit
if ttl is not None:
options["ttl"] = ttl
if restrict is not None:
options["restrict"] = restrict
data = {"options": options} if options else {}
res = self.api.post("/_api/export", params=params, data=data)
if res.status_code not in HTTP_OK:
raise DocumentsExportError(res)
return cursor(self.api, res)
def within(self, latitude, longitude, radius, distance=None, skip=None,
limit=None, geo=None):
"""Return all documents within the radius around the coordinate.
The returned list is sorted by distance from the coordinate. In order
to execute this query a geo index must be defined for the collection.
If there are more than one geo-spatial index, the ``geo`` argument can
be used to select a particular index.
if ``distance`` is given, return the distance (in meters) to the
coordinate in a new attribute whose key is the value of the argument.
:param latitude: the latitude of the coordinate
:type latitude: int
:param longitude: the longitude of the coordinate
:type longitude: int
:param radius: the maximum radius (in meters)
:type radius: int
:param distance: return the distance to the coordinate in this key
:type distance: str
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:param geo: the identifier of the geo-index to use
:type geo: str
:returns: the list of documents are within the radius
:rtype: list
:raises: SimpleQueryWithinError
"""
data = {
"collection": self.name,
"latitude": latitude,
"longitude": longitude,
"radius": radius
}
if distance is not None:
data["distance"] = distance
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
if geo is not None:
data["geo"] = geo
res = self.api.put("/_api/simple/within", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryWithinError(res)
return cursor(self.api, res)
def export_documents(self, flush=None, flush_wait=None, count=None,
batch_size=None, limit=None, ttl=None, restrict=None):
""""Export all documents from this collection using a cursor.
:param flush: trigger a WAL flush operation prior to the export
:type flush: bool or None
:param flush_wait: the max wait time in sec for flush operation
:type flush_wait: int or None
:param count: whether the count is returned in an attribute of result
:type count: bool or None
:param batch_size: the max number of result documents in one roundtrip
:type batch_size: int or None
:param limit: the max number of documents to be included in the cursor
:type limit: int or None
:param ttl: time-to-live for the cursor on the server
:type ttl: int or None
:param restrict: object with attributes to be excluded/included
:type restrict: dict
:return: the generator of documents in this collection
:rtype: generator
:raises: DocumentsExportError
"""
params = {"collection": self.name}
options = {}
if flush is not None:
options["flush"] = flush
if flush_wait is not None:
options["flushWait"] = flush_wait
if count is not None:
options["count"] = count
if batch_size is not None:
options["batchSize"] = batch_size
if limit is not None:
options["limit"] = limit
if ttl is not None:
options["ttl"] = ttl
if restrict is not None:
options["restrict"] = restrict
data = {"options": options} if options else {}
res = self.api.post("/_api/export", params=params, data=data)
if res.status_code not in HTTP_OK:
raise DocumentsExportError(res)
return cursor(self.api, res)
def range(self,
attribute,
left,
right,
closed=True,
skip=None,
limit=None):
"""Return all the documents within a given range.
In order to execute this query a skiplist index must be present on the
queried attribute.
:param attribute: the attribute path with a skip-list index
:type attribute: str
:param left: the lower bound
:type left: int
:param right: the upper bound
:type right: int
:param closed: whether or not to include left and right, or just left
:type closed: bool
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of documents
:rtype: list
:raises: SimpleQueryRangeError
"""
data = {
"collection": self.name,
"attribute": attribute,
"left": left,
"right": right,
"closed": closed
}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
res = self.api.put("/_api/simple/range", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryRangeError(res)
return cursor(self.api, res)
def all(self, skip=None, limit=None):
"""Return all documents in this collection.
``skip`` is applied before ``limit`` if both are provided.
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of all documents
:rtype: list
:raises: SimpleQueryAllError
"""
data = {"collection": self.name}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
res = self.api.put("/_api/simple/all", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryAllError(res)
return cursor(self.api, res)
def all(self, skip=None, limit=None):
"""Return all documents in this collection.
``skip`` is applied before ``limit`` if both are provided.
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of all documents
:rtype: list
:raises: SimpleQueryAllError
"""
data = {"collection": self.name}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
res = self.api.put("/_api/simple/all", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryAllError(res)
return cursor(self.api, res)
def range(self, attribute, left, right, closed=True, skip=None,
limit=None):
"""Return all the documents within a given range.
In order to execute this query a skiplist index must be present on the
queried attribute.
:param attribute: the attribute path with a skip-list index
:type attribute: str
:param left: the lower bound
:type left: int
:param right: the upper bound
:type right: int
:param closed: whether or not to include left and right, or just left
:type closed: bool
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of documents
:rtype: list
:raises: SimpleQueryRangeError
"""
data = {
"collection": self.name,
"attribute": attribute,
"left": left,
"right": right,
"closed": closed
}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
res = self.api.put("/_api/simple/range", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryRangeError(res)
return cursor(self.api, res)
def fulltext(self, attribute, query, skip=None, limit=None, index=None):
"""Return all documents that match the specified fulltext ``query``.
In order to execute this query a fulltext index must be defined for the
collection and the specified attribute.
For more information on fulltext queries please refer to:
https://docs.arangodb.com/SimpleQueries/FulltextQueries.html
:param attribute: the attribute path with a fulltext index
:type attribute: str
:param query: the fulltext query
:type query: str
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of documents
:rtype: list
:raises: SimpleQueryFullTextError
"""
data = {
"collection": self.name,
"attribute": attribute,
"query": query,
}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
if index is not None:
data["index"] = index
res = self.api.put("/_api/simple/fulltext", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryFullTextError(res)
return cursor(self.api, res)
def get_by_example(self, example, skip=None, limit=None):
"""Return all documents matching the given example document body.
``skip`` is applied before ``limit`` if both are provided.
:param example: the example document body
:type example: dict
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of matching documents
:rtype: list
:raises: SimpleQueryGetByExampleError
"""
data = {"collection": self.name, "example": example}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
res = self.api.put("/_api/simple/by-example", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryGetByExampleError(res)
return cursor(self.api, res)
def fulltext(self, attribute, query, skip=None, limit=None, index=None):
"""Return all documents that match the specified fulltext ``query``.
In order to execute this query a fulltext index must be defined for the
collection and the specified attribute.
For more information on fulltext queries please refer to:
https://docs.arangodb.com/SimpleQueries/FulltextQueries.html
:param attribute: the attribute path with a fulltext index
:type attribute: str
:param query: the fulltext query
:type query: str
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of documents
:rtype: list
:raises: SimpleQueryFullTextError
"""
data = {
"collection": self.name,
"attribute": attribute,
"query": query,
}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
if index is not None:
data["index"] = index
res = self.api.put("/_api/simple/fulltext", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryFullTextError(res)
return cursor(self.api, res)
def get_by_example(self, example, skip=None, limit=None):
"""Return all documents matching the given example document body.
``skip`` is applied before ``limit`` if both are provided.
:param example: the example document body
:type example: dict
:param skip: the number of documents to skip
:type skip: int
:param limit: maximum number of documents to return
:type limit: int
:returns: the list of matching documents
:rtype: list
:raises: SimpleQueryGetByExampleError
"""
data = {"collection": self.name, "example": example}
if skip is not None:
data["skip"] = skip
if limit is not None:
data["limit"] = limit
res = self.api.put("/_api/simple/by-example", data=data)
if res.status_code not in HTTP_OK:
raise SimpleQueryGetByExampleError(res)
return cursor(self.api, res)
