ArcadeDB Python

Python bindings for ArcadeDB, the multi-model database (graph, document, key/value, vector and time series, queried with SQL or openCypher). The engine runs inside your Python process, with no server and no network hop. This repository builds two packages, and both import as arcadedb: arcadedb (the native build, the default) for scripts, notebooks, tests, CLIs, serverless functions and agents, and arcadedb-jvm (the JVM build) for heavy, long-running loads. Status: beta.

Both packages import arcadedb, and they have the same public API. Install one, not both. Not sure which? Read Which package?.

Embedded bindings or drivers?

This repository is the embedded bindings: the engine runs inside your Python process. The official drivers are clients of a running ArcadeDB server. Do not mix them up.

You can also use both, for example the bindings for a job and the HTTP driver for a shared server. Driver docs: HTTP, gRPC. More in Which package?.

Install

uv add arcadedb       # native, the default
uv add arcadedb-jvm   # JVM, for heavy long-running loads

The first release of this layout is 26.11.1, and both packages have a final release on PyPI. A plain uv add arcadedb installs the final, and a later pre-release (A.B.C.devN) needs uv add --prerelease allow arcadedb. The same holds for arcadedb-jvm.

A .devN version (for example 26.12.1.dev0, when one is published) is a development pre-release. It embeds a snapshot of the upstream engine, the same snapshot in both packages, pinned by image digest and jar checksums in scripts/dev_engine_pin.json, and the wheel states it (arcadedb.ENGINE_SNAPSHOT, arcadedb.ENGINE_IMAGE_DIGEST). Install it with uv add --prerelease allow arcadedb==26.12.1.dev0 (or arcadedb-jvm==26.12.1.dev0).

Old names: arcadedb-jvm was formerly arcadedb-embedded, and arcadedb was formerly arcadedb-embedded-native (archived on PyPI). The last arcadedb-embedded release, 26.11.1, is a deprecation shim: it installs arcadedb, the native build, and warns once at import. It does not install arcadedb-jvm.

• Python: arcadedb (native) is tested on 3.11 to 3.14 and also installs on 3.15 (requires-python is >=3.11 with no upper bound; the CI runs a subset of the tests on 3.15). arcadedb-jvm needs 3.11 to 3.14 (requires-python is >=3.11,<3.15; its dependency JPype has no 3.15 wheel yet). Each release builds and tests both packages on Python 3.11 to 3.14 on all four platforms below. Between releases, main and the nightly run test arcadedb on 3.12 and 3.14 on every platform (with a short subset on 3.11, 3.13 and 3.15), and arcadedb-jvm on 3.11 to 3.14 on Linux x86-64 and on 3.11 and 3.14 on the other three. A pull request runs a smaller selection.
• Linux x86_64 and ARM64, macOS on Apple Silicon, Windows x86_64, for both packages. The Windows wheel of arcadedb is the newest.
• Import name: arcadedb. Check which package you have with python -c "import arcadedb; print(arcadedb.__backend__)". It prints native or jvm.
• Optional extras: arrow, pandas, polars, vector for arcadedb-jvm; numpy, arrow, pandas, polars for arcadedb.
• arcadedb-jvm bundles its own Java 25 runtime, so you install no Java. arcadedb needs no Java at all.

Quick start

import arcadedb

with arcadedb.create_database("./mydb") as db:
    db.command("sql", "CREATE DOCUMENT TYPE Person")
    db.command("sql", "CREATE PROPERTY Person.name STRING")
    db.command("sql", "CREATE PROPERTY Person.age INTEGER")

    # Writes need a transaction
    with db.transaction():
        db.command("sql", "INSERT INTO Person SET name = ?, age = ?", "Alice", 30)

    for record in db.query("sql", "SELECT FROM Person WHERE age > 25"):
        print(f"Name: {record.get('name')}")

This prints Name: Alice (the engine also logs to standard error). create_database raises if the path already holds a database, so run it in an empty directory. Everything else goes through the same two calls, db.command(...) and db.query(...), in SQL or openCypher.

What is included

