Choose the tables Ask can use

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

Pass a schemas list to limit the tables Ask considers. Each entry is a qualified table name, such as namespace.table.

Before you run it: Naming several schemas does not guarantee a SQL join. Use explicit SQL when the join must be predictable.

Keep a question focused on one tableThe schemas hint selects candidate tables; it does not filter their rows.

Choose shop.customersPass the table in the schemas list.
Ask about gold customersThe question supplies the condition to apply.
Check the plan and countConfirm that the intended table and tier were used.

Follow the example

Confirm Ask is available and load the sample.
Name the relevant table in schemas.
Ask for the gold-tier count.
Check the rows and generated plan.

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 = "tier"
ty   = "str"

[[indexes]]
name    = "by_tier"
columns = ["tier"]

Load sample rows

# Seed customers across two tiers so the count below is non-trivial.
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", "tier": "gold" },
    { "id": "c_2", "email": "bob@example.com",   "tier": "silver" },
    { "id": "c_3", "email": "carol@example.com", "tier": "gold" },
    { "id": "c_4", "email": "dan@example.com",   "tier": "silver" }
  ]'

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 gold-tier customers do I have?",
    "schemas": ["shop.customers"]
  }'

Check the result

The question is interpreted using the named tables rather than the entire catalog.

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

The shape is the same as the unhinted call - rows and cache. The difference is that the compiler walked one schema, not the whole tenant.

How the database handles this request

The schemas list is part of the cache key - same question, different schemas list, different entry.
The compiler sees only the listed schemas in its catalog. Tables in other namespaces are invisible for this call.
Recognising "gold-tier" hits the tier column. Because there's a by_tier index, the plan becomes Aggregate(count) → IndexScan(tier = "gold").
A shorter schema list gives the compiler fewer table definitions to consider. It does not guarantee a faster response or a supported join.

Important limits and checks

Assuming multiple tables imply a join. The list supplies context, not permission to generate every SQL join. Compare with a known SQL result when relationships matter.
Bare table name without namespace. Schemas are addressed as namespace.table. "customers" alone returns 400 unknown_schema.
Using a hint as a data filter. The list chooses tables; it does not filter rows within them. Inspect the returned plan and count to confirm that the question selected the intended records.

Continue

Continue to inspect how ask answers.

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