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 |
|---|---|---|
|
|
Scripts, notebooks, tests, CLIs, serverless functions, agents. |
|
|
Heavy, long-running loads, or the Java-object APIs. |
See Which package? if you are not sure. If you are not sure, take arcadedb.
The scripts on this page ran on Python 3.12 against both packages, version 26.11.1.post3, and both printed the output shown. The code is the same for both packages.
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
withblock. It closes the database when the block ends, also when an exception leaves it. -
Writes need a transaction.
INSERT,UPDATEandDELETEgo insidewith db.transaction():. Schema statements apply immediately. Reads need no transaction. What a transaction does on an error, and how to roll back by hand, is on Transactions.
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:
-
create_database("./quickstart")creates the directory and opens a database in it. -
Four
CREATEstatements define a document typePerson, three properties and an index onname. -
A transaction inserts three records. The
?marks are positional parameters bound to the values after the statement. -
db.queryreads them back, with and without a filter, andcount(*)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.
The server takes a config dictionary. These keys matter first:
-
hostdefaults tolocalhost, so only clients on the same machine connect. A client in a Docker container or on another machine needsconfig={"host": "0.0.0.0"}(all IPv4 interfaces, or"::"for IPv6).hostapplies to the HTTP server and to every wire protocol that you enable. A per-protocol key such aspostgres_hostoverrides it for that protocol. -
http_port(default 2480) andmode(defaultdevelopment) are read by the bindings. -
Any other key becomes the engine setting
arcadedb.<key with _ replaced by .>. For example,postgres_portsetsarcadedb.postgres.port.
Both packages carry the Postgres, Redis and Bolt wire protocol plugins, and none starts unless you name it in server_plugins:
config = {
"host": "0.0.0.0",
"server_plugins": "Postgres:com.arcadedb.postgres.PostgresProtocolPlugin",
"postgres_port": 5432, # sets arcadedb.postgres.port
}
The class names of the other two are com.arcadedb.redis.RedisProtocolPlugin (port key redis_port) and com.arcadedb.bolt.BoltProtocolPlugin (port key bolt_port).
The native server has no Studio web UI.
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.
-
Values and records: which Python types go in and what comes back, datetimes, record objects and the
SchemaAPI. -
Importing and exporting data: load a file, export a database or a query.
-
DataFrames, Arrow and columns: load and read pandas, Polars, Arrow and numpy data.
-
Python functions and record events: call a Python function from SQL and openCypher, and run Python when a record is written.