Skip to content

stevereiner/arcadedb-python

Repository files navigation

ArcadeDB Python Driver

PyPI version Python versions License

A comprehensive Python driver for ArcadeDB - the Multi-Model Database that supports Graph, Document, Key-Value, Vector, and Time-Series models in a single engine. Github for ArcadeDB (Apache 2.0).

Note: This package connects to an ArcadeDB server over REST/HTTP. If you need to run ArcadeDB embedded directly inside your Python application (no separate server process), see arcadedb-embedded-python instead.

Credits & Attribution

This driver builds upon the work of the original ArcadeDB Python driver contributors:

This modernized version enhances the original work with updated packaging, documentation, tests, new APIs, vector support, etc.

Features

  • Multi-Model Support: Work with Graph, Document, Key-Value, Vector, and Time-Series data models
  • Full API Coverage: Complete access to ArcadeDB's REST API with SQL, openCypher, Gremlin, GraphQL, and Mongo query languages
  • Vector Search: Native LSM_VECTOR index support with vectorNeighbors() for AI/ML similarity search
  • Bulk Operations: bulk_insert, bulk_upsert, bulk_delete using sqlscript for efficient batched writes
  • Type Annotations: Type hints on all public methods for better IDE support
  • Comprehensive Testing: Full integration test suite (59 tests) against a live ArcadeDB server

Installation

Using UV (Recommended)

# Install uv if not already installed
pip install uv

# Create virtual environment and install
uv venv
uv pip install arcadedb-python

Using Pip

pip install arcadedb-python

Optional Dependencies

# PostgreSQL driver support
uv pip install arcadedb-python[postgresql]
# or: pip install arcadedb-python[postgresql]

# Cypher syntax highlighting
uv pip install arcadedb-python[cypher]
# or: pip install arcadedb-python[cypher]

# All optional features
uv pip install arcadedb-python[full]
# or: pip install arcadedb-python[full]

# Development dependencies
uv pip install arcadedb-python[dev]
# or: pip install arcadedb-python[dev]

Quick Start

Basic Usage

from arcadedb_python import DatabaseDao, SyncClient

# Step 1: Create a client connection
client = SyncClient(
    host="localhost",
    port=2480,
    username="root",
    password="playwithdata"
)

# Step 2: Connect to database (or create it)
if not DatabaseDao.exists(client, "mydb"):
    db = DatabaseDao.create(client, "mydb")
else:
    db = DatabaseDao(client, "mydb")

# Step 3: Create schema (DDL requires is_command=True)
db.query("sql", "CREATE VERTEX TYPE Person IF NOT EXISTS", is_command=True)

# Step 4: Insert data (DML requires is_command=True)
db.query("sql", "INSERT INTO Person SET name = 'John', age = 30", is_command=True)

# Step 5: Query data
result = db.query("sql", "SELECT FROM Person LIMIT 10")
print(result)

# Step 6: Graph traversal
result = db.query("sql", """
    MATCH {type: Person, as: person} 
    RETURN person.name, person.age
""")
print(result)

Important Notes

  • Use SyncClient to create connections, not DatabaseDao directly
  • Use is_command=True for DDL/DML operations (CREATE, INSERT, UPDATE, DELETE)
  • SELECT queries don't need is_command=True (it defaults to False)
  • IF NOT EXISTS is supported for DOCUMENT TYPE, VERTEX TYPE, and EDGE TYPE

API Documentation

For complete API reference including all methods, parameters, exceptions, and detailed examples:

📚 docs/API.md - Comprehensive API documentation covering:

  • SyncClient - Connection management
  • DatabaseDao - All database operations (query, transactions, bulk operations)
  • Exception handling and error types
  • Configuration options
  • Complete code examples

Examples

Available Examples

examples/quickstart_example.py

  • Complete walkthrough of all Quick Start code
  • All data models: Graph, Document, Key-Value, Time-Series, Vector storage
  • Step-by-step explanations
  • Error handling examples

examples/test_query_languages.py

  • openCypher query examples
  • Gremlin query examples
  • Database creation and cleanup

Running Examples

# Complete quickstart with all features
python examples/quickstart_example.py

# Test openCypher and Gremlin queries
python examples/test_query_languages.py

Requirements: ArcadeDB must be running on localhost:2480 with default credentials (root/playwithdata)

Advanced Usage

Document Operations

Documents are schema-flexible records. They cannot be endpoints of edges. Vertices are documents with added capability: they can be connected by edges.

db.query("sql", "CREATE DOCUMENT TYPE Product IF NOT EXISTS", is_command=True)
db.query("sql", """
    INSERT INTO Product CONTENT {
        "name": "Laptop",
        "price": 999.99,
        "specs": {
            "cpu": "Intel i7",
            "ram": "16GB"
        }
    }
""", is_command=True)

result = db.query("sql", "SELECT FROM Product")
print(result)

Graph Operations

Edges connect vertex types only. Both the source and target must be VERTEX TYPE.

# Create vertex types for both ends of the edge
db.query("sql", "CREATE VERTEX TYPE Customer IF NOT EXISTS", is_command=True)
db.query("sql", "CREATE VERTEX TYPE ItemType IF NOT EXISTS", is_command=True)
db.query("sql", "CREATE EDGE TYPE Purchased IF NOT EXISTS", is_command=True)

# Insert vertices
db.query("sql", "INSERT INTO Customer SET name = 'Alice'", is_command=True)
db.query("sql", "INSERT INTO ItemType SET name = 'Laptop', price = 999.99", is_command=True)

