diff --git a/README.md b/README.md index 9e124b6..dc7b1ca 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ Python driver for [ArangoDB](https://www.arangodb.com), a scalable multi-model database natively supporting documents, graphs and search. -This is the _asyncio_ alternative of the officially supported [python-arango](https://github.com/arangodb/python-arango) +This is the _asyncio_ alternative of the [python-arango](https://github.com/arangodb/python-arango) driver. **Note: This project is still in active development, features might be added or removed.** diff --git a/docs/aql.rst b/docs/aql.rst index 914c982..c5cc69b 100644 --- a/docs/aql.rst +++ b/docs/aql.rst @@ -8,3 +8,155 @@ operations such as creating or deleting :doc:`databases `, information, refer to `ArangoDB manual`_. .. _ArangoDB manual: https://docs.arangodb.com + +AQL Queries +=========== + +AQL queries are invoked from AQL API wrapper. Executing queries returns +:doc:`result cursors `. + +**Example:** + +.. code-block:: python + + from arangoasync import ArangoClient, AQLQueryKillError + from arangoasync.auth import Auth + + # 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) + + # Get the API wrapper for "students" collection. + students = db.collection("students") + + # Insert some test documents into "students" collection. + await students.insert_many([ + {"_key": "Abby", "age": 22}, + {"_key": "John", "age": 18}, + {"_key": "Mary", "age": 21} + ]) + + # Get the AQL API wrapper. + aql = db.aql + + # Retrieve the execution plan without running the query. + plan = await aql.explain("FOR doc IN students RETURN doc") + + # Validate the query without executing it. + validate = await aql.validate("FOR doc IN students RETURN doc") + + # Execute the query + cursor = await db.aql.execute( + "FOR doc IN students FILTER doc.age < @value RETURN doc", + bind_vars={"value": 19} + ) + + # Iterate through the result cursor + student_keys = [] + async for doc in cursor: + student_keys.append(doc) + + # List currently running queries. + queries = await aql.queries() + + # List any slow queries. + slow_queries = await aql.slow_queries() + + # Clear slow AQL queries if any. + await aql.clear_slow_queries() + + # Retrieve AQL query tracking properties. + await aql.tracking() + + # Configure AQL query tracking properties. + await aql.set_tracking( + max_slow_queries=10, + track_bind_vars=True, + track_slow_queries=True + ) + + # Kill a running query (this should fail due to invalid ID). + try: + await aql.kill("some_query_id") + except AQLQueryKillError as err: + assert err.http_code == 404 + +See :class:`arangoasync.aql.AQL` for API specification. + + +AQL User Functions +================== + +**AQL User Functions** are custom functions you define in Javascript to extend +AQL functionality. They are somewhat similar to SQL procedures. + +**Example:** + +.. code-block:: python + + from arangoasync import ArangoClient + from arangoasync.auth import Auth + + # 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) + + # Get the AQL API wrapper. + aql = db.aql + + # Create a new AQL user function. + await aql.create_function( + # Grouping by name prefix is supported. + name="functions::temperature::converter", + code="function (celsius) { return celsius * 1.8 + 32; }" + ) + + # List AQL user functions. + functions = await aql.functions() + + # Delete an existing AQL user function. + await aql.delete_function("functions::temperature::converter") + +See :class:`arangoasync.aql.AQL` for API specification. + + +AQL Query Cache +=============== + +**AQL Query Cache** is used to minimize redundant calculation of the same query +results. It is useful when read queries are issued frequently and write queries +are not. + +**Example:** + +.. code-block:: python + + from arangoasync import ArangoClient + from arangoasync.auth import Auth + + # 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) + + # Get the AQL API wrapper. + aql = db.aql + + # Retrieve AQL query cache properties. + await aql.cache.properties() + + # Configure AQL query cache properties + await aql.cache.configure(mode="demand", max_results=10000) + + # Clear results in AQL query cache. + await aql.cache.clear() + +See :class:`arangoasync.aql.AQLQueryCache` for API specification. diff --git a/docs/cursor.rst b/docs/cursor.rst new file mode 100644 index 0000000..8b746c6 --- /dev/null +++ b/docs/cursor.rst @@ -0,0 +1,8 @@ +Cursors +------- + +Many operations provided by python-arango-async (e.g. executing :doc:`aql` queries) +return result **cursors** to batch the network communication between ArangoDB +server and python-arango-async client. Each HTTP request from a cursor fetches the +next batch of results (usually documents). Depending on the query, the total +number of items in the result set may or may not be known in advance. diff --git a/docs/errors.rst b/docs/errors.rst index cba6d92..855b152 100644 --- a/docs/errors.rst +++ b/docs/errors.rst @@ -16,5 +16,18 @@ Client Errors ============= :class:`arangoasync.exceptions.ArangoClientError` exceptions originate from -python-arango client itself. They do not contain error codes nor HTTP request +python-arango-async client itself. They do not contain error codes nor HTTP request response details. + +**Example** + +.. code-block:: python + + from arangoasync.exceptions import ArangoClientError, ArangoServerError + + try: + # Some operation that raises an error + except ArangoClientError: + # An error occurred on the client side + except ArangoServerError: + # An error occurred on the server side diff --git a/docs/index.rst b/docs/index.rst index 9e71989..76e8a44 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -63,6 +63,7 @@ Miscellaneous .. toctree:: :maxdepth: 1 + cursor errors errno