OriginChainDB docs
schema · natural language

Natural language.

Natural language lets you send a question instead of a query. The engine compiles it against the schemas you have registered, runs the result, and hands back rows — in the same shape any other read would.

It earns its place in two situations: exploration, when you don't yet know the shape of the data well enough to write the query, and end-user surfaces, where the person asking will never write a query at all. For anything on a hot path or in a code path you will maintain, write the SQL yourself — see when to use which.

1

Before you start.

Every example uses the shop.orders table from the quickstart. NL adds no schema syntax of its own — what it needs is that your tables are registered, because the column declarations are the entire context the compiler gets.

schemas/orders.toml
# NL has no schema knobs of its own. What it needs is that the tables you
# want it to reason about are REGISTERED - the compiler is given the column
# names and types of your schemas as its entire context, so a column that
# is not declared is a column it cannot use.

namespace   = "shop"
table       = "orders"
primary_key = ["id"]

[[columns]]
name = "id"
ty   = "str"
required = true

[[columns]]
name = "customer"
ty   = "str"

[[columns]]
name = "amount_cents"
ty   = "i64"

[[columns]]
name = "status"
ty   = "str"

[[columns]]
name = "notes"
ty   = "str"

[[columns]]
name = "placed_ms"
ty   = "u64"

# Not required by NL, but the compiled plan will use it like any other
# query would - so an indexed filter column makes the answer faster.
[[indexes]]
name    = "by_status"
columns = ["status"]
column names are your prompt

The compiler sees column names and types — nothing else. No sample rows, no comments, no descriptions. That makes naming load-bearing: amount_cents tells it far more than amt, and placed_ms tells it more than ts. If a question keeps compiling wrong, look at your column names before you look at your phrasing.

Related.