11
Querying with SaQLSaQL Basics
The SaQL query language: all query types, the request shape, and basic filter syntax.
Prerequisite: Lesson 6 complete
What you'll learn
- ✓POST /v1/agents/:id/query — the universal query endpoint
- ✓All 12 query types: latest, first, scan, count, chain_head, as_of, time_range, distinct, aggregate, group_by, explain, join
- ✓Filter shape: {field, op, value}
- ✓Combining filter with limit, order, after_hlc, select
Challenge
Write 10 records to products agent with category and price. Count how many have category = 'electronics'.
Interactive Walkthrough
What you'll learn
The SaQL query language: query types, the request shape, and the basic filter syntax.
SaQL request shape
All SaQL queries are POST /v1/agents/:id/query with a JSON body:
{
"type": "latest | first | scan | count | chain_head | as_of | time_range | ...",
"limit": 20,
"filter": { ... },
"order": "asc | desc",
"after_hlc": 0,
"select": ["field1", "field2"]
}All query types
| Type | Returns |
|---|---|
latest | Newest N records |
first | Oldest N records |
scan | Full strand, windowed |
count | Integer only |
chain_head | Single tip record |
as_of | Records up to a timestamp |
time_range | Records in a time window |
distinct | Unique values for a field |
aggregate | sum/avg/min/max/count across a field |
group_by | Count/aggregate per group |
explain | Query plan without executing |
join | Inner join across two agents |
Simple filter
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.toolcount with filter
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": "count",
"filter": {"field": "plan", "op": "eq", "value": "enterprise"}
}' | python3 -m json.toolChallenge
Write 10 records to a products agent with varying category and price fields. Count how many have category = "electronics".
---