The async executor
You need this page if you want to hand statements to the engine and carry on, and learn about the result in a callback. For async def code that awaits each call, use AsyncDatabase instead: see asyncio: AsyncDatabase. The short version:
-
executor = db.async_executor()returns a wrapper of the one executor of the database. Every call returns another wrapper of the same executor, with the same settings. -
executor.command(…),executor.query(…)andexecutor.transaction(…)queue work and return at once.executor.wait_completion()blocks until everything queued before it is stored. -
A callback runs on a thread of the engine, not on yours.
-
executor.close()shuts the executor down for every caller. Do it once, at the end. -
Do not use it to load many rows. Use
db.insert_many(…)for documents anddb.graph_batch()for graphs: see Bulk loads and commit size.
The statements are SQL or openCypher, as on Databases and queries. The executor, its worker threads and its queue belong to the engine. This page covers what the Python wrappers add.
The blocks on this page run one after the other against one empty database, and a test in the repository runs them that way (tests/test_docs_async_page.py) on the JVM build and on the native build. Each block that prints something is followed by its output. Every block assumes that db is an open database. The last block closes the executor, so nothing can follow it.
Submit and wait
Each worker of the executor opens a transaction of its own and commits it after commit_every operations, and at wait_completion(). You open no transaction for it. At parallel level 1 there is one worker, and every statement of the next block is stored once wait_completion() returns.
db.command("sql", "CREATE DOCUMENT TYPE Item")
def count():
return db.query("sql", "SELECT count(*) AS c FROM Item").first().get("c")
executor = db.async_executor().set_parallel_level(1).set_commit_every(1000)
for n in range(50):
executor.command("sql", "INSERT INTO Item SET n = ?", args=[n])
executor.wait_completion()
print(count())
50
The setters return the executor, so they chain. wait_completion(timeout_ms) raises TimeoutError when the queue is not done in time, and wait_completion(0) raises it at once if work is left. A negative timeout raises ValueError. Returning from the wait does not make is_pending() False at the same instant: poll it until it is, if you need an idle executor.
try:
executor.wait_completion(-1)
except ValueError as error:
print(error)
timeout_ms must be None or >= 0, got -1
command takes the parameters as args=[…] for ?, or as named keywords, and not both: the call raises ValueError before it queues anything.
One executor for the database
The engine has one executor for each database. db.async_executor() does not make a new one: it returns a new wrapper of the same executor, and the settings (parallel level, commit size and flush type, among others) are the executor’s, not the wrapper’s.
other = db.async_executor()
print(other is executor, other.get_commit_every(), other.get_parallel_level())
False 1000 1
So a library that sets the commit size changes it for your code too. Set what you need right after you get the executor, and do not share an executor with code you do not control. The durability settings of the executor are on Durability settings.
Callbacks and errors
A result callback gets one row at a time. It runs on a thread of the engine, so it must be thread-safe, and anything it shares with your thread needs a lock or a queue.
import threading
me = threading.get_ident()
rows = []
on_my_thread = []
def on_row(row):
rows.append(row.get("n"))
on_my_thread.append(threading.get_ident() == me)
executor.query("sql", "SELECT n FROM Item WHERE n < 3 ORDER BY n", on_row)
executor.wait_completion()
print(rows, set(on_my_thread))
[0, 1, 2] {False}
A statement that fails does not raise in your thread. It goes to the error_callback of that call. A statement without one fails silently: wait_completion() returns normally and the statement stored nothing. Statements queued after a failed one still run.
errors = []
executor.command("sql", "INSERT INTO Missing SET n = 1", error_callback=errors.append)
executor.command("sql", "INSERT INTO Item SET n = 100")
executor.wait_completion()
print(len(errors), count())
executor.command("sql", "INSERT INTO Missing SET n = 1")
executor.wait_completion()
print("no error raised", count())
1 51
no error raised 51
Give every call whose result you need an error_callback. executor.on_error(callback) sets one handler for the whole executor, and executor.on_ok(callback) one that runs after each batch commit; see their docstrings for what each receives. A per-record callback of create_record runs when the record is applied to the batch, before the commit, and on_ok runs after it (tests/test_async_executor.py pins this order).
Native: create_record hands records over in batches
On the arcadedb (native) package, from 26.11.1.post4, the async executor collects the records that create_record receives for one type and kind, and hands up to 1,000 of them to the library at once as one columnar frame. Each record keeps its own callback and its own error callback. Before, every record was one call with one JSON text. A thread of the executor hands a batch over when its first record has waited 0.05 seconds, so a record is not held back when no other call reaches the executor. The first 128 records of an executor go one by one, as before, and so does a hand-over of fewer than 64 collected records, because a frame has a fixed cost that a handful of records does not repay. The arcadedb-jvm package does not change.
An executor that receives only about 100 records pays for the per-record counter that lets the first records run one callback each: an async create_record of 100 records reads 1.060 [1.055, 1.067] on the laptop and 1.050 [1.045, 1.052] on the mini, that is about 6 percent more time for executors of 100 records. Executors of 1,000 records or more are faster. A linger thread shared by the process, tracked in ArcadeData/arcadedb-python#406, would remove this cost.
The table is one study of the arcadedb (native) package on a laptop and on a second Linux machine, the mini: the time for each operation of the post4 wheel against the 26.11.1.post3 wheel. The ratio is the median of the pair ratios (below 1 means less time) with its 95% interval. Setup: Python 3.12, one fresh process for each run, two cores for the process, the two builds alternated in both orders (ABBA), the first round dropped, and an A/A control (the post3 wheel twice) whose median ratio was between 0.994 and 1.002 on the laptop and between 0.989 and 1.002 on the mini. The post4 wheels were built by CI from commit e83947e, the commit of the tag, and the post3 wheels were the ones that CI built from the post3 commit. The files on PyPI were checked for the same engine as 26.11.1 (see The engine of 26.11.1.post4) and were not timed again.
| What was timed | Ratio on the laptop, post4 over post3 (95% interval) | Ratio on the mini (95% interval) | Clean pairs (laptop, mini) |
|---|---|---|---|
async |
1.060 [1.055, 1.067] |
1.050 [1.045, 1.052] |
20, 16 |
async |
0.342 [0.339, 0.345] |
0.324 [0.322, 0.326] |
20, 16 |
async |
0.166 [0.164, 0.167] |
0.153 [0.150, 0.155] |
20, 16 |
async |
0.673 [0.668, 0.680] |
0.561 [0.556, 0.568] |
20, 16 |
async |
0.703 [0.700, 0.706] |
0.591 [0.583, 0.599] |
20, 16 |
async |
0.210 [0.209, 0.212] |
0.208 [0.206, 0.211] |
20, 16 |
The records that the batching holds before it hands them over use memory: up to 1,000 record copies at a time. Across the 172 figures of the whole post4 study the median of the peak resident size, post4 over post3, was 1.004, and the async figures that batch records used more (for example, a control figure of 1,000 records read 234 to 326 MiB on the mini).
Blocks in a transaction
executor.transaction(block) runs block on a worker inside a transaction: the engine begins it, commits it, and rolls it back when the block raises. Inside the block, use db as you do in your own thread. retries, ok_callback and error_callback are optional, and slot=n sends the block to the worker with that number. Blocks sent to the same slot run in the order you submitted them, and the tests pin no other order, so do not depend on the order of command calls.
executor.transaction(lambda: db.command("sql", "INSERT INTO Item SET n = 200"))
executor.wait_completion()
print(count())
52
Threads
Any thread can submit to one executor. Four threads that submit ten statements each, at parallel level 1, give forty rows:
def submit(worker):
for _ in range(10):
executor.command("sql", "INSERT INTO Item SET worker = ?", args=[worker])
threads = [threading.Thread(target=submit, args=(w,)) for w in range(4)]
for thread in threads:
thread.start()
for thread in threads:
thread.join()
executor.wait_completion()
print(count())
92
Close
executor.close() shuts down the worker threads of the executor, and the executor is the one that every wrapper shares. After it, another wrapper still answers is_closed() with False, but submitting work to it raises an error that says the executor has been shut down. with db.async_executor() as executor: closes at the end of the block. db.close() closes every executor that the database handed out, and close() of a wrapper is safe to call twice.
The class of the error that a submit raises after a close is not part of the Python API, so the block catches Exception and reads the text:
with db.async_executor() as closing:
closing.command("sql", "INSERT INTO Item SET n = 300")
closing.wait_completion()
print(closing.is_closed(), executor.is_closed())
try:
executor.transaction(lambda: None)
except Exception as error:
print("shut down" in str(error))
print(count())
True False
True
93
Call wait_completion() before close(), as the block does.