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

package/dist/dsl/query-builder.js

@@ -0,0 +1,994 @@
+/**
+ * Query builder for constructing Dimensions DSL queries programmatically.
+ * @module query-builder
+ */
+import { ValidationError } from "../client/index.js";
+import { assertValidEntity, assertValidSearchIndex } from "./schema/validation.js";
+import { VALID_OPERATORS } from "./types/vocabulary.js";
+import { escapeDslString } from "./utils/escape.js";
+import { MAX_SEARCH_TEXT_LENGTH, sanitizeInput } from "./utils/sanitize.js";
+import { validateFieldName } from "./utils/validate-field-name.js";
+/**
+ * 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 class QueryBuilder {
+    schemaStore;
+    entity = null;
+    searchIndex = null;
+    searchTerms = null;
+    similarText = null;
+    complexPhrase = null;
+    complexMaxDist = null;
+    minShouldMatchPhrase = null;
+    minShouldMatchMin = null;
+    expressionNodes = [];
+    groupDepth = 0;
+    pendingConnector = null;
+    returnFields = [];
+    unnestFields = [];
+    sortField = null;
+    sortOrder = "asc";
+    skipValue = null;
+    limitValue = null;
+    facetClauses = [];
+    timeSeriesClauses = [];
+    groupedClauses = [];
+    /**
+     * @param schemaStore - Optional describe schema for entity/index validation
+     */
+    constructor(schemaStore) {
+        this.schemaStore = schemaStore;
+    }
+    /**
+     * Adds a condition node to the expression tree.
+     * Handles automatic AND connector insertion.
+     * @param condition - The condition string to add
+     */
+    addConditionNode(condition) {
+        // Add pending connector if exists
+        if (this.pendingConnector) {
+            this.expressionNodes.push({
+                type: "connector",
+                connector: this.pendingConnector,
+            });
+            this.pendingConnector = null;
+        }
+        else if (this.expressionNodes.length > 0) {
+            // Default to AND if no connector specified
+            const lastNode = this.expressionNodes[this.expressionNodes.length - 1];
+            if (lastNode?.type === "condition" || lastNode?.type === "group_end") {
+                this.expressionNodes.push({ type: "connector", connector: "and" });
+            }
+        }
+        this.expressionNodes.push({ type: "condition", condition });
+    }
+    /**
+     * 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
+     */
+    shouldAddSpaceBefore(node, prevNode) {
+        if (prevNode === null)
+            return false;
+        if (prevNode.type === "group_start")
+            return false;
+        if (node.type === "group_end")
+            return false;
+        return true;
+    }
+    /**
+     * 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) {
+        assertValidEntity(this.schemaStore, entity);
+        this.entity = entity;
+        return 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) {
+        assertValidSearchIndex(this.schemaStore, this.entity, index);
+        this.searchIndex = index;
+        return 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) {
+        const sanitized = sanitizeInput(terms);
+        if (sanitized.length > MAX_SEARCH_TEXT_LENGTH) {
+            throw new ValidationError(`Search text exceeds maximum length of ${MAX_SEARCH_TEXT_LENGTH} characters`);
+        }
+        this.searchTerms = sanitized;
+        return 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) {
+        const sanitized = sanitizeInput(text);
+        if (sanitized.length > MAX_SEARCH_TEXT_LENGTH) {
+            throw new ValidationError(`Search text exceeds maximum length of ${MAX_SEARCH_TEXT_LENGTH} characters`);
+        }
+        this.similarText = sanitized;
+        return 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, maxDist) {
+        if (maxDist < 1) {
+            throw new ValidationError("maxDist must be >= 1");
+        }
+        const sanitized = sanitizeInput(phrase);
+        if (sanitized.length > MAX_SEARCH_TEXT_LENGTH) {
+            throw new ValidationError(`Search text exceeds maximum length of ${MAX_SEARCH_TEXT_LENGTH} characters`);
+        }
+        this.complexPhrase = sanitized;
+        this.complexMaxDist = maxDist;
+        return 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, min) {
+        if (min < 1) {
+            throw new ValidationError("min must be >= 1");
+        }
+        const sanitized = sanitizeInput(phrase);
+        if (sanitized.length > MAX_SEARCH_TEXT_LENGTH) {
+            throw new ValidationError(`Search text exceeds maximum length of ${MAX_SEARCH_TEXT_LENGTH} characters`);
+        }
+        this.minShouldMatchPhrase = sanitized;
+        this.minShouldMatchMin = min;
+        return 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, operator, value) {
+        validateFieldName(field);
+        if (!VALID_OPERATORS.includes(operator)) {
+            throw new ValidationError(`Invalid operator: ${operator}`);
+        }
+        const formattedValue = typeof value === "string" ? `"${escapeDslString(value)}"` : value;
+        this.addConditionNode(`${field} ${operator} ${formattedValue}`);
+        return this;
+    }
+    /**
+     * Adds a condition checking if a field is empty.
+     * @param field - Field name to check
+     * @returns This builder for chaining
+     */
+    whereEmpty(field) {
+        validateFieldName(field);
+        this.addConditionNode(`${field} is empty`);
+        return this;
+    }
+    /**
+     * Adds a condition checking if a field is not empty.
+     * @param field - Field name to check
+     * @returns This builder for chaining
+     */
+    whereNotEmpty(field) {
+        validateFieldName(field);
+        this.addConditionNode(`${field} is not empty`);
+        return 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, values) {
+        validateFieldName(field);
+        if (values.length === 0) {
+            throw new ValidationError("List filter must have at least one value");
+        }
+        if (values.length > 400) {
+            throw new ValidationError("List filter cannot exceed 400 items");
+        }
+        const formattedValues = values
+            .map((v) => (typeof v === "string" ? `"${escapeDslString(v)}"` : v))
+            .join(", ");
+        this.addConditionNode(`${field} in [${formattedValues}]`);
+        return 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, start, end) {
+        validateFieldName(field);
+        if (typeof start === "number" && typeof end === "number" && start > end) {
+            throw new ValidationError("Range start must not be greater than end");
+        }
+        const formattedStart = typeof start === "string" ? `"${escapeDslString(start)}"` : start;
+        const formattedEnd = typeof end === "string" ? `"${escapeDslString(end)}"` : end;
+        this.addConditionNode(`${field} in [${formattedStart}:${formattedEnd}]`);
+        return this;
+    }
+    /**
+     * Sets the next connector to OR.
+     * @returns This builder for chaining
+     */
+    or() {
+        this.pendingConnector = "or";
+        return this;
+    }
+    /**
+     * Sets the next connector to NOT.
+     * @returns This builder for chaining
+     */
+    not() {
+        this.pendingConnector = "not";
+        return 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.pendingConnector = "and";
+        return this;
+    }
+    /**
+     * Opens a parenthesized group.
+     * @returns This builder for chaining
+     */
+    openGroup() {
+        // Add pending connector if exists
+        if (this.pendingConnector) {
+            this.expressionNodes.push({
+                type: "connector",
+                connector: this.pendingConnector,
+            });
+            this.pendingConnector = null;
+        }
+        else if (this.expressionNodes.length > 0) {
+            const lastNode = this.expressionNodes[this.expressionNodes.length - 1];
+            if (lastNode?.type === "condition" || lastNode?.type === "group_end") {
+                this.expressionNodes.push({ type: "connector", connector: "and" });
+            }
+        }
+        this.expressionNodes.push({ type: "group_start" });
+        this.groupDepth++;
+        return this;
+    }
+    /**
+     * Closes a parenthesized group.
+     * @returns This builder for chaining
+     * @throws {ValidationError} If no group is open
+     */
+    closeGroup() {
+        if (this.groupDepth === 0) {
+            throw new ValidationError("No group to close");
+        }
+        this.expressionNodes.push({ type: "group_end" });
+        this.groupDepth--;
+        return 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, operator, value) {
+        validateFieldName(field);
+        this.addConditionNode(`count(${field}) ${operator} ${value}`);
+        return this;
+    }
+    /**
+     * Sets the fields to return.
+     * @param fieldList - Array of field names to return
+     * @returns This builder for chaining
+     */
+    fields(fieldList) {
+        for (const field of fieldList) {
+            validateFieldName(field);
+        }
+        this.returnFields = [...fieldList];
+        return 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, unnestFieldList) {
+        for (const field of fieldList) {
+            validateFieldName(field);
+        }
+        for (const field of unnestFieldList) {
+            validateFieldName(field);
+        }
+        this.returnFields = [...fieldList];
+        this.unnestFields = [...unnestFieldList];
+        return 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) {
+        validateFieldName(field);
+        this.unnestFields.push(field);
+        return 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, order = "asc") {
+        validateFieldName(field);
+        this.sortField = field;
+        this.sortOrder = order;
+        return 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) {
+        if (count < 0) {
+            throw new ValidationError("Skip must be non-negative");
+        }
+        this.skipValue = count;
+        return 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) {
+        if (count < 0) {
+            throw new ValidationError("Limit must be non-negative");
+        }
+        this.limitValue = count;
+        return 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, options) {
+        validateFieldName(field);
+        if (options?.limit !== undefined && options.limit < 0) {
+            throw new ValidationError("Facet limit must be non-negative", {
+                limit: options.limit,
+            });
+        }
+        const clause = {
+            type: "facet",
+            field,
+            limit: options?.limit,
+        };
+        this.facetClauses.push(clause);
+        return 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, indicators, options) {
+        validateFieldName(field);
+        if (indicators.length === 0) {
+            throw new ValidationError("Aggregate must have at least one indicator", {
+                field,
+            });
+        }
+        for (const indicator of indicators) {
+            if (!indicator || indicator.trim().length === 0) {
+                throw new ValidationError("Indicator names must be non-empty strings", {
+                    field,
+                    indicator,
+                });
+            }
+        }
+        if (options?.limit !== undefined && options.limit < 0) {
+            throw new ValidationError("Facet limit must be non-negative", {
+                field,
+                limit: options.limit,
+            });
+        }
+        if (options?.sortBy) {
+            const validSortTargets = [...indicators, "count"];
+            if (!validSortTargets.includes(options.sortBy)) {
+                throw new ValidationError(`sortBy must be one of [${validSortTargets.join(", ")}], got "${options.sortBy}"`, { field, sortBy: options.sortBy, validSortTargets });
+            }
+        }
+        const clause = {
+            type: "aggregated_facet",
+            field,
+            indicators,
+            sortBy: options?.sortBy,
+            sortOrder: options?.sortOrder ?? "desc",
+            limit: options?.limit,
+        };
+        this.facetClauses.push(clause);
+        return 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, endYear) {
+        if (startYear > endYear) {
+            throw new ValidationError("startYear must not be greater than endYear", {
+                startYear,
+                endYear,
+            });
+        }
+        this.timeSeriesClauses.push({
+            type: "time_series",
+            function: "citations_per_year",
+            startYear,
+            endYear,
+        });
+        return 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, endYear, currency = "USD") {
+        if (startYear > endYear) {
+            throw new ValidationError("startYear must not be greater than endYear", {
+                startYear,
+                endYear,
+            });
+        }
+        this.timeSeriesClauses.push({
+            type: "time_series",
+            function: "funding_per_year",
+            startYear,
+            endYear,
+            currency,
+        });
+        return 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, options) {
+        if (!groupName || groupName.trim().length === 0) {
+            throw new ValidationError("Group name must be non-empty", { groupName });
+        }
+        if (options?.fields) {
+            for (const field of options.fields) {
+                validateFieldName(field);
+            }
+        }
+        if (options?.sortField) {
+            validateFieldName(options.sortField);
+        }
+        this.groupedClauses.push({
+            type: "grouped",
+            groupName,
+            entityOrFacet: {
+                type: "entity",
+                fields: options?.fields,
+                limit: options?.limit,
+                skip: options?.skip,
+                sortField: options?.sortField,
+                sortOrder: options?.sortOrder,
+            },
+        });
+        return 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, field, options) {
+        if (!groupName || groupName.trim().length === 0) {
+            throw new ValidationError("Group name must be non-empty", { groupName });
+        }
+        validateFieldName(field);
+        this.groupedClauses.push({
+            type: "grouped",
+            groupName,
+            entityOrFacet: {
+                type: "facet",
+                field,
+                limit: options?.limit,
+            },
+        });
+        return 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, field, indicators, options) {
+        if (!groupName || groupName.trim().length === 0) {
+            throw new ValidationError("Group name must be non-empty", { groupName });
+        }
+        validateFieldName(field);
+        if (indicators.length === 0) {
+            throw new ValidationError("Aggregate must have at least one indicator", {
+                field,
+            });
+        }
+        this.groupedClauses.push({
+            type: "grouped",
+            groupName,
+            entityOrFacet: {
+                type: "aggregated_facet",
+                field,
+                indicators,
+                sortBy: options?.sortBy,
+                sortOrder: options?.sortOrder ?? "desc",
+                limit: options?.limit,
+            },
+        });
+        return this;
+    }
+    /**
+     * Builds the DSL query string.
+     * @returns The constructed DSL query
+     * @throws {ValidationError} If entity type is not set
+     */
+    build() {
+        if (!this.entity) {
+            throw new ValidationError("Entity type must be specified");
+        }
+        const parts = [];
+        const searchTerms = this.searchTerms;
+        // search <entity> [in <index>] for "<terms>" OR function expression search
+        if (this.similarText) {
+            const escapedText = escapeDslString(this.similarText);
+            parts.push(`search ${this.entity} for similar_documents("${escapedText}")`);
+        }
+        else if (this.complexPhrase !== null) {
+            const escapedPhrase = escapeDslString(this.complexPhrase);
+            const indexPart = this.searchIndex && this.searchIndex !== "full_data" ? ` in ${this.searchIndex}` : "";
+            parts.push(`search ${this.entity}${indexPart} for complex("${escapedPhrase}", ${this.complexMaxDist})`);
+        }
+        else if (this.minShouldMatchPhrase !== null) {
+            const escapedPhrase = escapeDslString(this.minShouldMatchPhrase);
+            const indexPart = this.searchIndex && this.searchIndex !== "full_data" ? ` in ${this.searchIndex}` : "";
+            parts.push(`search ${this.entity}${indexPart} for min_should_match("${escapedPhrase}", ${this.minShouldMatchMin})`);
+        }
+        else if (searchTerms && this.searchIndex && this.searchIndex !== "full_data") {
+            parts.push(`search ${this.entity} in ${this.searchIndex} for "${escapeDslString(searchTerms)}"`);
+        }
+        else if (searchTerms) {
+            parts.push(`search ${this.entity} for "${escapeDslString(searchTerms)}"`);
+        }
+        else {
+            if (this.searchIndex && this.searchIndex !== "full_data") {
+                throw new ValidationError("Search index requires search terms: call for() before in()");
+            }
+            parts.push(`search ${this.entity}`);
+        }
+        // Check for unbalanced parentheses
+        if (this.groupDepth !== 0) {
+            throw new ValidationError("Unbalanced parentheses: unclosed group");
+        }
+        // where <conditions> - build from expression tree
+        if (this.expressionNodes.length > 0) {
+            let whereStr = "";
+            for (let i = 0; i < this.expressionNodes.length; i++) {
+                const node = this.expressionNodes[i];
+                const prevNode = i > 0 ? this.expressionNodes[i - 1] : null;
+                if (this.shouldAddSpaceBefore(node, prevNode)) {
+                    whereStr += " ";
+                }
+                switch (node.type) {
+                    case "condition":
+                        whereStr += node.condition;
+                        break;
+                    case "connector":
+                        whereStr += node.connector;
+                        break;
+                    case "group_start":
+                        whereStr += "(";
+                        break;
+                    case "group_end":
+                        whereStr += ")";
+                        break;
+                }
+            }
+            parts.push(`where ${whereStr}`);
+        }
+        // return <entity>[<fields>] or return <entity>
+        // Note: return clause is required before limit/skip/sort modifiers
+        // Note: fields must be separated with '+' not ','
+        // Note: unnest() wraps fields that should be flattened
+        const hasFields = this.returnFields.length > 0 || this.unnestFields.length > 0;
+        const hasOtherReturnClauses = this.facetClauses.length > 0 ||
+            this.timeSeriesClauses.length > 0 ||
+            this.groupedClauses.length > 0;
+        // Validate limit(0) usage - the Dimensions API rejects "return <entity> limit 0"
+        if (this.limitValue === 0) {
+            if (!hasOtherReturnClauses) {
+                throw new ValidationError("limit(0) requires at least one facet, time-series, or grouped return clause. " +
+                    "The Dimensions API does not support 'return <entity> limit 0'. " +
+                    "Use returnFacet(), returnCitationsPerYear(), or similar to get facet-only results.", { limit: 0 });
+            }
+            if (hasFields) {
+                throw new ValidationError("limit(0) cannot be used with fields(). " +
+                    "The Dimensions API does not support 'return <entity>[fields] limit 0'. " +
+                    "Either remove fields() to get facet-only results, or use limit > 0.", { limit: 0, fields: this.returnFields });
+            }
+        }
+        // When limit=0 with facets/time-series/grouped returns and no fields,
+        // skip the entire entity return section (return clause + modifiers).
+        // User intent: "I don't want entity results, only facet results."
+        const skipEntityReturn = this.limitValue === 0 && hasOtherReturnClauses && !hasFields;
+        if (hasFields) {
+            const allFieldParts = [];
+            // Add regular fields
+            for (const field of this.returnFields) {
+                allFieldParts.push(field);
+            }
+            // Add unnested fields
+            for (const field of this.unnestFields) {
+                allFieldParts.push(`unnest(${field})`);
+            }
+            parts.push(`return ${this.entity}[${allFieldParts.join("+")}]`);
+        }
+        else if (!skipEntityReturn &&
+            (this.sortField !== null || this.skipValue !== null || this.limitValue !== null)) {
+            // API requires return clause when using modifiers
+            parts.push(`return ${this.entity}`);
+        }
+        // sort by <field> <order>
+        // Skip when suppressing entity return (sort only applies to entity results)
+        if (this.sortField && !skipEntityReturn) {
+            parts.push(`sort by ${this.sortField} ${this.sortOrder}`);
+        }
+        // limit <n> (must come before skip)
+        // Skip when suppressing entity return
+        if (this.limitValue !== null && !skipEntityReturn) {
+            parts.push(`limit ${this.limitValue}`);
+        }
+        // skip <n> (must come after limit)
+        // Skip when suppressing entity return
+        if (this.skipValue !== null && !skipEntityReturn) {
+            parts.push(`skip ${this.skipValue}`);
+        }
+        // Facet return clauses
+        for (const clause of this.facetClauses) {
+            let facetDsl = `return ${clause.field}`;
+            if (clause.type === "aggregated_facet" && clause.indicators.length > 0) {
+                facetDsl += ` aggregate ${clause.indicators.join(", ")}`;
+                if (clause.sortBy) {
+                    facetDsl += ` sort by ${clause.sortBy} ${clause.sortOrder}`;
+                }
+            }
+            if (clause.limit !== undefined) {
+                facetDsl += ` limit ${clause.limit}`;
+            }
+            parts.push(facetDsl);
+        }
+        // Time-series return clauses
+        for (const clause of this.timeSeriesClauses) {
+            if (clause.function === "citations_per_year") {
+                parts.push(`return citations_per_year(${clause.startYear}, ${clause.endYear})`);
+            }
+            else if (clause.function === "funding_per_year") {
+                parts.push(`return funding_per_year(${clause.startYear}, ${clause.endYear}, "${clause.currency}")`);
+            }
+        }
+        // Grouped return clauses
+        for (const clause of this.groupedClauses) {
+            const inner = clause.entityOrFacet;
+            let groupedDsl = `return in "${escapeDslString(clause.groupName)}"`;
+            if (inner.type === "entity") {
+                if (inner.fields && inner.fields.length > 0) {
+                    groupedDsl += ` ${this.entity}[${inner.fields.join("+")}]`;
+                }
+                else {
+                    groupedDsl += ` ${this.entity}`;
+                }
+                if (inner.sortField) {
+                    groupedDsl += ` sort by ${inner.sortField} ${inner.sortOrder ?? "asc"}`;
+                }
+                if (inner.limit !== undefined) {
+                    groupedDsl += ` limit ${inner.limit}`;
+                }
+                if (inner.skip !== undefined) {
+                    groupedDsl += ` skip ${inner.skip}`;
+                }
+            }
+            else if (inner.type === "facet") {
+                groupedDsl += ` ${inner.field}`;
+                if (inner.limit !== undefined) {
+                    groupedDsl += ` limit ${inner.limit}`;
+                }
+            }
+            else if (inner.type === "aggregated_facet") {
+                groupedDsl += ` ${inner.field} aggregate ${inner.indicators.join(", ")}`;
+                if (inner.sortBy) {
+                    groupedDsl += ` sort by ${inner.sortBy} ${inner.sortOrder ?? "desc"}`;
+                }
+                if (inner.limit !== undefined) {
+                    groupedDsl += ` limit ${inner.limit}`;
+                }
+            }
+            parts.push(groupedDsl);
+        }
+        return parts.join(" ");
+    }
+    /**
+     * 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() {
+        const copy = new QueryBuilder(this.schemaStore);
+        copy.entity = this.entity;
+        copy.searchIndex = this.searchIndex;
+        copy.searchTerms = this.searchTerms;
+        copy.similarText = this.similarText;
+        copy.complexPhrase = this.complexPhrase;
+        copy.complexMaxDist = this.complexMaxDist;
+        copy.minShouldMatchPhrase = this.minShouldMatchPhrase;
+        copy.minShouldMatchMin = this.minShouldMatchMin;
+        copy.expressionNodes = [...this.expressionNodes];
+        copy.groupDepth = this.groupDepth;
+        copy.pendingConnector = this.pendingConnector;
+        copy.returnFields = [...this.returnFields];
+        copy.unnestFields = [...this.unnestFields];
+        copy.sortField = this.sortField;
+        copy.sortOrder = this.sortOrder;
+        copy.skipValue = this.skipValue;
+        copy.limitValue = this.limitValue;
+        copy.facetClauses = [...this.facetClauses];
+        copy.timeSeriesClauses = [...this.timeSeriesClauses];
+        copy.groupedClauses = [...this.groupedClauses];
+        return copy;
+    }
+    /**
+     * Resets the builder to its initial state.
+     * @returns This builder for chaining
+     */
+    reset() {
+        this.entity = null;
+        this.searchIndex = null;
+        this.searchTerms = null;
+        this.similarText = null;
+        this.complexPhrase = null;
+        this.complexMaxDist = null;
+        this.minShouldMatchPhrase = null;
+        this.minShouldMatchMin = null;
+        this.expressionNodes = [];
+        this.groupDepth = 0;
+        this.pendingConnector = null;
+        this.returnFields = [];
+        this.unnestFields = [];
+        this.sortField = null;
+        this.sortOrder = "asc";
+        this.skipValue = null;
+        this.limitValue = null;
+        this.facetClauses = [];
+        this.timeSeriesClauses = [];
+        this.groupedClauses = [];
+        return this;
+    }
+}
+//# sourceMappingURL=query-builder.js.map