@onchaindb/sdk 2.0.1 → 2.1.1

package/src/query-sdk/QueryBuilder.ts

@@ -3,7 +3,7 @@ import {QueryValue} from './index';
 import {FieldConditionBuilder, LogicalOperator} from './operators';
 import {SelectionBuilder} from './SelectionBuilder';
 import {ConditionBuilder} from './ConditionBuilder';
-import {FieldMap, HttpClient} from "./index";
+import {FieldMap, HttpClient, AggregateSpec} from "./index";
 import {AxiosError} from "axios";
 import {
     X402PaymentRequiredResponse,
@@ -22,13 +22,6 @@ export interface ServerJoinConfig {
     };
 }
 
-// DEPRECATED: Client-side join configuration (kept for backward compatibility)
-export interface JoinConfig {
-    parentCollection: string;
-    parentField: string;
-    childField: string;
-    alias: string;
-}
 
 // Main query builder providing fluent API for building queries
 export class QueryBuilder {
@@ -37,15 +30,16 @@ export class QueryBuilder {
     private fieldMap?: FieldMap;
     private limitValue?: number;
     private offsetValue?: number;
-    private sortBy?: string;
+    private _sortField?: string;
     private sortDirection?: string;
     private includeHistoryValue?: boolean;
     private httpClient?: HttpClient;
     private serverUrl?: string;
     private collectionName: string | undefined;
     private app: string | undefined;
-    private serverJoinConfigs: ServerJoinConfig[] = [];  // Server-side JOINs (Scepter)
-    private joinConfigs: JoinConfig[] = [];  // DEPRECATED: Client-side JOINs
+    private serverJoinConfigs: ServerJoinConfig[] = [];
+    private _groupBy?: string[];
+    private _aggregate?: AggregateSpec;
 
     constructor(httpClient?: HttpClient, serverUrl?: string, app?: string) {
         this.httpClient = httpClient;
@@ -115,18 +109,6 @@ export class QueryBuilder {
         return new JoinBuilder(this, alias, model, true);  // many = true
     }
 
-    // DEPRECATED: Client-side join (uses Promise.all to fetch related data)
-    // Use serverJoin(), joinWith(), joinOne(), or joinMany() instead for better performance
-    join(parentCollection: string, parentField: string, childField: string, alias: string): QueryBuilder {
-        console.warn('QueryBuilder.join() is deprecated. Use serverJoin(), joinOne(), or joinMany() for server-side JOINs.');
-        this.joinConfigs.push({
-            parentCollection,
-            parentField,
-            childField,
-            alias
-        });
-        return this;
-    }
 
     // Build selections using a builder function
     select(builderFn: (builder: SelectionBuilder) => SelectionBuilder): QueryBuilder {
@@ -162,29 +144,31 @@ export class QueryBuilder {
         return this;
     }
 
+    /** Alias for limit(). */
+    take(n: number): QueryBuilder { return this.limit(n); }
+
     // Set offset for results
     offset(offset: number): QueryBuilder {
         this.offsetValue = offset;
         return this;
     }
 
-    // Set sorting fields
-    orderBy(fields: string, direction?: "ASC" | "DESC"): QueryBuilder {
-        this.sortBy = fields;
-        switch (direction) {
-            case "ASC":
-                this.sortDirection = "ascending";
-                break;
-                case "DESC":
-                    this.sortDirection = "descending";
-                    break;
-            default:
-                this.sortDirection = "ascending";
-        }
+    /** Alias for offset(). */
+    skip(n: number): QueryBuilder { return this.offset(n); }
 
+    // Set sort field and direction (accepts "asc"/"desc" or "ASC"/"DESC")
+    sortBy(field: string, direction?: "asc" | "desc" | "ASC" | "DESC"): QueryBuilder {
+        this._sortField = field;
+        const dir = direction?.toLowerCase();
+        this.sortDirection = dir === "desc" ? "descending" : "ascending";
         return this;
     }
 
+    // Alias kept for backward compatibility
+    orderBy(field: string, direction?: "ASC" | "DESC"): QueryBuilder {
+        return this.sortBy(field, direction);
+    }
+
     // Include all versions of records in query results (default: false, returns only latest versions)
     // When true, returns all historical versions of each record
     // When false or not called (default), returns only the most recent version of each record
@@ -202,18 +186,6 @@ export class QueryBuilder {
             throw new Error('Server URL is required for query execution');
         }
 
-        // Server-side JOINs are embedded in the query structure and handled by the backend
-        if (this.serverJoinConfigs.length > 0) {
-            return this.executeSimpleQuery<T>();
-        }
-
-        // DEPRECATED: Client-side joins using Promise.all
-        if (this.joinConfigs.length > 0) {
-            console.warn('Using deprecated client-side JOINs. Consider migrating to serverJoin() for better performance.');
-            return this.executeWithJoins<T>();
-        }
-
-        // No joins, execute as a normal query
         return this.executeSimpleQuery<T>();
     }
 
@@ -277,8 +249,12 @@ export class QueryBuilder {
      * ```
      */
     async count(): Promise<number> {
-        const response = await this.execute();
-        return response.records?.length || 0;
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate({ _count: { '$count': '*' } });
+        const response = await clone.execute();
+        const first = response.records?.[0] as any;
+        return first?._count ?? 0;
     }
 
     /**
@@ -296,13 +272,12 @@ export class QueryBuilder {
      * ```
      */
     async sumBy(field: string): Promise<number> {
-        const response = await this.execute();
-        if (!response.records) return 0;
-
-        return response.records.reduce((sum: number, record: any) => {
-            const value = record[field];
-            return sum + (typeof value === 'number' ? value : 0);
-        }, 0);
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$sum': field } });
+        const response = await clone.execute();
+        const first = response.records?.[0] as any;
+        return first?._result ?? 0;
     }
 
     /**
@@ -320,15 +295,12 @@ export class QueryBuilder {
      * ```
      */
     async avgBy(field: string): Promise<number> {
-        const response = await this.execute();
-        if (!response.records || response.records.length === 0) return 0;
-
-        const sum = response.records.reduce((total: number, record: any) => {
-            const value = record[field];
-            return total + (typeof value === 'number' ? value : 0);
-        }, 0);
-
-        return sum / response.records.length;
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$avg': field } });
+        const response = await clone.execute();
+        const first = response.records?.[0] as any;
+        return first?._result ?? 0;
     }
 
     /**
@@ -345,14 +317,12 @@ export class QueryBuilder {
      * ```
      */
     async maxBy<T = any>(field: string): Promise<T | null> {
-        const response = await this.execute();
-        if (!response.records || response.records.length === 0) return null;
-
-        return response.records.reduce((max: any, record: any) => {
-            const value = record[field];
-            if (max === null) return value;
-            return value > max ? value : max;
-        }, null);
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$max': field } });
+        const response = await clone.execute();
+        const first = response.records?.[0] as any;
+        return first?._result ?? null;
     }
 
     /**
@@ -369,14 +339,12 @@ export class QueryBuilder {
      * ```
      */
     async minBy<T = any>(field: string): Promise<T | null> {
-        const response = await this.execute();
-        if (!response.records || response.records.length === 0) return null;
-
-        return response.records.reduce((min: any, record: any) => {
-            const value = record[field];
-            if (min === null) return value;
-            return value < min ? value : min;
-        }, null);
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$min': field } });
+        const response = await clone.execute();
+        const first = response.records?.[0] as any;
+        return first?._result ?? null;
     }
 
     /**
@@ -421,8 +389,46 @@ export class QueryBuilder {
      * ```
      */
     async countDistinct(field: string): Promise<number> {
-        const distinctValues = await this.distinctBy(field);
-        return distinctValues.length;
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$countDistinct': field } });
+        const response = await clone.execute();
+        const first = response.records?.[0] as any;
+        return first?._result ?? 0;
+    }
+
+    /**
+     * Run multiple aggregations in a single HTTP round-trip.
+     *
+     * Each key in `spec` becomes an output alias in the returned record.
+     * Supported operators: `$count`, `$sum`, `$avg`, `$max`, `$min`, `$countDistinct`.
+     * Use `'*'` as the field value for `$count`.
+     *
+     * @param spec - Map of output alias to `{ '$op': 'field' }` descriptor
+     * @returns Promise resolving to a single record containing all requested aggregation results
+     *
+     * @example
+     * ```typescript
+     * const stats = await db.queryBuilder()
+     *   .collection('posts')
+     *   .whereField('category').equals('technology')
+     *   .runAggregate({
+     *     total:        { '$count': '*' },
+     *     totalLikes:   { '$sum': 'likes' },
+     *     avgLikes:     { '$avg': 'likes' },
+     *     maxLikes:     { '$max': 'likes' },
+     *     minLikes:     { '$min': 'likes' },
+     *     uniqueAuthors: { '$countDistinct': 'author_id' }
+     *   });
+     * // Returns: { total: 4, totalLikes: 203, avgLikes: 50.75, maxLikes: 67, minLikes: 38, uniqueAuthors: 2 }
+     * ```
+     */
+    async runAggregate(spec: AggregateSpec): Promise<Record<string, any>> {
+        const clone = this.clone();
+        clone._setSelections({});
+        clone._setAggregate(spec);
+        const response = await clone.execute();
+        return (response.records?.[0] as any) ?? {};
     }
 
     /**
@@ -510,7 +516,7 @@ export class QueryBuilder {
             ...queryValue,
             limit: this.limitValue,
             offset: this.offsetValue,
-            sortBy: this.sortBy,
+            sortBy: this._sortField,
             sortDirection: this.sortDirection,
             root: `${this.app}::${this.collectionName}`
         };
@@ -528,7 +534,7 @@ export class QueryBuilder {
             ...this.buildQueryValue(),
             limit: this.limitValue,
             offset: this.offsetValue,
-            sortBy: this.sortBy,
+            sortBy: this._sortField,
             sortDirection: this.sortDirection,
         };
     }
@@ -541,12 +547,13 @@ export class QueryBuilder {
         cloned.fieldMap = this.fieldMap ? {...this.fieldMap} : undefined;
         cloned.limitValue = this.limitValue;
         cloned.offsetValue = this.offsetValue;
-        cloned.sortBy = this.sortBy;
+        cloned._sortField = this._sortField;
         cloned.sortDirection = this.sortDirection;
         cloned.includeHistoryValue = this.includeHistoryValue;
         cloned.collectionName = this.collectionName;
-        cloned.serverJoinConfigs = [...this.serverJoinConfigs]; // Deep copy server join configs
-        cloned.joinConfigs = [...this.joinConfigs]; // Deep copy client join configs (deprecated)
+        cloned.serverJoinConfigs = [...this.serverJoinConfigs];
+        cloned._groupBy = this._groupBy ? [...this._groupBy] : undefined;
+        cloned._aggregate = this._aggregate ? {...this._aggregate} : undefined;
         return cloned;
     }
 
@@ -555,6 +562,22 @@ export class QueryBuilder {
         this.serverJoinConfigs.push(config);
     }
 
+    // Internal helpers used by aggregation methods and GroupByQueryBuilder after cloning
+    _setSelections(select: SelectionMap): this {
+        this.selections = select;
+        return this;
+    }
+
+    _setGroupBy(fields: string[]): this {
+        this._groupBy = fields;
+        return this;
+    }
+
+    _setAggregate(agg: AggregateSpec): this {
+        this._aggregate = agg;
+        return this;
+    }
+
     // Execute a simple query without joins
     private async executeSimpleQuery<T extends Record<string, any>>(): Promise<QueryResponse<T>> {
         const request = this.getQueryRequest();
@@ -601,73 +624,6 @@ export class QueryBuilder {
         }
     }
 
-    // Execute query with joins using parallel queries
-    private async executeWithJoins<T extends Record<string, any>>(): Promise<QueryResponse<T>> {
-        // First, get the main collection records
-        const mainQuery = this.clone();
-        mainQuery.joinConfigs = []; // Remove joins for main query
-        const mainResults = await mainQuery.executeSimpleQuery();
-
-        if (mainResults.records.length === 0) {
-            return mainResults as QueryResponse<T>;
-        }
-
-        // For each join, execute parallel queries and merge results
-        const joinResults: Record<string, any[]> = {};
-
-        for (const joinConfig of this.joinConfigs) {
-            // Get all unique values from the main results for the join key
-            const joinKeys = [...new Set(
-                mainResults.records
-                    .map(record => record[joinConfig.childField])
-                    .filter(key => key !== null && key !== undefined)
-            )];
-
-            if (joinKeys.length > 0) {
-                // Query the joined collection
-                const joinQuery = new QueryBuilder(this.httpClient, this.serverUrl, this.app);
-                const joinResponse = await joinQuery
-                    .collection(joinConfig.parentCollection)
-                    .whereField(joinConfig.parentField).in(joinKeys)
-                    .selectAll()
-                    .executeSimpleQuery();
-
-                joinResults[joinConfig.alias] = joinResponse.records;
-            } else {
-                joinResults[joinConfig.alias] = [];
-            }
-        }
-
-        // Merge join results with main results
-        const mergedRecords = mainResults.records.map(mainRecord => {
-            const merged: any = {...mainRecord};
-
-            for (const joinConfig of this.joinConfigs) {
-                const joinKey = mainRecord[joinConfig.childField];
-                const relatedRecords = joinResults[joinConfig.alias].filter(
-                    joinRecord => joinRecord[joinConfig.parentField] === joinKey
-                );
-
-                // For one-to-many relationships, return array; for many-to-one, return single object
-                if (joinConfig.parentCollection === this.collectionName) {
-                    // Self-referential join (like replies to tweets)
-                    merged[joinConfig.alias] = relatedRecords;
-                } else {
-                    // Cross-collection join
-                    merged[joinConfig.alias] = relatedRecords.length > 0 ? relatedRecords[0] : null;
-                }
-            }
-
-            return merged;
-        });
-
-        return {
-            records: mergedRecords,
-            limit: mainResults.limit,
-            page: mainResults.page,
-            total: mainResults.total
-        } as QueryResponse<T>;
-    }
 
     // Build the query value object for HTTP requests
     private buildQueryValue(): QueryValue {
@@ -704,6 +660,21 @@ export class QueryBuilder {
             queryValue.include_history = this.includeHistoryValue;
         }
 
+        // Send fieldMap to Scepter so it can rename output fields server-side
+        if (this.fieldMap && Object.keys(this.fieldMap).length > 0) {
+            queryValue.field_map = this.fieldMap;
+        }
+
+        // Send group_by as an array so Scepter performs server-side grouping
+        if (this._groupBy && this._groupBy.length > 0) {
+            queryValue.group_by = this._groupBy;
+        }
+
+        // Send aggregate separately — never embed in select
+        if (this._aggregate && Object.keys(this._aggregate).length > 0) {
+            queryValue.aggregate = this._aggregate;
+        }
+
         return queryValue;
     }
 }
@@ -743,9 +714,14 @@ export class WhereClause {
     isLocalIp(): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).isLocalIp()); }
     isExternalIp(): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).isExternalIp()); }
     b64(value: string): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).b64(value)); }
-    inDataset(dataset: string): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).inDataset(dataset)); }
+    /** Case-sensitive membership check (use .in() for case-insensitive). */
+    inDataset(values: string[]): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).inDataset(values)); }
     inCountry(countryCode: string): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).inCountry(countryCode)); }
