Architecture

Inside the Onyx AI-Controlled Database Cloud

A system designed around control, not commands.

Onyx is built as a layered system that separates data storage, relationship definition, and data work orchestration. This separation allows each layer to be optimized independently, making AI-directed data workflows possible without sacrificing predictability or trust.

The AI Control Plane

Orchestration

What it does:

  • Understands intent (natural language or API)
  • Plans safe, explicit operations
  • Generates queries & workflows
  • Requires approval before execution
Ask questions, don’t write queries
const answer = await db.chat(
  "Tell me about my data"
)

The Relationship Layer

Relationships are declared at the schema level and resolved dynamically. No foreign keys. No pre-materialized joins. No graph migrations.

schema.json
"...
resolvers": [
  {
    "name": "roles",
    "resolver": "db.from("Role")
      .where(eq("userId", this.id))
      .list()"
  }
]
...

Relationships are executable logic — not storage constraints.

The Data Plane

What it guarantees:

  • Atomic Saves
  • Fist class performance
  • index-backed queries
  • modern solid state storage
No magic, just data
await db.save({
  table: tables.User,
  values: {
    id: userId,
    name: "Chris"
  }
})

const users = await db
  .from(tables.User)
  .where(eq("status", "active"))
  .and(gt("createdAt", lastWeek))
  .limit(50)
  .list()

The Execution Lifecycle

1

User expresses intent

2

Control plane plans a workflow

3

Queries are generated and executed, mutations are generated and executed with human-in-the-loop approval

4

Approved steps are executed by the data plane

5

Outputs are materialized and indexed

Results are returned, visualized, or persisted. Every action is explainable, reviewable, and repeatable.

Performance Model

To avoid common performance pitfalls, Onyx employs:

  • Indexed reference assignment for relationship resolution
  • Multidimensional hash-based lookup
  • Skip-list–backed traversal structures

Relationship resolution is computed once and reused across traversals, avoiding N+1 patterns while preserving flexibility. Optimized for SSD-backed access.

Failure and Recovery

Because workflows are explicit and persisted:

  • Partial execution can be resumed
  • Failed steps are isolated
  • Downstream effects are controlled

This makes data work resilient by design, not by convention.

End-to-End Example: Exploring Customer Behavior

01. Define Schema

You define entities: Customer, Account, Transaction, SupportTicket.
No rigid foreign keys are required.

02. Define Relationships

Relationships are defined via logical resolvers (e.g., Ownership, Activity Windows, Inferred Identity). These are logical, not physical.

03. Express Intent

“Show me customers with declining transaction volume who also opened support tickets in the last 30 days.”

This is not a query. It is intent.

04. Workflow Planning

  • Identify customers with declining trends
  • Resolve related accounts & transactions
  • Resolve related support tickets (time-bound)
  • Join results at customer level
  • Generate stats & visualization data

05. Human Review

The user prompts, the system generates queries, and the user approves execution.
No data changes without approval.

06 & 07. Execution & Persistence

Execution produces a statistical summary, ranked dataset, and narrative explanation. The workflow is then saved as a script to be rerun, shared, or used as a dashboard backend.

Key Concepts

Resolver-Defined Relationships

Relationships are defined by schema-level resolver queries, not static edges.

Workflows

Data interaction is modeled as a tree of steps, not isolated commands.

Control Plane

An AI-driven control plane plans workflows, with humans approving every action.

Outputs

Workflows produce reusable outputs, including datasets, summaries, and visualizations.

Data work as a controlled, repeatable workflow — not a pile of queries.

Back to HomeHow Onyx Works