Python SDK Quickstart

Create an organization, database, and API keys in the Onyx Cloud Console. Download your api key config file, and use the Onyx CLI to pull your schema and generate Python models.

Install the SDK from PyPI:

pip install onyx-database==2.4.0

Install the Onyx CLI (needed for schema pulls and codegen):

# Homebrew (macOS)
brew tap OnyxDevTools/onyx-cli
brew install onyx-cli

# Or install directly
curl -fsSL https://raw.githubusercontent.com/OnyxDevTools/onyx-cli/main/scripts/install.sh | bash

onyx version

Login to cloud.onyx.dev to create a database and an API key & secret.

Here is a minimal example schema:

{
  "tables": [
    {
      "name": "User",
      "identifier": {"name": "id", "generator": "UUID", "type": "String"},
      "type": "DEFAULT",
      "attributes": [
        {"name": "id","type": "String","maxSize": null,"isNullable": false},
        {"name": "status","type": "String","maxSize": null,"isNullable": false},
        {"name": "email", ...},
        {"name": "createdAt", ...}
      ]
    }
  ]
}

Set credentials using environment variables or a project config file.

Option A: Environment variables

export ONYX_DATABASE_ID="your-database-id"
export ONYX_DATABASE_API_KEY="key_abc"
export ONYX_DATABASE_API_SECRET="secret_xyz"

Option B: Project config file (onyx-database.json)

{
  "databaseId": "db_123",
  "baseUrl": "https://api.onyx.dev",
  "apiKey": "key_abc",
  "apiSecret": "secret_xyz"
}

Pull the schema and generate models + table helpers:

onyx schema get
onyx gen --py

Save first, then list records:

from onyx_database import onyx, eq, contains, asc

# Uses config resolution chain by default
db = onyx.init()

db.save("User", {
    "id": "user_123",
    "email": "alice@example.com",
    "status": "active",
})

active_users = (
    db.from_table("User")
      .where(eq("status", "active"))
      .and_(contains("email", "@example.com"))
      .order_by(asc("createdAt"))
      .limit(25)
      .list()
)

for user in active_users:
    print(user)

Use search-option keywords to select lexical, semantic, or hybrid retrieval. Lexical match="any" tolerates extra question words; semantic and hybrid modes use the database's configured embedding provider.

question = "how do i calculate cost per horse"

lexical = (
    db.from_table(tables.ActiveDocumentChunk)
      .search(
          question,
          mode="lexical",
          match="any",
          min_score=0.4,
          max_candidates=500,
      )
      .list()
)

semantic = (
    db.from_table(tables.ActiveDocumentChunk)
      .search(question, mode="semantic")
      .list()
)

hybrid = (
    db.from_table(tables.ActiveDocumentChunk)
      .search(question, mode="hybrid")
      .list()
)

Semantic and hybrid search require server-managed embeddings made with the same model and vector space. Resave or backfill older rows after enabling embeddings. A one-argument search(text) call deliberately keeps the legacy exhaustive lexical behavior.

Published model predictions

Train and publish a model in Model Builder, then predict from input objects or rows returned by a saved script. Use the REST prediction endpoints with your database credentials; the HTTP examples are separate from the SDK.

• GitHub: Onyx Python SDK
• PyPI: onyx-database