# Connect them with an edge
db.query("sql", """
    CREATE EDGE Purchased
    FROM (SELECT FROM Customer WHERE name = 'Alice')
    TO (SELECT FROM ItemType WHERE name = 'Laptop')
    SET date = sysdate(), amount = 999.99
""", is_command=True)

# Traverse the graph
result = db.query("sql", """
    SELECT expand(out('Purchased')) FROM Customer WHERE name = 'Alice'
""")
print(result)

Key-Value Operations

db.query("sql", "CREATE DOCUMENT TYPE Settings IF NOT EXISTS", is_command=True)
db.query("sql", "INSERT INTO Settings SET key = 'theme', value = 'dark'", is_command=True)

Time-Series Operations

db.query("sql", "CREATE VERTEX TYPE Sensor IF NOT EXISTS", is_command=True)
db.query("sql", """
    INSERT INTO Sensor SET 
    sensor_id = 'temp_01', 
    timestamp = sysdate(), 
    temperature = 23.5
""", is_command=True)

Vector Search (for AI/ML applications)

# Declare the vector property and create an LSM vector index
db.query("sql", "CREATE VERTEX TYPE DocRecord", is_command=True)
db.query("sql", "CREATE PROPERTY DocRecord.embedding ARRAY_OF_FLOATS", is_command=True)
db.create_vector_index("DocRecord", "embedding", dimensions=4)

# Insert documents with embeddings (use CONTENT for structured inserts)
db.query("sql", """
    INSERT INTO DocRecord CONTENT {
        "title": "AI Research Paper",
        "embedding": [0.1, 0.2, 0.3, 0.4],
        "content": "Full document text..."
    }
""", is_command=True)
db.query("sql", """
    INSERT INTO DocRecord CONTENT {
        "title": "Machine Learning Guide",
        "embedding": [0.9, 0.8, 0.7, 0.6],
        "content": "Intro to ML..."
    }
""", is_command=True)

# Perform vector similarity search
results = db.vector_search(
    type_name="DocRecord",
    embedding_field="embedding",
    query_embedding=[0.1, 0.2, 0.3, 0.4],
    top_k=2
)
for doc in results:
    print(doc["title"])

Using openCypher

Note: Use "opencypher" as the language to target ArcadeDB's native openCypher engine, introduced in recent releases. The older "cypher" language identifier used a Cypher implementation built on top of Gremlin and is now superseded by this native engine.

# Create nodes
db.query("opencypher", "CREATE (p:Person {name: 'John', age: 30})", is_command=True)
db.query("opencypher", "CREATE (p:Person {name: 'Jane', age: 25})", is_command=True)

# Create relationship
db.query("opencypher", """
    MATCH (a:Person {name: 'John'}), (b:Person {name: 'Jane'})
    CREATE (a)-[:KNOWS]->(b)
""", is_command=True)

# Query with openCypher
result = db.query("opencypher", "MATCH (p:Person) RETURN p.name, p.age")
print(result)

Using Gremlin

# Note: Gremlin support may have different performance characteristics than native SQL
# For large operations, consider using ArcadeDB's native SQL or Java API

# Add vertices
db.query("gremlin", "g.addV('Person').property('name', 'John').property('age', 30)", is_command=True)
db.query("gremlin", "g.addV('Person').property('name', 'Jane').property('age', 25)", is_command=True)

# Query with Gremlin
result = db.query("gremlin", "g.V().hasLabel('Person').values('name')")
print(result)

# Traversal
result = db.query("gremlin", "g.V().hasLabel('Person').has('age', gt(20)).values('name', 'age')")
print(result)

Configuration Options

SyncClient Parameters

Parameter Type Default Description
host str "localhost" ArcadeDB server hostname
port int 2480 ArcadeDB server port
username str None Database username
password str None Database password
protocol str "http" Protocol ("http" or "https")

DatabaseDao.query() Parameters

Parameter Type Default Description
language str Required Query language: "sql", "opencypher", "gremlin", "graphql", "mongo"
command str Required The query/command to execute
is_command bool False Set True for DDL/DML (CREATE, INSERT, UPDATE, DELETE)
limit int None Maximum number of results
params dict None Query parameters
session_id str None Transaction session ID

Requirements

  • Python: 3.10 or higher
  • ArcadeDB: Version 25.8.1 or higher
  • Dependencies:
    • requests >= 2.25.0
    • retry >= 0.9.2

Development

Setting up Development Environment

# Clone the repository
git clone https://github.com/stevereiner/arcadedb-python.git
cd arcadedb-python

# Install uv (if not already installed)
pip install uv

# Create virtual environment and install dependencies
uv venv
uv pip install -e .[dev]

# Run tests
uv run pytest

# Run linting
uv run black .
uv run isort .
uv run flake8
uv run mypy arcadedb_python

Building the Package

# Build the package
uv build

# Check the built package
uv run twine check dist/*

Running ArcadeDB for Development

# Using Docker
docker run -d --name arcadedb \
  -p 2480:2480 -p 2424:2424 \
  -e JAVA_OPTS="-Darcadedb.server.rootPassword=playwithdata" \
  arcadedata/arcadedb:latest

# Access ArcadeDB Studio at http://localhost:2480

Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Links

This Project

ArcadeDB

Original Contributors

Changelog

See CHANGELOG.md for a detailed history of changes.

About

Python API for ArcadeDB

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages