feat(query): add AggregationQuery for FT.AGGREGATE

[ajGingrich]

Summary

Adds AggregationQuery + SearchIndex.aggregate(), closing the last major gap on the query surface. Mirrors Python redisvl's AggregationQuery (base class only — the hybrid text+vector subclass is out of scope since HybridQuery already covers FT.HYBRID).

• Fluent builder: groupBy / apply / sortBy / limit / filter / load / params / dialect / timeout / verbatim / addScores. Steps render in the order they're called, mirroring the FT.AGGREGATE pipeline.
• Reducers namespace exposes factory functions for COUNT, COUNT_DISTINCT, COUNT_DISTINCTISH, SUM, MIN, MAX, AVG, STDDEV, QUANTILE, TOLIST, FIRST_VALUE, RANDOM_SAMPLE — each takes an optional as alias.
• Constructor accepts FilterInput (string | FilterExpression) for the pre-aggregation filter, matching the rest of the DSL.
• Result shape: { total, results } where each row is Record<string, string>. Numeric casting is left to the caller — Redis hands back string values over the wire.

Why

Issue #15. After the filter DSL PR landed FilterQuery/CountQuery/VectorRangeQuery/TextQuery (all on FT.SEARCH), FT.AGGREGATE was the next missing primitive. Python redisvl exposes it as a first-class peer; TS users currently have to drop down to the raw client.ft.aggregate() API.

Notable design choices

• Fluent vs config-object. Used a chainable builder because FT.AGGREGATE is inherently pipeline-shaped (each step operates on the previous step's output). This matches Python redisvl and feels natural for analytics-style queries. (HybridQuery is config-object because it's flat configuration of a single command.)
• Hybrid aggregation out of scope. Python redisvl has AggregateHybridQuery subclassing AggregationQuery for text+vector via FT.AGGREGATE. Our hybrid story is FT.HYBRID via HybridQuery, so the analogue isn't needed.
• Returns raw rows, not SearchDocuments. Aggregation rows aren't documents — they're computed groupings. The reducer aliases are the column names, and values come back as strings (FT.AGGREGATE wire format). Numeric casting is the caller's job.

Test plan

• Unit tests (25) — option-shape assertions across every step kind + validation edge cases. npx vitest run --config vitest.unit.config.ts tests/unit/query/aggregation.test.ts
• Type check — npm run type-check and npm run type-check:tests both clean.
• Prettier formatted.
• Integration tests (5) — against a real Redis 8.x. Run with npm test. (Couldn't exercise the Testcontainer locally; relying on CI.)

Docs

New user guide at website/docs/user-guide/aggregation.md, added to the User Guide sidebar between advanced-vector-search and vectorizers.

Closes #15

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a fluent AggregationQuery builder plus a SearchIndex.aggregate() method to expose FT.AGGREGATE as a first-class query type, closing the last major gap on the query surface. The builder records pipeline steps (GROUPBY / APPLY / SORTBY / LIMIT / FILTER) in call order and ships a Reducers namespace of factory functions. Unit + integration tests and a docs page round it out.

Changes:

• New AggregationQuery class + Reducers factory namespace in src/query/aggregation.ts, re-exported from the package root.
• New SearchIndex.aggregate() that runs the command and normalizes RESP2/RESP3 row shapes.
• Unit tests, an integration test, a user-guide doc, and a sidebar entry.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 9 comments.

Show a summary per file

File	Description
src/query/aggregation.ts	New builder, reducer factories, step rendering, validation.
src/indexes/search-index.ts	New aggregate() method on the index; row normalization.
src/index.ts	Re-exports of the new public surface.
src/query/index.ts	Barrel export for aggregation.ts.
tests/unit/query/aggregation.test.ts	25 unit tests for option-shape assertions and validation.
tests/unit/indexes/search-index.test.ts	Mock-based aggregate() tests (TOLIST, Map rows, GROUPBY 0).
tests/integration/aggregation.test.ts	End-to-end tests against a real Redis.
website/docs/user-guide/aggregation.md	New user-guide page with examples and API table.
website/sidebars.ts	Inserts the new doc into the user-guide sidebar.

Comments suppressed due to low confidence (1)

website/docs/user-guide/aggregation.md:166

• Same broken ./hybrid-search.md link as on line 9 — the file doesn't exist in the docs tree.

- [Hybrid search](./hybrid-search.md) — text + vector fusion via `FT.HYBRID`.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

website/docs/user-guide/aggregation.md:164

• Same documentation mismatch as above: the row type is described as Array<Record<string, string>> but aggregate() actually returns Array<Record<string, string | string[]>>. The advice "If you need numeric types, cast at the call site" is also misleading for TOLIST/array reducers, since those values are arrays rather than strings to be cast.

```typescript
const { total, results } = await index.aggregate(q);
// total:   number — the row count Redis reports after aggregation
// results: Array<Record<string, string>> — one entry per emitted row

If you need numeric types, cast at the call site (Number(row.revenue)). Aggregation reducers preserve numeric precision on the server side; the wire format simply hands them back as strings.

</details>