Single-Field Indexes

What you'll learn

Create an index on a single field, understand when SapixDB uses it, and verify with explain.

Without an index

Without an index, every filtered query does a full strand scan — O(n). Fine for small strands. Slow at 100k+ records.

Create a single-field index

curl -s -X POST http://localhost:7475/v1/agents/users/indexes \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{
    "name":  "idx_plan",
    "field": "plan"
  }' | python3 -m json.tool

The index is built asynchronously in the background. Status:

curl -s http://localhost:7475/v1/agents/users/indexes \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  | python3 -m json.tool

Query using the index (automatic)

# SapixDB automatically uses idx_plan for eq/in/starts_with filters on 'plan'
curl -s -X POST http://localhost:7475/v1/agents/users/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{"type": "scan", "limit": 50, "filter": {"field": "plan", "op": "eq", "value": "pro"}}' \
  | python3 -m json.tool

You do not name the index in the query — the engine picks it automatically when it sees a filter on an indexed field.

Challenge

Create an index on email for the users agent. Write 50 users. Query by exact email match and verify with explain (Lesson 21) that the index was used.

---