From 2d3485d28f02cac7de9fdc5a7988810b303871d9 Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Fri, 23 Oct 2026 13:41:04 +0900 Subject: [PATCH 1/3] docs(python): add the embedded bindings page and list them in the Python connection options Co-Authored-By: Claude Sonnet 5.5 --- scripts/generate-nav.py | 1 + .../how-to/connectivity/python-embedded.adoc | 104 ++++++++++++++++++ src/main/asciidoc/languages-drivers.adoc | 4 +- .../asciidoc/tutorials/python-quickstart.adoc | 3 +- 4 files changed, 110 insertions(+), 2 deletions(-) create mode 100644 src/main/asciidoc/how-to/connectivity/python-embedded.adoc diff --git a/scripts/generate-nav.py b/scripts/generate-nav.py index 3427cff14..f7796ec3c 100644 --- a/scripts/generate-nav.py +++ b/scripts/generate-nav.py @@ -95,6 +95,7 @@ # The group labels carry no URL because there is no per-language # landing page to point them at (Java has one; Python, JS and Go do not). ("Python", [ + ("how-to/connectivity/python-embedded.adoc", "Embedded bindings"), ("how-to/connectivity/drivers/python-http.adoc", "Native driver — HTTP"), ("how-to/connectivity/drivers/python-grpc.adoc", "Native driver — gRPC"), ("tutorials/python-quickstart.adoc", "PostgreSQL protocol"), diff --git a/src/main/asciidoc/how-to/connectivity/python-embedded.adoc b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc new file mode 100644 index 000000000..a21a3242c --- /dev/null +++ b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc @@ -0,0 +1,104 @@ +[[python-embedded]] +==== Python -- Embedded Bindings + +`arcadedb-embedded` runs the ArcadeDB engine inside your Python process. Calls cross into the engine through https://jpype.readthedocs.io/[JPype], so there is no network hop and no server to start. The wheel bundles its own Java runtime: you do not install Java. + +The bindings live in the https://github.com/ArcadeData/arcadedb-python-bindings[ArcadeData/arcadedb-python-bindings] repository. This page covers the first steps; the repository holds the full guides and the API reference. + +===== Install + +[source,shell] +---- +pip install arcadedb-embedded +---- + +Or with https://docs.astral.sh/uv/[uv]: + +[source,shell] +---- +uv add arcadedb-embedded +---- + +Python 3.11 to 3.14 is what the wheels' CI runs. Wheels exist for Linux (x86_64 and ARM64), macOS on Apple Silicon, and Windows (x86_64). + +There is a second package, `arcadedb-embedded-native`, which is a *preview*. It is the same engine built as a GraalVM native-image library: no JVM and no JPype. It installs beside `arcadedb-embedded`. Check its PyPI page for its current status before you rely on it. + +===== Open a database and query it + +[source,python] +---- +import arcadedb_embedded as arcadedb + +with arcadedb.create_database("./mydb") as db: + db.command("sql", "CREATE VERTEX TYPE Person") + db.command("sql", "CREATE PROPERTY Person.name STRING") + db.command("sql", "CREATE PROPERTY Person.age INTEGER") + + with db.transaction(): + db.command("sql", "INSERT INTO Person SET name = ?, age = ?", "Alice", 30) + db.command("sql", "INSERT INTO Person SET name = ?, age = ?", "Bob", 25) + + for row in db.query("sql", "SELECT name, age FROM Person WHERE age > ?", 26): + print(row.get("name"), row.get("age")) +---- + +[source,text] +---- +Alice 30 +---- + +Reopen the same directory later with `arcadedb.open_database("./mydb")`. `create_database` raises if the path already holds a database. Pass `read_only=True` to `open_database` to refuse writes. + +Queries in other languages use the same two calls, for example openCypher: + +[source,python] +---- +with arcadedb.open_database("./mydb") as db: + for row in db.query("opencypher", "MATCH (p:Person) RETURN p.name AS name ORDER BY name"): + print(row.get("name")) +---- + +[source,text] +---- +Alice +Bob +---- + +TIP: Schema, inserts and graph work are best written as SQL or openCypher through `db.command(...)` and `db.query(...)`. The bindings also expose wrapper objects for the rest of the Java API; the repository documents them. + +NOTE: *Writes need a transaction.* `INSERT`, `UPDATE` and `DELETE` go inside `with db.transaction():`. Schema statements apply immediately. + +===== Pick the embedded bindings or the HTTP driver + +[cols="1,2,2"] +|=== +| | Embedded bindings | HTTP driver (`arcadedb-driver`) + +| Where the engine runs +| In your Python process +| In a separate ArcadeDB server + +| Who can reach the data +| One process at a time: the database directory is locked while it is open +| Any number of clients, local or remote + +| Network round trip +| None +| One per call + +| Setup +| `pip install arcadedb-embedded` +| A running server, plus `pip install arcadedb-driver` +|=== + +Choose the embedded bindings for a single script, a notebook, or an application with one Python process that owns its data. Several threads of one process can share a database. + +Choose the xref:how-to/connectivity/drivers/python-http.adoc[HTTP driver] when more than one process, another language, or a remote machine must reach the same database, or when the server must outlive your Python process. + +The two meet in one case. The bindings can start an in-process HTTP server (`arcadedb.create_server(...)`), so the process that owns the database keeps direct access while other clients connect over HTTP. That server lives and dies with your Python process. For a long-running service, run the regular ArcadeDB server instead. + +===== Where to go next + +* https://github.com/ArcadeData/arcadedb-python-bindings[Bindings repository] -- guides for vectors, graphs, time series, import and server mode, plus the API reference and examples. +* xref:how-to/connectivity/drivers/native-drivers.adoc[Native drivers] -- the HTTP and gRPC clients, if you would rather talk to a server. +* xref:tutorials/python-quickstart.adoc[Python quickstart] -- the PostgreSQL wire protocol route. diff --git a/src/main/asciidoc/languages-drivers.adoc b/src/main/asciidoc/languages-drivers.adoc index 80f2775c9..202304d27 100644 --- a/src/main/asciidoc/languages-drivers.adoc +++ b/src/main/asciidoc/languages-drivers.adoc @@ -22,7 +22,7 @@ Python

