Ask for a row count

The language tabs use earlier client interfaces. Check SDK versions and connection setup before running them.

Ask how many customers are in a table. The nl request field holds the question; the result contains database rows.

Before you run it: Ask availability, permissions and budgets depend on configuration. These endpoint recipes do not imply that every SDK provides Ask.

Count the sample customers with Ask AIThe sample contains three customers; the returned count should agree with those rows.

Three customer rowsLoad the sample into shop.customers.
Ask for the countName the table and ask how many customers it contains.
Inspect the answerCheck the returned count separately from cache information.

Follow the example

Confirm Ask is enabled for your configuration.
Load the sample customers.
Send the question in nl.
Read the count and cache metadata.

Set up the table

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

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

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

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

Load sample rows

Load the three sample customers before running the count.

# One-time seed of three customers - skip if you've already loaded data.
curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/rows/shop.customers/_batch" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    { "id": "c_1", "email": "alice@example.com", "region": "IN" },
    { "id": "c_2", "email": "bob@example.com",   "region": "US" },
    { "id": "c_3", "email": "carol@example.com", "region": "DE" }
  ]'

Run the request

curl -X POST "https://$OC_HOST/v1/tenants/$OC_TENANT/ask" \
  -H "Authorization: Bearer $OC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "nl": "how many customers do I have?"
  }'

Check the result

The count is based on stored rows. A cached plan still reads current data.

{
  "rows": [
    { "count": 3 }
  ],
  "cache": "miss"
}

Every Ask response has the same shape: rows (an array of objects keyed by column), cache ("hit", "miss", or "skip"), and an optional plan field when you asked for it.

How the database handles this request

The Ask endpoint canonicalises the question (lowercase, collapse whitespace) and looks it up in the plan cache keyed by question + schemas list.
First call is a miss. The compiler walks the registered schemas, recognises "how many" as a COUNT, and produces a Plan tree like Aggregate(count) → Scan(shop.customers).
The executor runs the plan and the count rolls up to one row.
The plan is stored under that cache key for next time - the actual rows are not cached, only the plan.

Important limits and checks

Sending "question" instead of "nl". The engine reads the body field nl. Anything else returns 400 missing_field.
Expecting the rows array to be cached. Cache hits replay the compiled plan, not the result set. If the underlying rows changed since the previous call, you'll see the new count on a "hit".
Ambiguous questions on a busy tenant. "How many customers" works if customers is the only obvious table. Once you have a crm.customers and a shop.customers, narrow the request with a schema hint.

Continue

Continue to choose the tables ask can use.

Follow the exampleCopy Anchor Link

Set up the tableCopy Anchor Link

Load sample rowsCopy Anchor Link

Run the requestCopy Anchor Link

Check the resultCopy Anchor Link

Important limits and checksCopy Anchor Link

ContinueCopy Anchor Link