Natural language (Ask)
Ask turns a plain-language question into a database query. Start with one question about a known table, then check the query and the returned rows.
Ask first tries built-in rules to match your question to the database schema: the names and types of its tables and fields. If those rules cannot resolve it, Ask can use the language model configured on your instance. It can reuse a saved query plan for a repeated question.
- Choose the tablesLimit the question to the data you need.
- Ask in plain languageName the fields, filters or totals you want.
- Inspect the executed planCheck which tables and conditions it used.
- Verify the answerCompare returned rows with records you already know.
1. Ask a question.
Send the question in nl. Use schemas to name the tables it should consider. If you omit it, Ask considers the catalog available to the active database identity.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nl": "last 10 orders where status is pending",
"schemas": ["shop.orders"]
}'| Field | Required | Notes |
|---|---|---|
| nl | yes | The question in plain English. Aim for one sentence - multi-step questions are best split. |
| schemas | no | Array of schema names to consider. Omitting it allows all schemas but is slower for large catalogs. |
| show_plan | no | When true, the response includes the executed plan tree. |
- Ambiguous column references. "Top customers by amount" doesn't say whether "amount" is per-order or aggregated. Be specific: "top customers by total order amount".
- Not scoping schemas. If you know the question is only about orders, pass
schemas=["shop.orders"]- the compiler is faster and less likely to pick the wrong table. - Sensitive data in questions. If you fall back to the LLM, the question gets sent to whatever LLM is configured. Don't put PII or secrets in the question.
2. Inspect the plan.
Set show_plan: true to see how Ask reads the data. A query plan lists steps such as scanning a table, filtering rows and calculating totals. Check that it uses the intended table and conditions before reusing the question in an application.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
-H "Authorization: Bearer $OC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"nl": "top 5 customers by total spend",
"schemas": ["shop.orders", "shop.customers"],
"show_plan": true
}'{
"rows": [
{ "customer_id": "c_3", "total": 124900 },
{ "customer_id": "c_7", "total": 98200 },
...
],
"cache": "miss",
"plan": { "kind": "Aggregate", "by": ["customer_id"], ... }
}For the operator catalog (Scan, Filter, HashJoin, Aggregate, etc.), see the query reference.
3. The plan cache.
Every response includes a cache field with one of three values:
| Value | What happened |
|---|---|
| "hit" | Cached plan was reused. Fast. |
| "miss" | First time seeing this question (or close to it). Compiled fresh, then cached. |
| "skip" | Cache was bypassed, usually because schemas were modified since the entry was cached. |
Plan reuse depends on schema and authorization context. Do not re-register a schema just to clear the cache; use show_plan to inspect the query and verify its rows against an explicit query.