@digital-science-dsl/dimensions-analytics-mcp 0.5.3

package/dist/dsl/pagination.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Pagination helpers aligned with Dimensions DSL operational limits.
+ * @see https://docs.dimensions.ai/dsl/usagepolicy.html
+ * @module dsl/pagination
+ */
+/** Soft warning threshold for very large result sets. */
+export declare const LARGE_RESULT_THRESHOLD = 10000;
+/** Default pages per batch invocation (single page). */
+export declare const DEFAULT_BATCH_MAX_PAGES = 1;
+/** Hard cap on pages per batch invocation. */
+export declare const HARD_MAX_BATCH_PAGES = 50;
+/** Pages above this require `confirmLargeFetch`. */
+export declare const CONFIRM_LARGE_FETCH_PAGES = 5;
+/** Records above this require `confirmLargeFetch`. */
+export declare const CONFIRM_LARGE_FETCH_RECORDS = 5000;
+/** Max IDs returned in aggregate mode before truncation. */
+export declare const AGGREGATE_ID_CAP = 500;
+/** Metadata describing pagination state for search tool responses. */
+export interface PaginationMetadata {
+    readonly pageSize: number;
+    readonly skip: number;
+    readonly page: number;
+    readonly nextSkip: number | null;
+    readonly maxPageSize: number;
+    readonly maxTotalRecords: number;
+    readonly maxPagesRemaining: number;
+    readonly estimatedRequestsToFetchAll: number;
+    readonly estimatedMinutesToFetchAll: number;
+}
+/** Arguments for resolving skip/limit from tool input. */
+export type PaginationInput = {
+    readonly skip?: number;
+    readonly page?: number;
+    readonly limit?: number;
+    readonly pageSize?: number;
+};
+/**
+ * Validates that skip/limit stay within Dimensions pagination bounds.
+ * @param skip - Records to skip
+ * @param limit - Page size
+ * @throws {ValidationError} When out of bounds
+ */
+export declare function validatePaginationBounds(skip: number, limit: number): void;
+/**
+ * Resolves skip and limit from tool arguments (`skip`, `page`, `limit`, or `pageSize`).
+ * @param args - Pagination-related tool arguments
+ * @returns Resolved skip and limit
+ * @throws {ValidationError} When both skip and page are set or bounds are invalid
+ */
+export declare function resolveSkipAndLimit(args: PaginationInput): {
+    skip: number;
+    limit: number;
+};
+/**
+ * Builds pagination metadata for a search response.
+ * @param skip - Current skip offset
+ * @param pageSize - Current page size
+ * @param totalCount - Total matching records from the API
+ * @returns Pagination metadata block
+ */
+export declare function buildPaginationMetadata(skip: number, pageSize: number, totalCount: number): PaginationMetadata;
+/**
+ * Returns a soft warning when totalCount exceeds {@link LARGE_RESULT_THRESHOLD}.
+ * @param totalCount - Total matching records
+ * @returns Warning string or undefined
+ */
+export declare function largeResultWarning(totalCount: number): string | undefined;
+/** Options for validating a multi-page batch request. */
+export type BatchPaginationOptions = {
+    readonly startPage: number;
+    readonly maxPages: number;
+    readonly pageSize: number;
+    readonly maxRecords?: number;
+    readonly confirmLargeFetch?: boolean;
+};
+/**
+ * Validates multi-page batch parameters against policy guardrails.
+ * @param options - Batch request options
+ * @throws {ValidationError} When limits are exceeded or confirmation is required
+ */
+export declare function validateBatchPagination(options: BatchPaginationOptions): void;
+//# sourceMappingURL=pagination.d.ts.map