-    cidr(cidr: string): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).cidr(cidr)); }
+    /** Check if IP falls within CIDR range(s). Always uses "$cidr" alias to avoid Scepter stack overflow. */
+    cidr(ranges: string | string[]): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).cidr(ranges)); }
+    /** Matches if the field contains ANY of the given keywords (case-insensitive substring). */
+    keywords(keywords: string[]): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).keywords(keywords)); }
+    /** Exclusive range: matches records where min < field < max (both bounds excluded). */
     between(min: any, max: any): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).between(min, max)); }
     isTrue(): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).isTrue()); }
     isFalse(): QueryBuilder { return this.set(new FieldConditionBuilder(this.fieldName).isFalse()); }
@@ -914,119 +890,120 @@ export class GroupByQueryBuilder {
     ) {}
 
     /**
-     * Count records in each group
+     * Count records in each group.
+     * Executes a server-side groupBy + $count aggregation.
      * @returns Promise resolving to map of group key -> count
      */
     async count(): Promise<Record<string, number>> {
-        const response = await this.queryBuilder.execute();
-        if (!response.records) return {};
-
-        const groups: Record<string, number> = {};
-        for (const record of response.records) {
-            const key = this.getGroupKey(record);
-            groups[key] = (groups[key] || 0) + 1;
-        }
-        return groups;
+        const clone = this.queryBuilder.clone();
+        clone._setGroupBy([this.groupByField]);
+        clone._setSelections({});
+        clone._setAggregate({ _count: { '$count': '*' } });
+        const response = await clone.execute();
+        return this.buildGroupMap<number>(response.records, '_count');
     }
 
     /**
-     * Sum a numeric field within each group
+     * Sum a numeric field within each group.
+     * Executes a server-side groupBy + $sum aggregation.
      * @param field - The field name to sum
      * @returns Promise resolving to map of group key -> sum
      */
     async sumBy(field: string): Promise<Record<string, number>> {
-        const response = await this.queryBuilder.execute();
-        if (!response.records) return {};
-
-        const groups: Record<string, number> = {};
-        for (const record of response.records) {
-            const key = this.getGroupKey(record);
-            const value = (record as any)[field];
-            groups[key] = (groups[key] || 0) + (typeof value === 'number' ? value : 0);
-        }
-        return groups;
+        const clone = this.queryBuilder.clone();
+        clone._setGroupBy([this.groupByField]);
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$sum': field } });
+        const response = await clone.execute();
+        return this.buildGroupMap<number>(response.records, '_result');
     }
 
     /**
-     * Calculate average of a numeric field within each group
+     * Calculate average of a numeric field within each group.
+     * Executes a server-side groupBy + $avg aggregation.
      * @param field - The field name to average
      * @returns Promise resolving to map of group key -> average
      */
     async avgBy(field: string): Promise<Record<string, number>> {
-        const response = await this.queryBuilder.execute();
-        if (!response.records) return {};
-
-        const groups: Record<string, { sum: number; count: number }> = {};
-        for (const record of response.records) {
-            const key = this.getGroupKey(record);
-            const value = (record as any)[field];
-            if (!groups[key]) {
-                groups[key] = { sum: 0, count: 0 };
-            }
-            groups[key].sum += typeof value === 'number' ? value : 0;
-            groups[key].count += 1;
-        }
-
-        const result: Record<string, number> = {};
-        for (const [key, { sum, count }] of Object.entries(groups)) {
-            result[key] = count > 0 ? sum / count : 0;
-        }
-        return result;
+        const clone = this.queryBuilder.clone();
+        clone._setGroupBy([this.groupByField]);
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$avg': field } });
+        const response = await clone.execute();
+        return this.buildGroupMap<number>(response.records, '_result');
     }
 
     /**
-     * Find maximum value of a field within each group
+     * Find maximum value of a field within each group.
+     * Executes a server-side groupBy + $max aggregation.
      * @param field - The field name to find maximum
      * @returns Promise resolving to map of group key -> max value
      */
     async maxBy<T = any>(field: string): Promise<Record<string, T>> {
-        const response = await this.queryBuilder.execute();
-        if (!response.records) return {};
-
-        const groups: Record<string, T> = {};
-        for (const record of response.records) {
-            const key = this.getGroupKey(record);
-            const value = (record as any)[field] as T;
-            if (!(key in groups) || value > (groups[key] as T)) {
-                groups[key] = value;
-            }
-        }
-        return groups;
+        const clone = this.queryBuilder.clone();
+        clone._setGroupBy([this.groupByField]);
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$max': field } });
+        const response = await clone.execute();
+        return this.buildGroupMap<T>(response.records, '_result');
     }
 
     /**
-     * Find minimum value of a field within each group
+     * Find minimum value of a field within each group.
+     * Executes a server-side groupBy + $min aggregation.
      * @param field - The field name to find minimum
      * @returns Promise resolving to map of group key -> min value
      */
     async minBy<T = any>(field: string): Promise<Record<string, T>> {
-        const response = await this.queryBuilder.execute();
-        if (!response.records) return {};
+        const clone = this.queryBuilder.clone();
+        clone._setGroupBy([this.groupByField]);
+        clone._setSelections({});
+        clone._setAggregate({ _result: { '$min': field } });
+        const response = await clone.execute();
+        return this.buildGroupMap<T>(response.records, '_result');
+    }
 
