Quickstart

This page builds a small database from scratch. You need one of the two packages from Installation. Both import as arcadedb.

Package Install Pick this if

arcadedb (native, the default)

pip install arcadedb

Scripts, notebooks, tests, CLIs, serverless functions, agents.

arcadedb-jvm (JVM)

pip install arcadedb-jvm

Heavy, long-running loads, or the Java-object APIs.

See Which package? if you are not sure. If you are not sure, take arcadedb. Until a final 26.11.1 is on PyPI, add --pre to the install line of arcadedb (see the transition note in Installation).

The scripts on this page ran against the JVM build, version 26.10.2.post1 (formerly arcadedb-embedded). The output shown is what it printed. The code is the same for both packages. The wording of an error message can differ on arcadedb.

Embedded mode

The database runs in your Python process. You use SQL for the schema and for CRUD, through two calls. ArcadeDB SQL is its own dialect, and it has no JOINs: records link to each other and a query follows the links (see No JOINs).

  • db.command(language, statement, *params) runs a statement that can change data or schema.

  • db.query(language, statement, *params) runs a read.

Two rules cover most first mistakes:

  • Use a with block. It closes the database when the block ends, also when an exception leaves it.

  • Writes need a transaction. INSERT, UPDATE and DELETE go inside with db.transaction():. Schema statements apply immediately. Reads need no transaction.

A complete example

import 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 a transaction)
        with db.transaction():
            for name, age, email in [
                ("Alice", 30, "[email protected]"),
                ("Bob", 25, "[email protected]"),
                ("Charlie", 35, "[email protected]"),
            ]:
                db.command(
                    "sql",
                    "INSERT INTO Person SET name = ?, age = ?, email = ?",
                    name,
                    age,
                    email,
                )
        print("Inserted 3 records")

        # Query all (no transaction needed for reads)
        print("All people:")
        for record in db.query("sql", "SELECT FROM Person ORDER BY age"):
            print(f"  - {record.get('name')}, age {record.get('age')}")

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

        # Count
        total = db.query("sql", "SELECT count(*) as total FROM Person").first().get("total")
        print("Total people:", total)


if __name__ == "__main__":
    main()
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

create_database raises if the path already holds a database, so run the script in an empty directory or delete ./quickstart before you run it again.

The steps in the script are:

  1. create_database("./quickstart") creates the directory and opens a database in it.

  2. Four CREATE statements define a document type Person, three properties and an index on name.

  3. A transaction inserts three records. The ? marks are positional parameters bound to the values after the statement.

  4. db.query reads them back, with and without a filter, and count(*) counts them.

Reopen the database

Open an existing database with open_database. The second part of the script shows what happens when a write runs outside a transaction:

import arcadedb

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

# A write outside a transaction raises
with arcadedb.open_database("./quickstart") as db:
    try:
        db.command("sql", "INSERT INTO Person SET name = 'Dora'")
    except Exception as e:
        print(type(e).__name__, e, sep=": ")
Found 3 records
ArcadeDBError: Command failed: com.arcadedb.exception.TransactionException: Transaction not begun

Server mode

When another process or another language needs the same data, start the bundled server. The process that created it keeps direct embedded access, and other processes reach the same databases over the HTTP API on the port that get_http_port() returns:

import arcadedb

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

The server runs only while your Python process runs. See Embedded bindings or the HTTP driver for when to run the regular ArcadeDB server (the official Docker image arcadedata/arcadedb) instead.

In the arcadedb-jvm wheels from 26.11.1 the server also serves the Studio web UI, and get_studio_url() returns its address. The earlier 26.10.x wheels do not contain Studio: see the note in What is included.

Next steps

  • Databases and queries: open, drop and check databases, parameters, pagination, SQLScript and openCypher.