Python SDK

Run database queries from a Python service or script. This guide describes the 1.0.0rc1 source candidate, which requires Python 3.10 or newer.

Get the SDKCopy Anchor Link

The SDK is available on GitHub. Follow the source-install steps in that README, then return here to run your first query. The 1.0 candidate package has not been released on registries; the examples below use its source API.

python -m pip install originchain==0.9.0

Connect and run SQLCopy Anchor Link

Set OC_URL and OC_TOKEN in the process environment using the values from Connect. OC_URL is the complete HTTPS database address; preserve its path.

With the candidate installed, save this as query.py and run python query.py:

from originchain import Client

with Client.from_env() as db:
    result = db.sql.run("SELECT $1 AS value", [7])
    print(result.rows)

Expect one row with value equal to 7. This confirms the request reached the database and returned a value; it does not create any data.

No table is needed for this first query. $1 binds the first item in the list. Pass values separately rather than formatting them into SQL. Parameters replace values, not table or column names. The context manager closes the client when the block ends.

Use an async applicationCopy Anchor Link

Use AsyncClient when your application already runs an event loop:

import asyncio
from originchain import AsyncClient

async def main():
    async with AsyncClient.from_env() as db:
        result = await db.sql.run("SELECT $1 AS value", [7])
        print(result.rows)

asyncio.run(main())

Reuse the client for the service's lifetime. Await its network operations; do not create a new event loop inside an already running async handler.

Choose an operationCopy Anchor Link

The server's capabilities and your permissions determine which requests succeed. Usage and query metrics are available separately; advanced helpers vary by language.

Use the connection from ConnectCopy Anchor Link

Keep OC_TOKEN in your environment or secret manager. Use the credential offered for your database configuration, as explained in authentication. PostgreSQL logins and organization-management credentials are separate; they are not substitutes for this HTTP connection.

Search other data modelsCopy Anchor Link

These examples assume an open synchronous db and existing data. Use the matching async methods with await in an asynchronous application.

Full-text searchCopy Anchor Link

After indexing a text field, run a ranked search:

result = db.fts.search("documents", "body", "account setup", mode="bm25", k=10)
for hit in result.hits:
    print(hit.doc_id, hit.score)

Each doc_id identifies an indexed source document. A score ranks matches for this search; it is not a percentage of correctness. An empty hit list means this request found no matches. All search modes return hits and optional facets; unranked hits use a zero score.

Vector searchCopy Anchor Link

Use db.vector with embeddings from the same model and dimension as the stored data. Creating a client does not generate embeddings or populate an index. Follow the vector guide to prepare them.

Graph queriesCopy Anchor Link

Use db.graph after defining the relevant tables and relationships. The graph quickstart explains the data setup; Cypher parameters bind by name.

Read results and handle errorsCopy Anchor Link

sql.run keeps the full SQL outcome: rows, column metadata, confirmed write counts, buffered counts, nested results and the raw response. A missing count stays unknown.

• HTTP failures expose status and a request ID when the server supplies one.
• A batch can fail after earlier statements succeeded. Inspect the partial result before repeating it.
• A protocol error is not an empty result. Handle it as a failed response.
• Keep tokens and private rows out of diagnostic logs.

Numeric and date/time strings remain unchanged. Avoid converting values until your application knows the expected type and precision.

Timeouts and retriesCopy Anchor Link

The candidate's default timeout is 60 seconds and requests are not retried automatically. Explicit retry settings remain for existing integrations, but a timeout or 503 may follow a committed write. Cancellation stops waiting; it does not prove rollback.

Do not infer success from a result kind alone or treat a buffered count as a commit confirmation. See retry behavior.

ContinueCopy Anchor Link

The package and import name are both originchain. The separately generated originchaindb package is a different API.

SDK availability · SQL guide · HTTP API