-        const groups: Record<string, T> = {};
-        for (const record of response.records) {
-            const key = this.getGroupKey(record);
-            const value = (record as any)[field] as T;
-            if (!(key in groups) || value < (groups[key] as T)) {
-                groups[key] = value;
-            }
-        }
-        return groups;
+    /**
+     * Run multiple aggregations per group in a single HTTP round-trip.
+     *
+     * Each key in `spec` becomes an output alias on each returned record (alongside the group field).
+     * Supported operators: `$count`, `$sum`, `$avg`, `$max`, `$min`, `$countDistinct`.
+     *
+     * @param spec - Map of output alias to `{ '$op': 'field' }` descriptor
+     * @returns Promise resolving to an array of records, each containing the group field and all aggregation results
+     *
+     * @example
+     * ```typescript
+     * const rows = await db.queryBuilder()
+     *   .collection('orders')
+     *   .groupBy('category')
+     *   .run({
+     *     total:    { '$count': '*' },
+     *     revenue:  { '$sum': 'amount' },
+     *     avgOrder: { '$avg': 'amount' }
+     *   });
+     * // Returns: [{ category: 'electronics', total: 12, revenue: 5000, avgOrder: 416.67 }, ...]
+     * ```
+     */
+    async run(spec: AggregateSpec): Promise<Record<string, any>[]> {
+        const clone = this.queryBuilder.clone();
+        clone._setGroupBy([this.groupByField]);
+        clone._setSelections({});
+        clone._setAggregate(spec);
+        const response = await clone.execute();
+        return (response.records as any[]) ?? [];
     }
 
     /**
-     * Get the group key from a record, supporting nested field paths
+     * Build a Record<groupKey, aggValue> from the records returned by Scepter.
+     * Each record contains the group field and the aggregated value under aggKey.
      */
