Quick Start¶

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

Installation¶

Install the self-contained package with bundled JRE:

uv 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 support two access methods:

Embedded Mode (SQL) - Recommended for Getting Started¶

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"))

HTTP API (Server Mode) - For Remote Access¶

REST requests when server is running - enables remote access:

import arcadedb_embedded as arcadedb
import requests
from requests.auth import HTTPBasicAuth

# Start server with Java API
server = arcadedb.create_server("./server", "password123")
server.start()

auth = HTTPBasicAuth("root", "password123")

# Create database via HTTP
requests.post(
    f"http://localhost:{server.get_http_port()}/api/v1/server",
    auth=auth,
    json={"command": "create database mydb"}
)

# Create schema
requests.post(
    f"http://localhost:{server.get_http_port()}/api/v1/command/mydb",
    auth=auth,
    json={"language": "sql", "command": "CREATE DOCUMENT TYPE Person"}
)

# Insert data
requests.post(
    f"http://localhost:{server.get_http_port()}/api/v1/command/mydb",
    auth=auth,
    json={"language": "sql", "command": "INSERT INTO Person SET name = 'Alice'"}
)

# Query data
response = requests.post(
    f"http://localhost:{server.get_http_port()}/api/v1/command/mydb",
    auth=auth,
    json={"language": "sql", "command": "SELECT FROM Person"}
)
result = response.json()
print(result)

server.stop()

Choose Your Method

Embedded mode: Use for single-process apps (fastest)
HTTP API: Use for multi-process/remote access
Both: Can be used simultaneously on same server!

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