Natural Language Queries

What you'll learn

Query SapixDB in plain English using the NL pipeline — no SaQL required.

NL query endpoint

curl -s -X POST http://localhost:7475/v1/agents/orders/nl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{"question": "Show me the 5 most recent paid orders over $100"}' \
  | python3 -m json.tool

How the NL pipeline works

1. Heuristic planner — fast pattern matching for common phrases ("latest", "count of", "between X and Y"). No LLM call.
2. LLM planner — for complex questions, calls the configured LLM to generate SaQL JSON.
3. NL cache — repeated identical questions are served from cache without rerunning the planner.

Response shape

{
  "question":    "Show me the 5 most recent paid orders over $100",
  "saql":        {"type": "scan", "limit": 5, "order": "desc", "filter": {"AND": [...]}},
  "source":      "heuristic | llm | cache",
  "records":     [ ... ]
}

The saql field shows exactly which query was generated — great for debugging.

Configure the LLM backend (optional)

# docker-compose.yml
environment:
  SAPIX_NL_PROVIDER:  openai
  SAPIX_NL_API_KEY:   sk-...
  SAPIX_NL_MODEL:     gpt-4o

Without LLM configuration, only the heuristic planner runs.

Challenge

Try 5 different natural language questions against an agent with varied records. Observe the source field — which ones hit the heuristic planner vs. the LLM?

---