Python SDK Quickstart

The onyx-database Python SDK works with onyx cli generated models. It resolves credentials via config files, environment variables, or explicit config and supports Python 3.11+.

Looking for other supported sdks?

TypeScript Python Go Kotlin

Overview

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

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

Create a database and publish a schema

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", ...}
      ]
    }
  ]
}

Configure credentials

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"
}

Generate Python models

Pull the schema and generate models + table helpers:

onyx schema get
onyx gen --py

Save and query data

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)

Search natural language

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.

What else can I do?

Atomic Saving Resolvers Bulk Save Query & Filter Inner Queries Aggregations Streaming Queries Full-Text Search Pagination AI Chat

Resources

Next Steps

Open the Python SDK Reference

Browse Onyx Examples

Try the Onyx CLI

Need Help?

If you have any questions or need assistance:

Email:support@onyx.dev
Documentation: Visit ourHelp Centerfor tutorials and FAQs.

Contact Support