-    private getGroupKey(record: any): string {
-        // Support nested field paths (e.g., "user.country")
-        if (this.groupByField.includes('.')) {
-            const parts = this.groupByField.split('.');
-            let current = record;
-            for (const part of parts) {
-                current = current?.[part];
-            }
-            return String(current ?? 'null');
+    private buildGroupMap<T>(records: any[], aggKey: string): Record<string, T> {
+        const result: Record<string, T> = {};
+        for (const record of records ?? []) {
+            const key = String(record[this.groupByField] ?? 'null');
+            result[key] = record[aggKey];
         }
-        return String(record[this.groupByField] ?? 'null');
+        return result;
     }
 }

package/src/query-sdk/index.ts

@@ -8,6 +8,12 @@ export interface QueryValue {
     find: any;
     select: any;
     include_history?: boolean;
+    /** Maps logical field names to one or more physical source fields. Values are arrays. */
+    field_map?: Record<string, string[]>;
+    /** Group-by fields for server-side aggregation. Pass as an array, e.g. ["category"]. */
+    group_by?: string[];
+    /** Server-side aggregation operations. Keys are output aliases, values are typed AggregateOp objects. */
+    aggregate?: AggregateSpec;
 }
 
 export type QueryRequest = QueryValue & {
@@ -24,7 +30,19 @@ export interface QueryResponse<T = any> {
 
 // Selection types
 export type SelectionMap = Record<string, any>;
-export type FieldMap = Record<string, string>;
+/** Maps logical field names to one or more physical source fields. */
+export type FieldMap = Record<string, string[]>;
+
+// Aggregation operation types — mirrors Rust's AggregateOp untagged enum (query_input.rs)
+export type AggCountOp          = { '$count': string };          // '*' counts all records; or a field name
+export type AggSumOp            = { '$sum': string };
+export type AggAvgOp            = { '$avg': string };
+export type AggMaxOp            = { '$max': string };
+export type AggMinOp            = { '$min': string };
+export type AggCountDistinctOp  = { '$countDistinct': string };
+export type AggregateOp = AggCountOp | AggSumOp | AggAvgOp | AggMaxOp | AggMinOp | AggCountDistinctOp;
+/** Maps output alias names to aggregation operations. */
+export type AggregateSpec = Record<string, AggregateOp>;
 
 // Operator values - expanded to match Rust SDK
 export type Val = string | number | boolean | null | Val[] | Date | RegExp;