Ask your first question
Ask a plain-language question about a table you already know. This walkthrough uses the quickstart product record, then checks the generated query and returned rows. Ask requires the relevant instance configuration; it is not guaranteed on every deployment.
- Load the sample productKeep the Trail mug row and its price in cents.
- Ask about product pricesRequest the highest-priced products in the selected table.
- Inspect the returned planCheck the price field, descending order and requested limit.
- Compare the returned rowConfirm the Trail mug value matches the sample data.
1. Prepare known data
Complete the HTTP quickstart. It creates quickstart.products and the Trail mug record. Keep the complete OC_URL and OC_TOKEN from that setup. Do not add tenant path segments yourself. Confirm that the instance exposes the Ask endpoint before continuing. Add database identity headers when required.
2. Ask a scoped question
curl --fail-with-body -X POST "$OC_URL/ask" \
-H "Authorization: Bearer $OC_TOKEN" -H "Content-Type: application/json" \
-d '{"nl":"top 5 quickstart.products by price_cents desc","schemas":["quickstart.products"],"show_plan":true}'nl is the question; schemas narrows the catalog. show_plan returns the plan alongside the rows. It still executes the question; it is not a dry run.
3. Check the answer
Confirm the plan names quickstart.products, sorts price_cents descending and limits the result to five. With only the quickstart fixture, the result includes Trail mug. Compare the answer with an explicit SQL query when correctness matters.
A successful response is not proof that natural language preserved every condition. Check filters, grouping, units, ordering and null behavior. An empty result can be a valid answer or a misunderstood question.
4. Understand the compiler
A deterministic grammar handles supported simple questions first. A configured language model can handle questions outside that grammar. If fallback is unavailable or compilation fails, show the returned error rather than inventing an answer. Review what question and schema context is sent to the configured provider.
The prompt grammar covers scans, projections, filters, distinct values, sorting, limits, common aggregates and relation hops. It does not promise that arbitrary SQL, joins, CTEs or graph algorithms can be generated from any question. Use explicit SQL or graph endpoints for a query shape you need to control.
5. Treat caching as an optimization
The cache field reports plan reuse, not a cached answer. Rows are queried again. Schema and authorization context affect reuse; do not depend on a particular cache outcome for application correctness. Do not re-register a schema solely to force a cache miss.
Use the right client surface
Use the HTTP request shown above for the documented Ask options. SDK publication and helper support differ by version; do not assume a private or unpublished client exposes this feature. Check the SDK directory and Ask reference.
The console’s Ask AI assistance is a separate workflow. Do not infer its availability or execution controls from the engine’s /ask endpoint.