feat(query): add AggregationQuery for FT.AGGREGATE

src/index.ts

@@ -37,6 +37,8 @@ export { CountQuery } from './query/count.js';
 export type { CountQueryConfig } from './query/count.js';
 export { TextQuery } from './query/text.js';
 export type { TextQueryConfig, TextScorer } from './query/text.js';
+export { AggregationQuery, Reducers } from './query/aggregation.js';
+export type { AggregateCommand, SortSpec, LoadField, Reducer } from './query/aggregation.js';
 export { Tag, Num, Text, Geo, GeoRadius, Timestamp, FilterExpression } from './query/filter.js';
 export type { Inclusive, GeoUnit } from './query/filter.js';
 export type {

src/indexes/search-index.ts

@@ -12,6 +12,7 @@ import { RedisVLError, SchemaValidationError } from '../errors.js';
 import type { BaseQuery, SearchResult, SearchDocument, QueryOptions } from '../query/base.js';
 import { VectorQuery } from '../query/vector.js';
 import { VectorRangeQuery } from '../query/range.js';
+import type { AggregationQuery } from '../query/aggregation.js';
 import { DISTANCE_NORMALIZERS } from '../utils/distance.js';
 import type { VectorFieldAttrs } from '../schema/fields.js';
 
@@ -655,4 +656,67 @@ export class SearchIndex {
             );
         }
     }
+
+    /**
+     * Execute an {@link AggregationQuery} (`FT.AGGREGATE`) against this index.
+     *
+     * Returns the raw aggregate result: a `total` row count and a list of
+     * rows, where each row is a `Record<string, string | string[]>` of field
+     * name to value. GROUPBY/REDUCE/APPLY aliases appear as keys on each row.
+     *
+     * Scalar reducers (`COUNT`, `SUM`, `AVG`, …) yield strings — numeric
+     * casting is the caller's job. List reducers (`TOLIST`) yield
+     * `string[]`, preserving the array structure Redis returns on the wire.
+     *
+     * @example
+     * ```typescript
+     * import { AggregationQuery, Reducers } from 'redis-vl';
+     *
+     * const q = new AggregationQuery('@category:{electronics}')
+     *   .groupBy('@brand', Reducers.sum('price', 'revenue'))
+     *   .sortBy([{ field: 'revenue', direction: 'DESC' }])
+     *   .limit(0, 5);
+     *
+     * const { total, results } = await index.aggregate(q);
+     * for (const row of results) console.log(row.brand, row.revenue);
+     * ```
+     */
+    async aggregate(
+        query: AggregationQuery
+    ): Promise<{ total: number; results: Array<Record<string, string | string[]>> }> {
+        try {
+            const { query: queryString, options } = query.toCommand();
+            const reply = await this.client.ft.aggregate(this.name, queryString, options);
+
+            // node-redis returns each row as a MapReply, which resolves to a
+            // plain object by default or to a real `Map` when the caller has
+            // opted into Map type-mapping via `client.withTypeMapping(...)`.
+            // Handle both shapes. Preserve array values verbatim (TOLIST
+            // returns string[]); coerce scalar non-strings via String() so
+            // numeric reducers come back as strings consistent with the
+            // FT.AGGREGATE wire format.
+            const results: Array<Record<string, string | string[]>> = reply.results.map((row) => {
+                const out: Record<string, string | string[]> = {};
+                const entries: Iterable<[string, unknown]> =
+                    row instanceof Map
+                        ? (row.entries() as Iterable<[string, unknown]>)
+                        : Object.entries(row as Record<string, unknown>);
+                for (const [k, v] of entries) {
+                    if (Array.isArray(v)) {
+                        out[k] = v.map((item) => (typeof item === 'string' ? item : String(item)));
+                    } else {
+                        out[k] = typeof v === 'string' ? v : String(v);
+                    }
+                }
+                return out;
+            });
+
+            return { total: reply.total, results };
+        } catch (error) {
+            throw new RedisVLError(
+                `Failed to execute aggregate query: ${error instanceof Error ? error.message : String(error)}`,
+                { cause: error instanceof Error ? error : undefined }
+            );
+        }
+    }
 }