SapixDB is the world's first agent-native database. It treats every record as a cryptographically signed nucleotide, hash-linked into an immutable strand — giving you built-in audit trails, time travel queries, and schema evolution without migrations.

How is SapixDB different from PostgreSQL or MongoDB?

Traditional databases store mutable rows with no built-in history. SapixDB is append-only by design: every write is cryptographically signed and linked to its predecessor. You get immutable audit trails, time travel, and agent-owned data ownership without external tooling.

Does SapixDB require schema migrations?

No. SapixDB uses Mutant-governed schema evolution — the schema evolves in place via versioned nucleotide types, never requiring ALTER TABLE or migration scripts.

Is SapixDB HIPAA and SOX compliant?

Yes. Because every record is cryptographically signed and immutably linked, SapixDB produces a tamper-evident audit trail natively. HIPAA data lineage and SOX financial audit requirements are satisfied at the storage layer without external compliance tooling.

How do I get started with SapixDB?

SapixDB is available as a Docker image. Run `docker compose up -d` and the agent starts on port 7475. Community is free forever. A 30-day Enterprise trial is available at sapixdb.com/trial — no credit card required.

Is there a free plan?

Yes. The Community plan is free forever with no expiry — up to 5 agents and 10 GB storage, including all core features: cryptographic strands, SaQL queries, time travel, HIPAA, SOX, graph, and blobs. Paid plans unlock higher limits and replication.

Community · SaQL

Aggregate Functions

Compute a single numeric result — total, average, extremes, or count — across all matching records in one round-trip using the aggregate query type.

Query Shape

All aggregate queries share the same structure. Send a POST to /v1/agents/:id/query with "type": "aggregate" plus the function name and the field to operate on.

SaQL — aggregate query shape

POST /v1/agents/:id/query
Authorization: Bearer spx_root_YOUR_ROOT_KEY
Content-Type: application/json

{
  "type":   "aggregate",
  "fn":     "sum | avg | min | max",
  "field":  "field_name",
  "filter": { ... }          // optional
}

Response Shape

The response contains a single aggregate object with the function name, field, computed value, and the number of records that contributed to the result.

JSON response

{
  "aggregate": {
    "fn_name":      "avg",
    "field":        "amount",
    "value":        247.50,
    "record_count": 18
  }
}

Key	Type	Description
`fn_name`	string	The function that was applied (`sum`, `avg`, `min`, or `max`).
`field`	string	The record field that was aggregated.
`value`	number \| null	The computed result. `null` when no matching records contained a numeric value for the field.
`record_count`	integer	Number of records included in the computation (after any filter).

sum — Total Value

Adds up all numeric values in field across matching records. Use this for revenue totals, byte counts, event counts with weights, and similar running totals.

SaQL — total revenue

{
  "type":  "aggregate",
  "fn":    "sum",
  "field": "amount"
}

curl

curl -s -X POST http://localhost:7475/v1/agents/orders/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer spx_root_YOUR_ROOT_KEY" \
  -d '{"type": "aggregate", "fn": "sum", "field": "amount"}' \
  | python3 -m json.tool

avg — Average Value

Returns the arithmetic mean of field across all matching records. Typical use cases include average order value, mean response latency, and average session length.

SaQL — average order value

{
  "type":  "aggregate",
  "fn":    "avg",
  "field": "amount"
}

min — Smallest Value

Finds the smallest value of field across all matching records. Useful for finding the cheapest product in a category, the earliest login timestamp, or the lowest error rate recorded.

SaQL — minimum order value

{
  "type":  "aggregate",
  "fn":    "min",
  "field": "amount"
}

max — Largest Value

Finds the largest value of field. Common uses: largest single order, peak concurrent users, highest recorded temperature.

SaQL — largest single order

{
  "type":  "aggregate",
  "fn":    "max",
  "field": "amount"
}

Counting records

Record counting is not part of the aggregate query type. Use the dedicated count query type instead — it accepts an optional filter and returns only the record count, with no payload transfer:

SaQL — count all records

{ "type": "count" }

SaQL — count with a filter

{
  "type":   "count",
  "filter": { "field": "plan", "op": "eq", "value": "pro" }
}

JSON response

{ "count": 42 }

Filtering Aggregates

Add a filter object to scope the aggregate to a subset of records. The same filter syntax used in scan queries applies here.

SaQL — average order value for pro plan

{
  "type":   "aggregate",
  "fn":     "avg",
  "field":  "amount",
  "filter": {
    "field": "plan",
    "op":    "eq",
    "value": "pro"
  }
}

SaQL — total revenue in Q2 2026

{
  "type":   "aggregate",
  "fn":     "sum",
  "field":  "amount",
  "filter": {
    "AND": [
      { "field": "created_at", "op": "gte", "value": "2026-04-01" },
      { "field": "created_at", "op": "lt",  "value": "2026-07-01" }
    ]
  }
}

Function Reference

fn	Operates on	Returns	Typical use
`sum`	numeric field	total	Revenue, bytes transferred, event weights
`avg`	numeric field	mean	Average order value, mean latency
`min`	numeric field	smallest	Lowest price, earliest timestamp
`max`	numeric field	largest	Peak load, largest order, max score

ℹ group_by counts per bucket; aggregate computes a scalarUse aggregate for a single number across the whole strand (total revenue, mean latency). Use group_by to count how many records share each unique field value (e.g. how many users are on each plan). See Group-By Queries.