Python API

The relate Python clientclient A language package that runs the relate engine inside a program's process: the Python, Node.js, Rust, Java, Go and Swift clients. Read more in the glossary is the relate-db package, imported as relate: a native extension that opens a storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary and runs the engine in the calling process. It offers two layers. relate.connect() returns a Connection in the style of Python's database API (PEP 249), with cursors whose rows are dicts. relate.Database is the engine handle underneath, with Arrow output and the raw QueryResult. The signatures on this page are read from the package source and checked against relate-db 0.1.2.

Synopsis

import relate

conn = relate.connect(database=":memory:", namespace="neo4j", read_only=False)
cur = conn.execute(query, params=None)        # a Cursor holding every row
rows = cur.fetchall()                         # a list of Record dicts
summary = cur.consume()                       # a ResultSummary
conn.commit()                                 # a bookmark "relate:<n>", or None
conn.close()

db = relate.Database(path=":memory:", namespace="neo4j", *, read_only=False)
result = db.execute(query, params=None)       # a QueryResult
ipc = db.execute_arrow(query, params=None)    # Arrow IPC stream bytes

Module

Open options

relate.connect(), relate.Connection() and relate.Database() take the same three options.

A file-backed store has one writing open at a time, in this process or any other; a second raises OperationalError: storage locked: <path>, where <path> is the .rl file, or <store>/.cypherlite.writer for a directory store. A directory store also opens read_only=True beside its writer; a .rl store does not.

Connection

Any call after close() raises ProgrammingError: Cannot operate on a closed connection.

Cursor

A cursor holds the whole result from the moment the statement returns; fetching moves a position over rows already in memory.

Record

A row is a relate.Record, a dict subclass. row["name"] and row.name read the same value; assigning row.name raises AttributeError. row.keys() returns the column names in RETURN order, and row.data() returns a plain dict copy.

ResultSummary

ResultGraph

Database

The native handle. It is thread-affine like a Connection, and runs statements in auto-commit mode until begin_transaction().

QueryResult

Value classes

element_id is None in the system namespace, where elementId() fails.

Value mapping

params is a dict with str keys at every level, referenced as $name. Every parameter a statement names must be present; None is a value.

Cursor.description maps the engine's column type to a PEP 249 type object:

relate.viz

An optional module that turns a result into a neo4j_viz.VisualizationGraph. It needs the neo4j-viz package, which no relate-db extra installs; import relate does not load it.

Errors

Every engine error and every parameter-type or range error raises a subclass of relate.Error, in the PEP 249 tree; a cyclic parameter, or one nested more than 128 levels deep, raises Python's own ValueError, which except relate.Error does not catch. The engine's classification is copied onto the exception as attributes; an error the client raises itself carries None in the four engine attributes.

The errors reference lists the engine messages behind each class.

Threading

A Connection or Database belongs to the thread that opened it. A statement or other call from another thread raises ProgrammingError with kind WrongThread, and the connection stays usable on its own thread. Connection.close() from another thread also raises WrongThread, but it marks the Connection closed: every later call, from any thread, raises ProgrammingError: Cannot operate on a closed connection. Dropping the last reference, on any thread, checkpoints a writable store. The engine releases the GIL while a statement runs.

Limits

Capabilities

Example

The native layer reports a type name per column, from the first row, and counts without a statement:

import relate

TEAM = """
CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace)
"""

db = relate.Database(":memory:")
db.execute(TEAM)
result = db.execute(
    "MATCH (p:Person {name: 'Grace'})-[w:WORKS_ON]->(proj) "
    "RETURN p.name AS name, w.since AS since, proj AS project ORDER BY since LIMIT 1"
)
print(result.columns, result.column_types, result.query_type)
print(db.node_count(), db.relationship_count(), db.labels(), db.relationship_types())
db.close()

['name', 'since', 'project'] ['STRING', 'INTEGER', 'NODE'] r
5 5 ['Person', 'Project'] ['KNOWS', 'MAINTAINS', 'WORKS_ON']

A nodenode An entity in the graph: it carries zero or more labels and a map of properties, and relationships connect it to other nodes. Read more in the glossary arrives as a relate.Node, a relationshiprelationship A directed, typed connection between two nodes, with properties of its own; every relationship has exactly one type and a start and an end node. Read more in the glossary as a relate.Relationship, and a pathpath An alternating sequence of nodes and relationships that a pattern matched, bound with p = … and read with nodes(p), relationships(p) and length(p). Read more in the glossary as a relate.Path holding both:

import relate

TEAM = """
CREATE (ada:Person {name: 'Ada', role: 'engineer'}),
       (grace:Person {name: 'Grace', role: 'engineer'}),
       (noor:Person {name: 'Noor', role: 'maintainer'}),
       (relate:Project {name: 'relate', language: 'Rust'}),
       (tck:Project {name: 'opencypher-tck', language: 'Gherkin'}),
       (ada)-[:WORKS_ON {since: 2024}]->(relate),
       (grace)-[:WORKS_ON {since: 2023}]->(relate),
       (grace)-[:WORKS_ON {since: 2022}]->(tck),
       (noor)-[:MAINTAINS]->(relate),
       (ada)-[:KNOWS]->(grace)
"""

with relate.connect(":memory:") as conn:
    conn.execute(TEAM)
    path = conn.execute("MATCH p = (:Person {name: 'Ada'})-[:KNOWS]->(:Person) RETURN p").single()["p"]
    ada, grace = path.nodes
    knows = path.relationships[0]
    print(len(path), ada["name"], ada.element_id, ada.labels)
    print(knows.type, knows.element_id, knows.start_node_element_id, knows.end_node_element_id, grace["name"])

1 Ada 4:relate-neo4j:n0 ['Person']
KNOWS 5:relate-neo4j:r4 4:relate-neo4j:n0 4:relate-neo4j:n1 Grace

See also

• Use the Python client: open modes, typed values, transactions, errors, and threads in working programs.
• Embed relate in a Python app: the first program.
• Errors: the exception classes and every engine error with its codes.
• Node.js API: the same engine from Node.js.
• Embedded graph in an app: the problem the clients solve.