Python

-

arcadedb-driver (HTTP & gRPC), psycopg, neo4j, httpx.

+

arcadedb-driver (HTTP & gRPC), embedded bindings, psycopg, neo4j, httpx.

 JavaScript @@ -76,3 +76,5 @@ ++++ + +Running Python in the same process as the database? See xref:how-to/connectivity/python-embedded.adoc[Python -- Embedded Bindings]. diff --git a/src/main/asciidoc/tutorials/python-quickstart.adoc b/src/main/asciidoc/tutorials/python-quickstart.adoc index 5f7b42593..2e1c6d248 100644 --- a/src/main/asciidoc/tutorials/python-quickstart.adoc +++ b/src/main/asciidoc/tutorials/python-quickstart.adoc @@ -12,6 +12,7 @@ ArcadeDB exposes multiple wire protocols, so you can pick the one your stack alr * xref:how-to/connectivity/drivers/python-grpc.adoc[*Native gRPC driver*] -- `pip install arcadedb-driver-grpc`, for streaming and bulk inserts. * xref:how-to/connectivity/bolt.adoc#python-example[*Neo4j BOLT*] -- `pip install neo4j`, run Cypher queries. * xref:reference/http-api/http.adoc[*HTTP/JSON API*] -- use `requests` or `httpx`, no driver required. +* xref:how-to/connectivity/python-embedded.adoc[*Embedded bindings*] -- `pip install arcadedb-embedded`, runs the engine inside your Python process with no server. A native-image build, `arcadedb-embedded-native`, is in preview. This tutorial uses the PostgreSQL wire protocol, which is the right choice when you already run a PostgreSQL stack. ==== @@ -207,7 +208,7 @@ See the xref:reference/http-api/http.adoc[HTTP/JSON API reference] for every end ==== Embedded Python Bindings -For high-performance use cases that need in-process access (no network overhead), see the https://github.com/humemai/arcadedb-embedded-python[arcadedb-embedded-python] project, which provides direct JVM bindings via JPype. +For use cases that need in-process access (no network overhead), see xref:how-to/connectivity/python-embedded.adoc[Python -- Embedded Bindings]. They run the engine inside your Python process through JPype. ==== Next Steps From 1d056d4ae285ce92e5ac78a0a656ba9a1963f02a Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Fri, 23 Oct 2026 13:54:09 +0900 Subject: [PATCH 2/3] docs(python): say both builds ship for now and the plan to converge on native Co-Authored-By: Claude Opus 5.5 --- src/main/asciidoc/how-to/connectivity/python-embedded.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/main/asciidoc/how-to/connectivity/python-embedded.adoc b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc index a21a3242c..35080883f 100644 --- a/src/main/asciidoc/how-to/connectivity/python-embedded.adoc +++ b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc @@ -21,7 +21,7 @@ uv add arcadedb-embedded Python 3.11 to 3.14 is what the wheels' CI runs. Wheels exist for Linux (x86_64 and ARM64), macOS on Apple Silicon, and Windows (x86_64). -There is a second package, `arcadedb-embedded-native`, which is a *preview*. It is the same engine built as a GraalVM native-image library: no JVM and no JPype. It installs beside `arcadedb-embedded`. Check its PyPI page for its current status before you rely on it. +There is a second package, `arcadedb-embedded-native`, which is a *preview*. It is the same engine built as a GraalVM native-image library: no JVM and no JPype. It installs beside `arcadedb-embedded`. Both builds are published for now, with the JVM build as the default. The plan is to converge on the native build once it matches the JVM build on the workloads that matter; then one package, `arcadedb`, will ship the native build only. Check the preview's PyPI page for its current status before you rely on it. ===== Open a database and query it From ccdaed0f4067dbb9944d8c5730008403b9f0fa9b Mon Sep 17 00:00:00 2001 From: Taewoon Kim Date: Fri, 23 Oct 2026 16:58:11 +0900 Subject: [PATCH 3/3] docs(python): link the renamed bindings repository ArcadeData/arcadedb-python Co-Authored-By: Claude Opus 5.5 --- src/main/asciidoc/how-to/connectivity/python-embedded.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/main/asciidoc/how-to/connectivity/python-embedded.adoc b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc index 35080883f..952a75791 100644 --- a/src/main/asciidoc/how-to/connectivity/python-embedded.adoc +++ b/src/main/asciidoc/how-to/connectivity/python-embedded.adoc @@ -3,7 +3,7 @@ `arcadedb-embedded` runs the ArcadeDB engine inside your Python process. Calls cross into the engine through https://jpype.readthedocs.io/[JPype], so there is no network hop and no server to start. The wheel bundles its own Java runtime: you do not install Java. -The bindings live in the https://github.com/ArcadeData/arcadedb-python-bindings[ArcadeData/arcadedb-python-bindings] repository. This page covers the first steps; the repository holds the full guides and the API reference. +The bindings live in the https://github.com/ArcadeData/arcadedb-python[ArcadeData/arcadedb-python] repository. This page covers the first steps; the repository holds the full guides and the API reference. ===== Install @@ -99,6 +99,6 @@ The two meet in one case. The bindings can start an in-process HTTP server (`arc ===== Where to go next -* https://github.com/ArcadeData/arcadedb-python-bindings[Bindings repository] -- guides for vectors, graphs, time series, import and server mode, plus the API reference and examples. +* https://github.com/ArcadeData/arcadedb-python[Bindings repository] -- guides for vectors, graphs, time series, import and server mode, plus the API reference and examples. * xref:how-to/connectivity/drivers/native-drivers.adoc[Native drivers] -- the HTTP and gRPC clients, if you would rather talk to a server. * xref:tutorials/python-quickstart.adoc[Python quickstart] -- the PostgreSQL wire protocol route.