Skip to content

ArcadeDB Python Bindings

  • Production Ready

    Native Python bindings for ArcadeDB with comprehensive embedded/server coverage

    • Status: ✅ Production Ready
    • Tests: ✅ Full suite green on every platform build

  • Pure Python API

    Pythonic interface to ArcadeDB's multi-model database

    Quick Start

  • Multi-Model Database

    Graph, Document, Key/Value, Vector, Time Series in one database

    Learn More

  • High Performance

    Direct JVM integration via JPype for maximum speed

    Architecture

What is ArcadeDB?

ArcadeDB is a next-generation multi-model database that supports:

  • Graph: Native property graphs with vertices and edges
  • Document: Schema-less JSON documents
  • Key/Value: Fast key-value pairs
  • Vector: Embeddings with HNSW (JVector) similarity search
  • Time Series: Temporal data with efficient indexing
  • Search Engine: Full-text search with Lucene

Why Python Bindings?

These bindings provide native Python access to ArcadeDB's full capabilities with two access methods:

Embedded Engine (DSL-first)

  • Direct JVM Integration: Run database directly in your Python process via JPype
  • Best Performance: No network overhead, direct method calls
  • Use Cases: Single-process applications, high-performance scenarios
  • Recommended style: SQL/OpenCypher via db.command(...) and db.query(...)
  • Example: 
    db.command("sql", "CREATE DOCUMENT TYPE Person")
with db.transaction():
    db.command("sql", "INSERT INTO Person SET name = 'Alice'")

HTTP API (Server Mode)

  • Remote Access: HTTP REST endpoints when server is running
  • Multi-Language: Any language can connect via HTTP
  • Use Cases: Multi-process applications, web services, remote access
  • Example: 
    import requests
from requests.auth import HTTPBasicAuth

requests.post(
    "http://localhost:2480/api/v1/query/mydb",
    json={"language": "sql", "command": "SELECT FROM Person"},
    auth=HTTPBasicAuth("root", "password"),
    timeout=30,
)

Both APIs can be used simultaneously on the same server instance; see Access Methods and Server Mode.

When to run the official server distribution instead

In-process server mode ties the server's lifetime to your Python process. For a database that outlives any one client, or for HA/replication and TLS, run the standalone ArcadeDB server.

Additional Features

  • Multiple Query Languages: SQL and OpenCypher
  • ACID Transactions: a commit survives a process crash; with arcadedb.txWalFlush=1 it also survives a power cut (see Durability)
  • Type Safety: Strong Python type handling and clear errors

Current Ingest Guidance

The bindings are SQL/Cypher-first, but the recommended ingest path depends on what you are doing.

  • For normal application code, prefer SQL/OpenCypher through db.command(...) and db.query(...).
  • For file-driven imports or restore flows, use SQL IMPORT DATABASE or the narrow db.import_documents(...) wrapper when you specifically need document-file import.
  • For bulk document ingest from Python, prefer db.insert_many(...), which crosses the FFI boundary once per batch; add parallel=True on a type created with as many buckets as the async executor has writers, or a multiple (CREATE DOCUMENT TYPE T BUCKETS n, ArcadeData/arcadedb#8478); on a laptop's 4 performance cores (engine b22b5e9954, 6 runs per arm) it was 1.11x to 1.14x faster than the synchronous mode at 1, 3, 4, and 8 buckets alike.
  • The async executor's SQL command path is not a bulk-ingest path. Before 26.10.1, async_executor().command(...) could silently drop records above parallel level 1 (ArcadeData/arcadedb#7615, fixed in #7625); see Bulk Ingest Recommendation.
  • For bulk graph ingest from Python, prefer GraphBatch.

Features

Core Features

  • 🚀 Embedded Mode - Direct database access in Python process
  • 🌐 Server Mode - Optional in-process HTTP server with Studio UI
  • 📦 Self-contained - All JARs and JRE bundled
  • 🔄 Multi-model - Graph, Document, Key/Value, Vector, Time Series
  • 🔍 Multiple languages - SQL and OpenCypher

Advanced Features

  • ⚡ High performance - Direct JVM integration via JPype
  • 🔒 ACID transactions - durable to a process crash by default, to a power cut with arcadedb.txWalFlush=1
  • 🎯 Vector storage - HNSW (JVector) indexing for embeddings
  • 📥 Data import - CSV, XML, and ArcadeDB JSONL
  • 🔎 Full-text search - Lucene integration

Quick Example

import arcadedb_embedded as 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")

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

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

Resource Management

Always use context managers (with statements) for automatic resource cleanup!

Package Coverage

These bindings cover the parts of ArcadeDB's Java API most relevant to Python developers:

Module Status Description
Core Operations ✅ Supported Database, queries, transactions
Schema Management ✅ Supported Types, properties, indexes
Server Mode ✅ Supported HTTP server, Studio UI, database management
Vector Search ✅ Supported HNSW (JVector) indexing, similarity search
Data Import ✅ Supported CSV, XML, and ArcadeDB JSONL
Data Export ✅ Supported JSONL; CSV for query results
Graph API ✅ Supported SQL and OpenCypher, plus record wrappers

See Java API Coverage for detailed comparison.

Benchmarks

ArcadeDB is measured against the engines you would otherwise reach for, on one machine, one job at a time, with every timed query's answer compared across engines before any latency is published. The results live on the project page; the Benchmarks section documents the protocol, the answer checking, how to run a lane yourself, and how to read the output.

Distribution

We provide a single, self-contained package that works on all major platforms:

Platforms Package Name Size What's Included
linux/amd64, linux/arm64, darwin/arm64, windows/amd64 arcadedb-embedded ~69 MiB wheel, ~96 MiB installed Full ArcadeDB + Bundled JRE + Studio UI

The package uses the standard import:

import arcadedb_embedded as arcadedb

No Java Installation Required!

The package includes a bundled Java 25 Runtime Environment (JRE) optimized for ArcadeDB. You do not need to install Java separately on your system.

Getting Started

Requirements

  • Python: 3.10 to 3.14 (CI runs all five on every supported platform)
  • OS: Linux (x86_64, ARM64), macOS (Apple Silicon), or Windows (x86_64)

Self-Contained

Everything needed to run ArcadeDB is included in the wheel. Current Linux x86_64 package metadata and local installs are in this ballpark, with small variation by platform, version, and filesystem:

  • Bundled JRE (Platform-specific Java 25 runtime trimmed with jlink to only what's required for ArcadeDB, ~63 MiB uncompressed)
  • ArcadeDB JARs (~33 MiB uncompressed)
  • Wheel download (~69 MiB compressed)
  • Installed package on disk (~96 MiB)
  • JPype (Bridge between Python and the bundled JVM)

Community & Support

License

Both upstream ArcadeDB (Java) and this ArcadeDB Embedded Python project are licensed under Apache 2.0, fully open and free for everyone, including commercial use.