• Embedded mode: the database is a directory, opened by one process at a time.
• Graph, document, key/value, vector (JVector HNSW) and time series models; ACID transactions.
• Import from CSV, XML and ArcadeDB JSONL; export to JSONL.
• Columnar results with to_columns(), to_arrow() and to_dataframe().
• Faceted queries: the FACETS clause of a SELECT with a COLUMNAR index, and the counts as a dict in ResultSet.facets (needs engine 26.12.1 or later).
• An optional in-process HTTP server (create_server()), off until you call it, for other processes that need the same data.

New in 26.11.1: the arcadedb-jvm wheels carry the Studio web UI, which the server then serves. Studio used to bundle ApexCharts, which is no longer open source (ArcadeData/arcadedb#10579), and ArcadeData/arcadedb#10627 replaced it with Apache ECharts. The earlier 26.10.x wheels on PyPI have no Studio.

Packages on PyPI

Formerly arcadedb-embedded (now arcadedb-jvm, the same build) and formerly arcadedb-embedded-native (now arcadedb). They imported as arcadedb_embedded and arcadedb_native, and they are deprecated: arcadedb-embedded-native is archived, and the last arcadedb-embedded release, 26.11.1, is a shim that installs arcadedb and warns once at import.

Releases from this repository start with 26.11.1. The 26.10.x wheels were built and published from humemai/arcadedb-embedded-python.

Documentation

• Here: docs/ is an Antora component (AsciiDoc) with Installation, Which package?, Quickstart, Databases and queries, Vectors, Faceted queries, and Concurrency, processes and crashes. It covers only what is specific to the Python bindings.
• Published at docs.arcadedb.com/arcadedb-python, the same site as the main ArcadeDB manual, rebuilt daily from main (ArcadeData/arcadedb-docs#505). The Docs workflow builds it as a site of its own on every change under docs/ and attaches it as the docs-site artifact. To build it locally, run npx -p @antora/cli@3.2.1 -p @antora/site-generator@3.2.1 antora docs/antora-playbook.yml and open docs/build/site/index.html.
• ArcadeDB itself (SQL, openCypher, schema, server): docs.arcadedb.com. It is not repeated here.

Examples

examples/ holds 30 runnable scripts, from a first document store to vector search, time series, graph algorithms and server mode. CI runs them (test-python-examples.yml).

Build and test from source

./scripts/build.sh   # an arcadedb-jvm wheel for your platform in dist/

The arcadedb (native) wheel is built from native/ with GraalVM Community Edition; CLAUDE.md has the commands. A native image build takes about 5 to 30 minutes per platform (macOS is the slowest).

The JVM build runs in Docker on Linux. macOS and Windows need a JDK 25 or later. The jars come from the arcadedata/arcadedb Docker image: latest by default, or the tag in ARCADEDB_TAG (for example ARCADEDB_TAG=26.10.2 ./scripts/build.sh). The package version is read from the engine jar in that image, so an A.B.C-SNAPSHOT image builds A.B.C.devN.

The native build does not use the image. It resolves arcadedb-engine and arcadedb-server from Maven Central at arcadedb.version in native/pom.xml (release versions only, because a snapshot is not on Maven Central) and compiles them with GraalVM Community Edition. Neither build compiles the engine from source: the engine code is upstream's, unmodified.

Tests run against the built wheel, not the source tree: install the wheel with its test extra into a virtual environment, then run pytest. CLAUDE.md has the exact commands, the build options and the lint setup.

Contributing

Open an issue or a pull request. Run pre-commit run --all-files first, and add a regression test with every fix. The rest of the bindings work from humemai/arcadedb-embedded-python is ported here one pull request at a time; #19 lists what is done and what is next.

Where this code comes from

It moved here from bindings/python in ArcadeData/arcadedb at ee04bd202abce0183c6263a3c4d8a61a4d526960, with its git history. Issue numbers in older commit messages refer to that repository. humemai/arcadedb-embedded-python is the fork where the bindings kept developing (runtime fixes, JRE trim, the native build, benchmarks). Its benchmark tooling stays there.

Citation

If you use these bindings in published work, cite them with the metadata in CITATION.cff; GitHub shows it as "Cite this repository". There is no DOI for this repository yet.

License

Apache License 2.0, like ArcadeDB. See LICENSE.