"Database Query Reference"

Reference: Database Query Surface

Vox provides a built-in typed surface targeting the unified storage layer (Codex/Arca) via the standard db.* API domain.

Standard Table Fetch & Mutations

When you declare an @table type Model, the compiler auto-instantiates a db.Model handler namespace holding explicit data actions.

  • db.Model.all() -> list[Model]
    Retrieve every matched record in a table.
  • db.Model.find(id: Id[Model]) -> Option[Model]
    Extract a specific row given a compiler-tracked typed Identifier key.
  • db.Model.insert(fields) -> Id[Model]
    Insert mapping with schema constraints automatically typed and parameterized. ID is returned upon storage completion.
  • db.Model.update(id: Id[Model], diff) -> Unit
    Replaces explicit parameters targeted inside diff directly over the previously generated ID scope.
  • db.Model.delete(id: Id[Model]) -> Unit
    Removes row associated with that specific Identifier entirely.

Filters and Predicates

Query structures map to literal internal predicates mapped across your database indexes mapping securely. Note: Filtering and pagination requires appending .all() to trigger SQL fulfillment.

  • db.Model.filter({ field: val })
    Creates simple equality matches across the field table parameters.

    // vox:skip
db.User.filter({ age: 30 }).all()

  • db.Model.where({ field: { predicate } })
    Accepts complex structured parameter ranges such as gt, lt, eq, ne, in.

    // vox:skip
db.User.where({ age: { gt: 18, lt: 65 }, status: { ne: "blocked" } }).all()

Query Context Chaining

The Vox DB handler uses deterministic chained methods.

  • .order_by("field", "asc" | "desc")
    Orders results chronologically or structurally based on the explicit field value sequence.
  • .limit(n: int)
    Determines max response array element limits.
  • .select("field1", "field2")
    Performs column restrictions at query transit.

Chain Aggregation Example:

// vox:skip
return db.User
   .where({ role: { eq: "admin" } })
   .order_by("created_at", "desc")
   .limit(5)
   .all()

Advanced Storage Modifiers

These chainable context selectors modify how the operation interacts with the underlying Arca distribution:

  • .using("hybrid") / .using("fts") / .using("vector")
    Instructs VoxDb to use advanced indexing patterns (full-text or vector space).
  • .live("channel")
    Marks result sets as real-time subscriptions linked to a websocket client.
  • .scope("name")
    Isolates queries within multitenant architectures seamlessly.
  • .sync()
    Forces local edge SQLite consistency mapping back to global Turso control planes immediately.

Database Escape Hatch

  • db.query(sql: str, params: list[T]) -> list[Result] Allows writing explicit raw parameter-bound queries that entirely bypass the compiler's safety assertions. Designed exclusively for highly customized analytics scripts mapping across disparate tables.