OriginChain docs
by query shape · natural language

Natural language (Ask)

POST an English sentence; get rows back. The compiler folds the sentence into the same Plan tree SQL and /v1/query produce. The compiled plan is cached under intent|<question_hash> — the first call compiles, every repeat is a cache hit at p50 < 2 ms.

The compiler runs a deterministic rule grammar first. If the grammar can't resolve a phrase against the catalog, it falls back to an OpenAI-compatible chat endpoint configured at the instance — Bedrock, Anthropic, OpenAI, or a self-hosted Ollama.

endpoint
POST /v1/tenants/:tenant/ask
Content-Type: application/json
Authorization: Bearer $OC_TOKEN

{ "question": "last 10 orders where status is pending",
  "schemas":  ["shop.orders"] }

Ask a question.

schemas constrains the catalog the compiler can resolve against — pass the table ids your question is about. Omit it to allow every registered schema.

POST /v1/tenants/:t/ask 
curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/$T/ask" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "last 10 orders where status is pending",
    "schemas":  ["shop.orders"]
  }'
response
{
  "rows": [
    { "id": "o-481", "customer_id": "c_3", "amount": "129.50", "status": "pending" },
    ...
  ],
  "plan_cache": "hit",
  "elapsed_us": 1280
}

EXPLAIN the compiled plan.

Append ?explain=true to return the plan tree along with the rows. Useful for verifying the compiler picked the right shape, the right indexes, the right join order — before you wire the call into a hot path.

POST /v1/tenants/:t/ask?explain=true 
curl -X POST "https://acme.ap-south-1.db.originchain.ai/v1/tenants/$T/ask?explain=true" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "top 5 customers by revenue this quarter",
    "schemas":  ["shop.orders", "shop.customers"]
  }'

Plan cache.

The compiler hashes the canonicalised question and parameters, then looks up intent|<hash> before running the rule grammar or calling out to an LLM. A cache hit replays the cached Plan tree directly through the executor — same bytes, same operators, same indexes.

Schema migrations evict the affected entries on cutover. Manual eviction is exposed via the admin console.

Composition.

Ask compiles to the same Plan tree as SQL and /v1/query. A row written through any insert path is visible to Ask the moment the WAL fsyncs. For the operator catalog, see core concepts → plan tree.