package/dist/dsl/pagination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.d.ts","sourceRoot":"","sources":["../../src/dsl/pagination.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,yDAAyD;AACzD,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C,wDAAwD;AACxD,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC,8CAA8C;AAC9C,eAAO,MAAM,oBAAoB,KAAK,CAAC;AAEvC,oDAAoD;AACpD,eAAO,MAAM,yBAAyB,IAAI,CAAC;AAE3C,sDAAsD;AACtD,eAAO,MAAM,2BAA2B,OAAQ,CAAC;AAEjD,4DAA4D;AAC5D,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,sEAAsE;AACtE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,2BAA2B,EAAE,MAAM,CAAC;IAC7C,QAAQ,CAAC,0BAA0B,EAAE,MAAM,CAAC;CAC7C;AAED,0DAA0D;AAC1D,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAgB1E;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,eAAe,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAiB1F;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,kBAAkB,CA0BpB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQzE;AAED,yDAAyD;AACzD,MAAM,MAAM,sBAAsB,GAAG;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;CACtC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAoC7E"}

package/dist/dsl/pagination.js

@@ -0,0 +1,135 @@
+/**
+ * Pagination helpers aligned with Dimensions DSL operational limits.
+ * @see https://docs.dimensions.ai/dsl/usagepolicy.html
+ * @module dsl/pagination
+ */
+import { ValidationError } from "../client/index.js";
+import { SCHEMA_LIMITS } from "./schema/store.js";
+/** Soft warning threshold for very large result sets. */
+export const LARGE_RESULT_THRESHOLD = 10_000;
+/** Default pages per batch invocation (single page). */
+export const DEFAULT_BATCH_MAX_PAGES = 1;
+/** Hard cap on pages per batch invocation. */
+export const HARD_MAX_BATCH_PAGES = 50;
+/** Pages above this require `confirmLargeFetch`. */
+export const CONFIRM_LARGE_FETCH_PAGES = 5;
+/** Records above this require `confirmLargeFetch`. */
+export const CONFIRM_LARGE_FETCH_RECORDS = 5_000;
+/** Max IDs returned in aggregate mode before truncation. */
+export const AGGREGATE_ID_CAP = 500;
+/**
+ * Validates that skip/limit stay within Dimensions pagination bounds.
+ * @param skip - Records to skip
+ * @param limit - Page size
+ * @throws {ValidationError} When out of bounds
+ */
+export function validatePaginationBounds(skip, limit) {
+    if (limit < 1 || limit > SCHEMA_LIMITS.maxLimit) {
+        throw new ValidationError(`limit must be between 1 and ${SCHEMA_LIMITS.maxLimit}`, {
+            limit,
+            maxLimit: SCHEMA_LIMITS.maxLimit,
+        });
+    }
+    if (skip < 0) {
+        throw new ValidationError("skip must be non-negative", { skip });
+    }
+    if (skip + limit > SCHEMA_LIMITS.maxOffset) {
+        throw new ValidationError(`skip + limit cannot exceed ${SCHEMA_LIMITS.maxOffset} (max paginated records)`, { skip, limit, maxOffset: SCHEMA_LIMITS.maxOffset });
+    }
+}
+/**
+ * Resolves skip and limit from tool arguments (`skip`, `page`, `limit`, or `pageSize`).
+ * @param args - Pagination-related tool arguments
+ * @returns Resolved skip and limit
+ * @throws {ValidationError} When both skip and page are set or bounds are invalid
+ */
+export function resolveSkipAndLimit(args) {
+    const limit = args.pageSize ?? args.limit ?? 100;
+    let skip = 0;
+    if (args.skip !== undefined) {
+        skip = args.skip;
+    }
+    else if (args.page !== undefined) {
+        if (args.page < 0 || args.page >= SCHEMA_LIMITS.maxPages) {
+            throw new ValidationError(`page must be between 0 and ${SCHEMA_LIMITS.maxPages - 1}`, {
+                page: args.page,
+                maxPages: SCHEMA_LIMITS.maxPages,
+            });
+        }
+        skip = args.page * limit;
+    }
+    validatePaginationBounds(skip, limit);
+    return { skip, limit };
+}
+/**
+ * Builds pagination metadata for a search response.
+ * @param skip - Current skip offset
+ * @param pageSize - Current page size
+ * @param totalCount - Total matching records from the API
+ * @returns Pagination metadata block
+ */
+export function buildPaginationMetadata(skip, pageSize, totalCount) {
+    const page = Math.floor(skip / pageSize);
+    const fetchedThrough = skip + pageSize;
+    const hasMore = totalCount > fetchedThrough;
+    const nextSkip = hasMore ? fetchedThrough : null;
+    const remainingRecords = Math.max(0, totalCount - fetchedThrough);
+    const maxPagesRemaining = Math.min(SCHEMA_LIMITS.maxPages - (page + 1), Math.ceil(remainingRecords / pageSize));
+    const estimatedRequestsToFetchAll = Math.ceil(totalCount / pageSize);
+    const estimatedMinutesToFetchAll = Math.ceil(estimatedRequestsToFetchAll / SCHEMA_LIMITS.requestsPerMinute);
+    return {
+        pageSize,
+        skip,
+        page,
+        nextSkip,
+        maxPageSize: SCHEMA_LIMITS.maxLimit,
+        maxTotalRecords: SCHEMA_LIMITS.maxOffset,
+        maxPagesRemaining,
+        estimatedRequestsToFetchAll,
+        estimatedMinutesToFetchAll,
+    };
+}
+/**
+ * Returns a soft warning when totalCount exceeds {@link LARGE_RESULT_THRESHOLD}.
+ * @param totalCount - Total matching records
+ * @returns Warning string or undefined
+ */
+export function largeResultWarning(totalCount) {
+    if (totalCount <= LARGE_RESULT_THRESHOLD)
+        return undefined;
+    const pages = Math.ceil(totalCount / SCHEMA_LIMITS.maxLimit);
+    const minutes = Math.ceil(pages / SCHEMA_LIMITS.requestsPerMinute);
+    return (`${totalCount.toLocaleString()} matches — narrow filters or use facets first. ` +
+        `Full pagination needs ~${pages} requests (~${minutes} min at ${SCHEMA_LIMITS.requestsPerMinute}/min).`);
+}
+/**
+ * Validates multi-page batch parameters against policy guardrails.
+ * @param options - Batch request options
+ * @throws {ValidationError} When limits are exceeded or confirmation is required
+ */
+export function validateBatchPagination(options) {
+    const { startPage, maxPages, pageSize, maxRecords, confirmLargeFetch } = options;
+    if (maxPages < 1 || maxPages > HARD_MAX_BATCH_PAGES) {
+        throw new ValidationError(`maxPages must be between 1 and ${HARD_MAX_BATCH_PAGES}`, {
+            maxPages,
+            hardMax: HARD_MAX_BATCH_PAGES,
+        });
+    }
+    if (startPage < 0 || startPage >= SCHEMA_LIMITS.maxPages) {
+        throw new ValidationError(`startPage must be between 0 and ${SCHEMA_LIMITS.maxPages - 1}`, {
+            startPage,
+        });
+    }
+    validatePaginationBounds(startPage * pageSize, pageSize);
+    const endSkip = startPage * pageSize + maxPages * pageSize;
+    if (endSkip > SCHEMA_LIMITS.maxOffset) {
+        throw new ValidationError(`startPage + maxPages exceeds max paginated records (${SCHEMA_LIMITS.maxOffset})`, { startPage, maxPages, pageSize, maxOffset: SCHEMA_LIMITS.maxOffset });
+    }
+    const recordsPlanned = Math.min(maxPages * pageSize, maxRecords ?? maxPages * pageSize);
+    const needsConfirm = maxPages > CONFIRM_LARGE_FETCH_PAGES || recordsPlanned > CONFIRM_LARGE_FETCH_RECORDS;
+    if (needsConfirm && !confirmLargeFetch) {
+        throw new ValidationError(`Large fetch requires confirmLargeFetch: true (maxPages=${maxPages}, ~${recordsPlanned} records). ` +
+            "Narrow filters or use aggregate mode for summaries.", { maxPages, recordsPlanned, confirmLargeFetch });
+    }
+}
+//# sourceMappingURL=pagination.js.map

