Quick Start¶

Get up and running with ArcadeDB Python bindings in 5 minutes!

Installation¶

Install the self-contained package with bundled JRE:

pip install arcadedb-embedded

No Java Installation Required

The package includes a bundled platform-specific JRE. You don't need to install Java separately!

Access Methods¶

ArcadeDB Python bindings run the database in your Python process. That is the primary mode. An optional in-process HTTP server is also bundled, for when other processes or languages need to reach the same data.

Embedded Mode (SQL)¶

Direct local database access via JPype, using SQL for schema and CRUD:

import arcadedb_embedded as arcadedb

# Direct database access (SQL)
with arcadedb.create_database("./mydb") as db:
    # Schema
    db.command("sql", "CREATE DOCUMENT TYPE Person")
    db.command("sql", "CREATE PROPERTY Person.name STRING")

    # Insert (requires explicit transaction)
    with db.transaction():
        db.command("sql", "INSERT INTO Person SET name = ?", "Alice")

    # Query (no transaction needed)
    result = db.query("sql", "SELECT FROM Person")
    for record in result:
        print(record.get("name"))

Server Mode (HTTP + Studio)¶

When another process, another language, or a browser needs the same data, start the bundled server. The owning process keeps full-speed embedded access:

import arcadedb_embedded as arcadedb

with arcadedb.create_server("./databases", root_password="password123") as server:
    db = server.create_database("mydb")     # embedded access, in this process
    print("Studio:", server.get_studio_url())  # HTTP access, any process

Server mode adds ~8MB to the wheel and costs nothing at runtime until you call create_server() — see Server Mode for the measured breakdown, and Access Methods for all three paths.

For a server that outlives your Python process, or for HA/TLS, run the official ArcadeDB server instead.

Your First Database¶

1. Create a Database¶

import arcadedb_embedded as arcadedb

# Create database (context manager for automatic open and close)
with arcadedb.create_database("./quickstart") as db:
    print(f"Created database at: {db.get_database_path()}")

2. Create Schema¶

with arcadedb.create_database("./quickstart") 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")
    print("Schema created!")

3. Insert Data¶

All writes must be in a transaction:

with arcadedb.create_database("./quickstart") 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")

    # Use transaction for writes
    with db.transaction():
        for name, age in [("Alice", 30), ("Bob", 25), ("Charlie", 35)]:
            db.command("sql", "INSERT INTO Person SET name = ?, age = ?", name, age)

    print("Inserted 3 records")

Transactions

Always use with db.transaction(): for INSERT, UPDATE, DELETE operations.

4. Query Data¶

with arcadedb.create_database("./quickstart") 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():
        for name, age in [("Alice", 30), ("Bob", 25)]:
            db.command("sql", "INSERT INTO Person SET name = ?, age = ?", name, age)

    # Query data
    result = db.query("sql", "SELECT FROM Person WHERE age > 25")

    for record in result:
        name = record.get('name')
        age = record.get('age')
        print(f"Name: {name}, Age: {age}")

Output:

Name: Alice, Age: 30

Complete Example¶

Here's a complete working example:

import arcadedb_embedded as arcadedb

def main():
    # Create database
    with arcadedb.create_database("./quickstart") as db:
        # Create schema (SQL)
        db.command("sql", "CREATE DOCUMENT TYPE Person")
        db.command("sql", "CREATE PROPERTY Person.name STRING")
        db.command("sql", "CREATE PROPERTY Person.age INTEGER")
        db.command("sql", "CREATE PROPERTY Person.email STRING")
        db.command("sql", "CREATE INDEX ON Person (name) NOTUNIQUE")

        # Insert data (in transaction)
        with db.transaction():
            for name, age, email in [
                ("Alice", 30, "alice@example.com"),
                ("Bob", 25, "bob@example.com"),
                ("Charlie", 35, "charlie@example.com"),
            ]:
                db.command(
                    "sql",
                    "INSERT INTO Person SET name = ?, age = ?, email = ?",
                    name,
                    age,
                    email,
                )

        print("✅ Inserted 3 records")

        # Query all (No transaction needed. SQL still fine for reads)
        print("\n📋 All people:")
        result = db.query("sql", "SELECT FROM Person ORDER BY age")
        for record in result:
            print(f"  - {record.get('name')}, age {record.get('age')}")

        # Query with filter
        print("\n🔍 People over 25:")
        result = db.query("sql", "SELECT FROM Person WHERE age > 25 ORDER BY age")
        for record in result:
            print(f"  - {record.get('name')}, age {record.get('age')}")

        # Count
        result = db.query("sql", "SELECT count(*) as total FROM Person")
        total = result.first().get('total')
        print(f"\n📊 Total people: {total}")

if __name__ == "__main__":
    main()

Output:

✅ Inserted 3 records

📋 All people:
  - Bob, age 25
  - Alice, age 30
  - Charlie, age 35

🔍 People over 25:
  - Alice, age 30
  - Charlie, age 35

📊 Total people: 3

Key Concepts¶

Context Managers¶

Always use with statements for automatic cleanup:

# ✅ Good - automatic cleanup
with arcadedb.create_database("./mydb") as db:
    # Use database
    pass
# Database automatically closed

# ❌ Avoid - manual cleanup required
db = arcadedb.create_database("./mydb")
# Use database
db.close()  # Easy to forget!

Transactions¶

All writes require a transaction:

# ✅ Good - in transaction
with db.transaction():
    db.command("sql", "INSERT INTO Person SET name = ?", "Alice")

# ❌ Will fail - no transaction
db.command("sql", "INSERT INTO Person SET name = 'Alice'")
# write commands outside a transaction will raise

Read-Only Operations

db.query() doesn't require a transaction - only db.command() for writes.

Next Steps¶

Now that you've created your first database, explore more features:

Core Operations

Learn about database management, queries, and transactions
Vector Search

Store and query embeddings with vector indexing
Graph Operations

Work with vertices, edges, and graph traversals
Import Data

Bulk import from CSV and ArcadeDB JSONL exports

Common Patterns¶

Working with Existing Database¶

# Open existing database
with arcadedb.open_database("./quickstart") as db:
    result = db.query("sql", "SELECT FROM Person")
    print(f"Found {len(list(result))} records")

Batch Inserts¶

with db.transaction():
    for i in range(100):
        db.command("sql", "INSERT INTO Person SET name = ?, age = ?", f"User{i}", 20 + i)

Error Handling¶

try:
    with arcadedb.create_database("./mydb") as db:
        db.command("sql", "CREATE DOCUMENT TYPE User")
        db.command("sql", "CREATE PROPERTY User.email STRING")
        db.command("sql", "CREATE INDEX ON User (email) UNIQUE")

        # Data operations require an explicit transaction
        with db.transaction():
            db.command("sql", "INSERT INTO User SET email = ?", "alice@example.com")

            # This will raise an exception due to unique constraint
            db.command("sql", "INSERT INTO User SET email = ?", "alice@example.com")
except Exception as e:
    print(f"Database error: {e}")

Need Help?¶

Examples: Check Examples for more code samples
API Reference: See Database API for all methods
Troubleshooting: Visit Troubleshooting Guide