package/dist/dsl/pagination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/dsl/pagination.ts"],"names":[],"mappings":"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"}

package/dist/dsl/query-builder.d.ts

@@ -0,0 +1,456 @@
+/**
+ * Query builder for constructing Dimensions DSL queries programmatically.
+ * @module query-builder
+ */
+import type { SchemaStore } from "./schema/store.js";
+import type { Currency } from "./types/return-clauses.js";
+import type { EntityType, SearchIndex, SortOrder, WhereOperator } from "./types/vocabulary.js";
+export type { EntityType, SearchIndex, SortOrder, WhereOperator };
+/**
+ * Fluent builder for constructing Dimensions DSL queries.
+ * Provides a type-safe way to build search queries with conditions, sorting, and pagination.
+ *
+ * @example
+ * ```typescript
+ * const query = new QueryBuilder()
+ *   .search("publications")
+ *   .for("machine learning")
+ *   .where("year", ">=", 2020)
+ *   .fields(["id", "title", "doi"])
+ *   .sort("times_cited", "desc")
+ *   .limit(100)
+ *   .build();
+ * ```
+ */
+export declare class QueryBuilder {
+    private readonly schemaStore;
+    private entity;
+    private searchIndex;
+    private searchTerms;
+    private similarText;
+    private complexPhrase;
+    private complexMaxDist;
+    private minShouldMatchPhrase;
+    private minShouldMatchMin;
+    private expressionNodes;
+    private groupDepth;
+    private pendingConnector;
+    private returnFields;
+    private unnestFields;
+    private sortField;
+    private sortOrder;
+    private skipValue;
+    private limitValue;
+    private facetClauses;
+    private timeSeriesClauses;
+    private groupedClauses;
+    /**
+     * @param schemaStore - Optional describe schema for entity/index validation
+     */
+    constructor(schemaStore?: SchemaStore);
+    /**
+     * Adds a condition node to the expression tree.
+     * Handles automatic AND connector insertion.
+     * @param condition - The condition string to add
+     */
+    private addConditionNode;
+    /**
+     * Determines if a space should be added before an expression node.
+     * Handles spacing rules for parentheses in boolean expressions.
+     * @param node - The current expression node
+     * @param prevNode - The previous expression node (or null if first)
+     * @returns True if a space should be added before the node
+     */
+    private shouldAddSpaceBefore;
+    /**
+     * Sets the entity type to search.
+     * @param entity - The entity type to search (publications, grants, etc.)
+     * @returns This builder for chaining
+     * @throws {ValidationError} If entity type is invalid
+     */
+    search(entity: EntityType | string): this;
+    /**
+     * Sets the search index for full-text search.
+     * Requires search terms via {@link for} — building without search terms will throw.
+     * @param index - The search index to use
+     * @returns This builder for chaining
+     * @throws {ValidationError} If index is invalid
+     * @throws {ValidationError} If used without search terms at build time
+     */
+    in(index: SearchIndex | string): this;
+    /**
+     * Sets the search terms for full-text search.
+     *
+     * **Note:** `"*"` is **not** a wildcard in the Dimensions DSL — it is treated as a literal
+     * string. To search all records without a text filter, simply omit the `for()` call and
+     * use `where()` conditions instead.
+     *
+     * @param terms - Search terms to look for
+     * @returns This builder for chaining
+     */
+    for(terms: string): this;
+    /**
+     * Sets the search to find semantically similar documents based on text.
+     * Uses the similar_documents() DSL function.
+     * @param text - The text (abstract, description) to find similar documents for
+     * @returns This builder for chaining
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .forSimilar("After spinal cord injury, macrophages infiltrate...")
+     *   .where("year", ">", 2015)
+     *   .limit(10)
+     *   .build();
+     * // Generates: search publications for similar_documents("...") where year > 2015 ...
+     * ```
+     */
+    forSimilar(text: string): this;
+    /**
+     * Sets the search to use proximity matching via the complex() DSL function.
+     * Finds documents where search terms appear within a maximum distance of each other.
+     * @param phrase - The search phrase
+     * @param maxDist - Maximum distance between terms (must be >= 1)
+     * @returns This builder for chaining
+     * @throws {ValidationError} If maxDist is less than 1
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .forComplex("quantum networking", 3)
+     *   .build();
+     * // Generates: search publications for complex("quantum networking", 3)
+     * ```
+     */
+    forComplex(phrase: string, maxDist: number): this;
+    /**
+     * Sets the search to use minimum term matching via the min_should_match() DSL function.
+     * Finds documents matching at least `min` of the terms in the phrase.
+     * @param phrase - The search phrase
+     * @param min - Minimum number of terms that must match (must be >= 1)
+     * @returns This builder for chaining
+     * @throws {ValidationError} If min is less than 1
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .forMinShouldMatch("quantum OR optical networking", 2)
+     *   .build();
+     * // Generates: search publications for min_should_match("quantum OR optical networking", 2)
+     * ```
+     */
+    forMinShouldMatch(phrase: string, min: number): this;
+    /**
+     * Adds a where clause condition.
+     * @param field - Field name to filter on
+     * @param operator - Comparison operator
+     * @param value - Value to compare against
+     * @returns This builder for chaining
+     * @throws {ValidationError} If operator is invalid
+     */
+    where(field: string, operator: WhereOperator, value: string | number | boolean): this;
+    /**
+     * Adds a condition checking if a field is empty.
+     * @param field - Field name to check
+     * @returns This builder for chaining
+     */
+    whereEmpty(field: string): this;
+    /**
+     * Adds a condition checking if a field is not empty.
+     * @param field - Field name to check
+     * @returns This builder for chaining
+     */
+    whereNotEmpty(field: string): this;
+    /**
+     * Adds a list filter condition (field in ["a", "b", "c"]).
+     * @param field - Field name to filter on
+     * @param values - Array of values to match
+     * @returns This builder for chaining
+     * @throws {ValidationError} If values array is empty
+     * @throws {ValidationError} If values array exceeds 400 items (DSL limit)
+     */
+    whereIn(field: string, values: readonly (string | number)[]): this;
+    /**
+     * Adds a range filter condition (field in [start:end]).
+     * @param field - Field name to filter on
+     * @param start - Start of range (inclusive)
+     * @param end - End of range (inclusive)
+     * @returns This builder for chaining
+     * @throws {ValidationError} If numeric start is greater than numeric end
+     */
+    whereRange(field: string, start: string | number, end: string | number): this;
+    /**
+     * Sets the next connector to OR.
+     * @returns This builder for chaining
+     */
+    or(): this;
+    /**
+     * Sets the next connector to NOT.
+     * @returns This builder for chaining
+     */
+    not(): this;
+    /**
+     * Sets the next connector to AND explicitly.
+     * Note: AND is the default connector between conditions, but this method
+     * provides API symmetry with or() and not().
+     * @returns This builder for chaining
+     */
+    and(): this;
+    /**
+     * Opens a parenthesized group.
+     * @returns This builder for chaining
+     */
+    openGroup(): this;
+    /**
+     * Closes a parenthesized group.
+     * @returns This builder for chaining
+     * @throws {ValidationError} If no group is open
+     */
+    closeGroup(): this;
+    /**
+     * Adds a count filter condition (count(field) op value).
+     * @param field - Multi-value field name to count
+     * @param operator - Comparison operator
+     * @param value - Count to compare against
+     * @returns This builder for chaining
+     */
+    whereCount(field: string, operator: "=" | "!=" | ">" | "<" | ">=" | "<=", value: number): this;
+    /**
+     * Sets the fields to return.
+     * @param fieldList - Array of field names to return
+     * @returns This builder for chaining
+     */
+    fields(fieldList: string[]): this;
+    /**
+     * Sets the fields to return including unnest operations.
+     * Unnest flattens nested arrays into separate rows (Cartesian product).
+     * DSL: return publications[id+title+unnest(researchers)+unnest(category_for)]
+     *
+     * @param fieldList - Array of regular field names to return
+     * @param unnestFieldList - Array of field names to unnest
+     * @returns This builder for chaining
+     * @throws {ValidationError} If any unnest field name is empty or whitespace-only
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .for("machine learning")
+     *   .fieldsWithUnnest(["id", "title"], ["researchers", "category_for"])
+     *   .build();
+     * // Returns flattened rows - one row per researcher × category combination
+     * ```
+     */
+    fieldsWithUnnest(fieldList: readonly string[], unnestFieldList: readonly string[]): this;
+    /**
+     * Adds an unnest field to the return clause.
+     * Can be chained with fields() to add unnest operations.
+     * DSL: return publications[id+title+unnest(researchers)]
+     *
+     * @param field - Field name to unnest
+     * @returns This builder for chaining
+     * @throws {ValidationError} If field name is empty or whitespace-only
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .for("test")
+     *   .fields(["id", "title"])
+     *   .addUnnest("researchers")
+     *   .addUnnest("category_for")
+     *   .build();
+     * ```
+     */
+    addUnnest(field: string): this;
+    /**
+     * Sets the sort field and order.
+     * @param field - Field name to sort by
+     * @param order - Sort direction (asc or desc)
+     * @returns This builder for chaining
+     */
+    sort(field: string, order?: SortOrder): this;
+    /**
+     * Sets the number of results to skip (for pagination).
+     * @param count - Number of results to skip
+     * @returns This builder for chaining
+     * @throws {ValidationError} If count is negative
+     */
+    skip(count: number): this;
+    /**
+     * Sets the maximum number of results to return.
+     * @param count - Maximum number of results
+     * @returns This builder for chaining
+     * @throws {ValidationError} If count is negative
+     */
+    limit(count: number): this;
+    /**
+     * Adds a facet return clause.
+     * DSL: return <field> [limit <n>]
+     * @param field - Facet field name
+     * @param options - Optional limit for facet results
+     * @returns This builder for chaining
+     * @throws {ValidationError} If field is empty or whitespace-only
+     * @throws {ValidationError} If limit is negative
+     */
+    returnFacet(field: string, options?: {
+        limit?: number;
+    }): this;
+    /**
+     * Adds an aggregated facet return clause.
+     * DSL: return <field> aggregate <indicators> [sort by <indicator> <order>] [limit <n>]
+     * @param field - Facet field name
+     * @param indicators - Array of indicator names to aggregate
+     * @param options - Optional sort and limit options
+     * @returns This builder for chaining
+     * @throws {ValidationError} If field is empty or whitespace-only
+     * @throws {ValidationError} If indicators array is empty
+     * @throws {ValidationError} If any indicator is empty or whitespace-only
+     * @throws {ValidationError} If limit is negative
+     * @throws {ValidationError} If sortBy is not one of indicators or "count"
+     */
+    returnAggregate(field: string, indicators: readonly string[], options?: {
+        sortBy?: string;
+        sortOrder?: SortOrder;
+        limit?: number;
+    }): this;
+    /**
+     * Adds a citations_per_year time-series return clause.
+     * Returns citation counts per year for the specified range.
+     * DSL: return citations_per_year(2010, 2023)
+     *
+     * @param startYear - Start year for the time series (inclusive)
+     * @param endYear - End year for the time series (inclusive)
+     * @returns This builder for chaining
+     * @throws {ValidationError} If startYear is greater than endYear
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .for("machine learning")
+     *   .returnCitationsPerYear(2010, 2023)
+     *   .build();
+     * // "search publications for ... return citations_per_year(2010, 2023)"
+     * ```
+     */
+    returnCitationsPerYear(startYear: number, endYear: number): this;
+    /**
+     * Adds a funding_per_year time-series return clause.
+     * Returns funding amounts per year for the specified range.
+     * DSL: return funding_per_year(2015, 2023, "USD")
+     *
+     * @param startYear - Start year for the time series (inclusive)
+     * @param endYear - End year for the time series (inclusive)
+     * @param currency - Currency for the funding amounts (default: "USD")
+     * @returns This builder for chaining
+     * @throws {ValidationError} If startYear is greater than endYear
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("grants")
+     *   .for("cancer research")
+     *   .returnFundingPerYear(2015, 2023, "EUR")
+     *   .build();
+     * // "search grants for ... return funding_per_year(2015, 2023, "EUR")"
+     * ```
+     */
+    returnFundingPerYear(startYear: number, endYear: number, currency?: Currency): this;
+    /**
+     * Adds a grouped entity return clause.
+     * DSL: return in "docs" publications[id + title]
+     *
+     * @param groupName - Name for the result group
+     * @param options - Entity return options (fields, limit, skip, sort)
+     * @returns This builder for chaining
+     * @throws {ValidationError} If groupName is empty or whitespace-only
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .for("test")
+     *   .returnGrouped("docs", { fields: ["id", "title"], limit: 10 })
+     *   .build();
+     * // "... return in "docs" publications[id+title] limit 10"
+     * ```
+     */
+    returnGrouped(groupName: string, options?: {
+        fields?: readonly string[];
+        limit?: number;
+        skip?: number;
+        sortField?: string;
+        sortOrder?: SortOrder;
+    }): this;
+    /**
+     * Adds a grouped facet return clause (simple facet).
+     * DSL: return in "facets" year limit 10
+     *
+     * @param groupName - Name for the result group
+     * @param field - Facet field name
+     * @param options - Optional limit for facet results
+     * @returns This builder for chaining
+     * @throws {ValidationError} If groupName or field is empty
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .for("test")
+     *   .returnGroupedFacet("years", "year", { limit: 20 })
+     *   .build();
+     * // "... return in "years" year limit 20"
+     * ```
+     */
+    returnGroupedFacet(groupName: string, field: string, options?: {
+        limit?: number;
+    }): this;
+    /**
+     * Adds a grouped aggregated facet return clause.
+     * DSL: return in "metrics" funders aggregate rcr_avg, funding_usd sort by rcr_avg desc
+     *
+     * @param groupName - Name for the result group
+     * @param field - Facet field name
+     * @param indicators - Array of indicator names to aggregate
+     * @param options - Optional sort and limit options
+     * @returns This builder for chaining
+     * @throws {ValidationError} If groupName, field, or indicators are invalid
+     *
+     * @example
+     * ```typescript
+     * const query = new QueryBuilder()
+     *   .search("publications")
+     *   .for("test")
+     *   .returnGroupedAggregate("metrics", "funders", ["rcr_avg"], { sortBy: "rcr_avg" })
+     *   .build();
+     * // "... return in "metrics" funders aggregate rcr_avg sort by rcr_avg desc"
+     * ```
+     */
+    returnGroupedAggregate(groupName: string, field: string, indicators: readonly string[], options?: {
+        sortBy?: string;
+        sortOrder?: SortOrder;
+        limit?: number;
+    }): this;
+    /**
+     * Builds the DSL query string.
+     * @returns The constructed DSL query
+     * @throws {ValidationError} If entity type is not set
+     */
+    build(): string;
+    /**
+     * Creates a deep copy of this builder.
+     * Useful when branching queries (e.g. adding different facets from a shared base).
+     * @returns A new QueryBuilder with the same state
+     */
+    clone(): QueryBuilder;
+    /**
+     * Resets the builder to its initial state.
+     * @returns This builder for chaining
+     */
+    reset(): this;
+}
+//# sourceMappingURL=query-builder.d.ts.map