@deepagents/text2sql 4.3.0 → 6.0.0

package/dist/lib/adapters/clickhouse/index.js

@@ -0,0 +1,1544 @@
+// packages/text2sql/src/lib/adapters/adapter.ts
+import { format as formatSql } from "sql-formatter";
+
+// packages/text2sql/src/lib/agents/exceptions.ts
+var sqlValidationMarker = /* @__PURE__ */ Symbol("SQLValidationError");
+var unanswerableSqlMarker = /* @__PURE__ */ Symbol("UnanswerableSQLError");
+var sqlScopeMarker = /* @__PURE__ */ Symbol("SQLScopeError");
+var sqlReadOnlyMarker = /* @__PURE__ */ Symbol("SQLReadOnlyError");
+var SQLValidationError = class _SQLValidationError extends Error {
+  [sqlValidationMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLValidationError";
+    this[sqlValidationMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLValidationError && error[sqlValidationMarker] === true;
+  }
+};
+var UnanswerableSQLError = class _UnanswerableSQLError extends Error {
+  [unanswerableSqlMarker];
+  constructor(message) {
+    super(message);
+    this.name = "UnanswerableSQLError";
+    this[unanswerableSqlMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _UnanswerableSQLError && error[unanswerableSqlMarker] === true;
+  }
+};
+var SQLScopeError = class _SQLScopeError extends Error {
+  [sqlScopeMarker];
+  payload;
+  errorType;
+  constructor(payload) {
+    super(JSON.stringify(payload));
+    this.name = "SQLScopeError";
+    this.payload = payload;
+    this.errorType = payload.error_type;
+    this[sqlScopeMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLScopeError && error[sqlScopeMarker] === true;
+  }
+};
+var SQLReadOnlyError = class _SQLReadOnlyError extends Error {
+  [sqlReadOnlyMarker];
+  constructor(message) {
+    super(message);
+    this.name = "SQLReadOnlyError";
+    this[sqlReadOnlyMarker] = true;
+  }
+  static isInstance(error) {
+    return error instanceof _SQLReadOnlyError && error[sqlReadOnlyMarker] === true;
+  }
+};
+
+// packages/text2sql/src/lib/fragments/schema.ts
+function dialectInfo(input) {
+  return {
+    name: "dialectInfo",
+    data: {
+      dialect: input.dialect,
+      ...input.version && { version: input.version },
+      ...input.database && { database: input.database },
+      ...input.details && { details: input.details }
+    }
+  };
+}
+function table(input) {
+  return {
+    name: "table",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      ...input.rowCount != null && { rowCount: input.rowCount },
+      ...input.sizeHint && { sizeHint: input.sizeHint },
+      columns: input.columns,
+      ...input.indexes?.length && { indexes: input.indexes },
+      ...input.constraints?.length && { constraints: input.constraints }
+    }
+  };
+}
+function column(input) {
+  return {
+    name: "column",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.pk && { pk: true },
+      ...input.fk && { fk: input.fk },
+      ...input.unique && { unique: true },
+      ...input.notNull && { notNull: true },
+      ...input.default && { default: input.default },
+      ...input.indexed && { indexed: true },
+      ...input.values?.length && { values: input.values },
+      ...input.stats && { stats: input.stats }
+    }
+  };
+}
+function index(input) {
+  return {
+    name: "index",
+    data: {
+      name: input.name,
+      columns: input.columns,
+      ...input.unique && { unique: true },
+      ...input.type && { type: input.type }
+    }
+  };
+}
+function constraint(input) {
+  return {
+    name: "constraint",
+    data: {
+      name: input.name,
+      type: input.type,
+      ...input.columns?.length && { columns: input.columns },
+      ...input.definition && { definition: input.definition },
+      ...input.defaultValue && { defaultValue: input.defaultValue },
+      ...input.referencedTable && { referencedTable: input.referencedTable },
+      ...input.referencedColumns?.length && {
+        referencedColumns: input.referencedColumns
+      }
+    }
+  };
+}
+function view(input) {
+  return {
+    name: "view",
+    data: {
+      name: input.name,
+      ...input.schema && { schema: input.schema },
+      columns: input.columns,
+      ...input.definition && { definition: input.definition }
+    }
+  };
+}
+function relationship(input) {
+  return {
+    name: "relationship",
+    data: {
+      from: input.from,
+      to: input.to,
+      ...input.cardinality && { cardinality: input.cardinality }
+    }
+  };
+}
+
+// packages/text2sql/src/lib/adapters/groundings/context.ts
+var noopProgress = () => {
+};
+function timestampProgress(onProgress) {
+  if (!onProgress) return noopProgress;
+  return (progress) => {
+    onProgress({
+      ...progress,
+      timestampMs: progress.timestampMs ?? Date.now()
+    });
+  };
+}
+function createGroundingContext(options = {}) {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0,
+    cache: /* @__PURE__ */ new Map(),
+    onProgress: timestampProgress(options.onProgress)
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  #policyAnalyzer;
+  /**
+   * Injects the strategy that guards validate() and execute().
+   */
+  constructor(policyAnalyzer) {
+    this.#policyAnalyzer = policyAnalyzer;
+  }
+  /**
+   * Introspect the database schema and return context fragments.
+   *
+   * Executes all configured groundings to populate the context, then
+   * generates fragments from the complete context data.
+   *
+   * @param ctx - Optional grounding context for sharing state between groundings
+   * @returns Array of context fragments representing the database schema
+   */
+  async introspect(ctx = createGroundingContext()) {
+    for (const fn of this.grounding) {
+      const grounding = fn(this);
+      if (grounding.phase) {
+        ctx.onProgress({
+          type: "phase:start",
+          phase: grounding.phase,
+          message: `Starting ${grounding.name} introspection...`
+        });
+      }
+      try {
+        await grounding.execute(ctx);
+      } finally {
+        if (grounding.phase) {
+          ctx.onProgress({
+            type: "phase:end",
+            phase: grounding.phase,
+            message: `Finished ${grounding.name} introspection.`
+          });
+        }
+      }
+    }
+    return this.#toSchemaFragments(ctx);
+  }
+  /**
+   * Resolve the allowed entity names (tables + views) from grounding config.
+   * Asks each grounding to contribute its entities; annotators contribute
+   * nothing, so their metadata scans are skipped.
+   * Results are NOT cached — call once and store the result.
+   */
+  async resolveAllowedEntities() {
+    const ctx = createGroundingContext();
+    for (const fn of this.grounding) {
+      await fn(this).contributeEntities(ctx);
+    }
+    return [...ctx.tables.map((t) => t.name), ...ctx.views.map((v) => v.name)];
+  }
+  /**
+   * Convert complete grounding context to schema fragments.
+   * Called after all groundings have populated ctx with data.
+   */
+  #toSchemaFragments(ctx) {
+    const fragments = [];
+    if (ctx.info) {
+      fragments.push(
+        dialectInfo({
+          dialect: ctx.info.dialect,
+          version: ctx.info.version,
+          database: ctx.info.database,
+          details: ctx.info.details
+        })
+      );
+    }
+    for (const t of ctx.tables) {
+      fragments.push(this.#tableToFragment(t));
+    }
+    for (const v of ctx.views) {
+      fragments.push(this.#viewToFragment(v));
+    }
+    const tableMap = new Map(ctx.tables.map((t) => [t.name, t]));
+    const tableColumnSets = new Map(
+      ctx.tables.map((t) => [t.name, new Set(t.columns.map((c) => c.name))])
+    );
+    for (const rel of ctx.relationships) {
+      const sourceColumns = tableColumnSets.get(rel.table);
+      const targetColumns = tableColumnSets.get(rel.referenced_table);
+      if (sourceColumns && rel.from.some((column2) => !sourceColumns.has(column2))) {
+        continue;
+      }
+      if (targetColumns && rel.to.some((column2) => !targetColumns.has(column2))) {
+        continue;
+      }
+      const sourceTable = tableMap.get(rel.table);
+      const targetTable = tableMap.get(rel.referenced_table);
+      fragments.push(
+        this.#relationshipToFragment(rel, sourceTable, targetTable)
+      );
+    }
+    return fragments;
+  }
+  /**
+   * Convert a Table to a table fragment with nested column, index, and constraint fragments.
+   */
+  #tableToFragment(t) {
+    const pkConstraint = t.constraints?.find((c) => c.type === "PRIMARY_KEY");
+    const pkColumns = new Set(pkConstraint?.columns ?? []);
+    const notNullColumns = new Set(
+      t.constraints?.filter((c) => c.type === "NOT_NULL").flatMap((c) => c.columns ?? []) ?? []
+    );
+    const defaultByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "DEFAULT") ?? []) {
+      for (const col of c.columns ?? []) {
+        if (c.defaultValue != null) {
+          defaultByColumn.set(col, c.defaultValue);
+        }
+      }
+    }
+    const uniqueColumns = new Set(
+      t.constraints?.filter((c) => c.type === "UNIQUE" && c.columns?.length === 1).flatMap((c) => c.columns ?? []) ?? []
+    );
+    const fkByColumn = /* @__PURE__ */ new Map();
+    for (const c of t.constraints?.filter((c2) => c2.type === "FOREIGN_KEY") ?? []) {
+      const cols = c.columns ?? [];
+      const refCols = c.referencedColumns ?? [];
+      for (let i = 0; i < cols.length; i++) {
+        const refCol = refCols[i] ?? refCols[0] ?? cols[i];
+        fkByColumn.set(cols[i], `${c.referencedTable}.${refCol}`);
+      }
+    }
+    const columnFragments = t.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        pk: pkColumns.has(col.name) || void 0,
+        fk: fkByColumn.get(col.name),
+        unique: uniqueColumns.has(col.name) || void 0,
+        notNull: notNullColumns.has(col.name) || void 0,
+        default: defaultByColumn.get(col.name),
+        indexed: col.isIndexed || void 0,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    const presentColumns = new Set(t.columns.map((c) => c.name));
+    const indexFragments = (t.indexes ?? []).filter(
+      (idx) => idx.columns.every((column2) => presentColumns.has(column2))
+    ).map(
+      (idx) => index({
+        name: idx.name,
+        columns: idx.columns,
+        unique: idx.unique,
+        type: idx.type
+      })
+    );
+    const constraintFragments = (t.constraints ?? []).filter(
+      (c) => c.type === "CHECK" || c.type === "UNIQUE" && (c.columns?.length ?? 0) > 1
+    ).filter(
+      (c) => !c.columns?.length || c.columns.every((column2) => presentColumns.has(column2))
+    ).map(
+      (c) => constraint({
+        name: c.name,
+        type: c.type,
+        columns: c.columns,
+        definition: c.definition
+      })
+    );
+    return table({
+      name: t.name,
+      schema: t.schema,
+      rowCount: t.rowCount,
+      sizeHint: t.sizeHint,
+      columns: columnFragments,
+      indexes: indexFragments.length > 0 ? indexFragments : void 0,
+      constraints: constraintFragments.length > 0 ? constraintFragments : void 0
+    });
+  }
+  /**
+   * Convert a View to a view fragment with nested column fragments.
+   */
+  #viewToFragment(v) {
+    const columnFragments = v.columns.map(
+      (col) => column({
+        name: col.name,
+        type: col.type,
+        values: col.values,
+        stats: col.stats
+      })
+    );
+    return view({
+      name: v.name,
+      schema: v.schema,
+      columns: columnFragments,
+      definition: v.definition
+    });
+  }
+  /**
+   * Convert a Relationship to a relationship fragment.
+   * Infers cardinality from row counts if available.
+   */
+  #relationshipToFragment(rel, sourceTable, targetTable) {
+    const sourceCount = sourceTable?.rowCount;
+    const targetCount = targetTable?.rowCount;
+    let cardinality;
+    if (sourceCount != null && targetCount != null && targetCount > 0) {
+      const ratio = sourceCount / targetCount;
+      if (ratio > 5) {
+        cardinality = "many-to-one";
+      } else if (ratio < 1.2 && ratio > 0.8) {
+        cardinality = "one-to-one";
+      } else if (ratio < 0.2) {
+        cardinality = "one-to-many";
+      }
+    }
+    return relationship({
+      from: { table: rel.table, columns: rel.from },
+      to: { table: rel.referenced_table, columns: rel.to },
+      cardinality
+    });
+  }
+  format(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    try {
+      return formatSql(decoded, { language: this.formatterLanguage });
+    } catch {
+      return decoded;
+    }
+  }
+  #decodeShellEscapes(sql) {
+    return sql.replace(/\\n/g, "\n").replace(/\\t/g, "	").replace(/\\([().*])/g, "$1").replace(/\\(?=$)/gm, "");
+  }
+  #cachedAllowedEntities = null;
+  async #resolveScope() {
+    if (this.#cachedAllowedEntities) return this.#cachedAllowedEntities;
+    this.#cachedAllowedEntities = await this.resolveAllowedEntities();
+    return this.#cachedAllowedEntities;
+  }
+  async #analyzePolicy(sql) {
+    return this.#policyAnalyzer.analyze(sql, {
+      resolveAllowedEntities: () => this.#resolveScope()
+    });
+  }
+  async validate(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") return violation.message;
+    if (violation?.kind === "scope") return JSON.stringify(violation.payload);
+    return this.validateImpl(decoded);
+  }
+  async execute(sql) {
+    const decoded = this.#decodeShellEscapes(sql);
+    const violation = await this.#analyzePolicy(decoded);
+    if (violation?.kind === "read-only") {
+      throw new SQLReadOnlyError(violation.message);
+    }
+    if (violation?.kind === "scope") {
+      throw new SQLScopeError(violation.payload);
+    }
+    return this.executeImpl(decoded);
+  }
+  /**
+   * Convert unknown database value to number.
+   * Handles number, bigint, and string types.
+   */
+  toNumber(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+    if (typeof value === "bigint") {
+      return Number(value);
+    }
+    if (typeof value === "string" && value.trim() !== "") {
+      const parsed = Number(value);
+      return Number.isFinite(parsed) ? parsed : void 0;
+    }
+    return void 0;
+  }
+  /**
+   * Parse a potentially qualified table name into schema and table parts.
+   */
+  parseTableName(name) {
+    if (name.includes(".")) {
+      const [schema, ...rest] = name.split(".");
+      return { schema, table: rest.join(".") };
+    }
+    return { schema: this.defaultSchema ?? "", table: name };
+  }
+  /**
+   * Escape a string value for use in SQL string literals (single quotes).
+   * Used in WHERE clauses like: WHERE name = '${escapeString(value)}'
+   */
+  escapeString(value) {
+    return value.replace(/'/g, "''");
+  }
+  /**
+   * Build a SQL filter clause to include/exclude schemas.
+   * @param columnName - The schema column name (e.g., 'TABLE_SCHEMA')
+   * @param allowedSchemas - If provided, filter to these schemas only
+   */
+  buildSchemaFilter(columnName, allowedSchemas) {
+    if (allowedSchemas && allowedSchemas.length > 0) {
+      const values = allowedSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} IN (${values})`;
+    }
+    if (this.systemSchemas.length > 0) {
+      const values = this.systemSchemas.map((s) => `'${this.escapeString(s)}'`).join(", ");
+      return `AND ${columnName} NOT IN (${values})`;
+    }
+    return "";
+  }
+};
+
+// packages/text2sql/src/lib/sql-scope-error.ts
+function buildScopeParseErrorPayload(sql, parserDialect, error) {
+  const parserError = error instanceof Error ? error.message : String(error ?? "Unknown error");
+  return {
+    error: `SQL scope analysis failed before validation/execution: ${parserError}`,
+    error_type: "SQL_SCOPE_PARSE_ERROR",
+    suggestion: "Rewrite the query into simpler SQL that can be analyzed safely, or extend parser coverage for this dialect feature.",
+    sql_attempted: sql,
+    parser_dialect: parserDialect,
+    parser_error: parserError
+  };
+}
+
+// packages/text2sql/src/lib/adapters/clickhouse/clickhouse.sql-policy.ts
+var READ_ONLY_MESSAGE = "only SELECT queries allowed";
+var ClickHouseSqlPolicyAnalyzer = class {
+  #query;
+  #readonlyCheck;
+  #currentDatabase;
+  constructor(query) {
+    this.#query = query;
+  }
+  async analyze(sql, context) {
+    try {
+      await (this.#readonlyCheck ??= this.#verifyReadonly());
+      const ast = await this.#explain(`EXPLAIN AST ${sql}`);
+      const astAnalysis = analyzeAst(ast);
+      if (!astAnalysis.isSelect) {
+        return { kind: "read-only", message: READ_ONLY_MESSAGE };
+      }
+      if (await this.#hasUnsafeFunction(astAnalysis.functions)) {
+        return { kind: "read-only", message: READ_ONLY_MESSAGE };
+      }
+      const syntacticTree = await this.#explain(
+        `EXPLAIN QUERY TREE run_passes = 0 ${sql}`
+      );
+      const analyzedTree = await this.#explain(`EXPLAIN QUERY TREE ${sql}`);
+      const syntacticRelations = readQueryTreeRelations(
+        syntacticTree,
+        "syntactic"
+      );
+      const analyzedRelations = readQueryTreeRelations(
+        analyzedTree,
+        "analyzed"
+      );
+      if (!this.#currentDatabase) {
+        throw new Error("ClickHouse current database was not established.");
+      }
+      const relations = [
+        ...new Set(
+          [...syntacticRelations, ...analyzedRelations].map(
+            (relation) => qualifyRelation(relation, this.#currentDatabase)
+          )
+        )
+      ];
+      const allowed = await context.resolveAllowedEntities();
+      const rejected = relations.filter(
+        (relation) => !isAllowedRelation(relation, allowed)
+      );
+      return rejected.length ? {
+        kind: "scope",
+        payload: buildOutOfScopePayload(sql, rejected, [...allowed])
+      } : null;
+    } catch (error) {
+      return {
+        kind: "scope",
+        payload: buildScopeParseErrorPayload(sql, "clickhouse", error)
+      };
+    }
+  }
+  async #verifyReadonly() {
+    const rows = readRows(
+      await this.#query(
+        "SELECT getSetting('readonly') AS readonly, currentDatabase() AS database"
+      )
+    );
+    const row = rows[0];
+    if (rows.length !== 1 || !row || Object.keys(row).length !== 2 || typeof row.database !== "string" || row.database.length === 0) {
+      throw new Error(
+        "ClickHouse readonly probe returned an unknown row shape."
+      );
+    }
+    const value = row.readonly;
+    if (value !== 1 && value !== "1") {
+      throw new Error(
+        `ClickHouse connection must have effective readonly = 1; received ${String(value)}.`
+      );
+    }
+    this.#currentDatabase = row.database;
+  }
+  async #explain(sql) {
+    const rows = readRows(await this.#query(sql));
+    if (rows.length === 0) {
+      throw new Error("ClickHouse EXPLAIN returned no rows.");
+    }
+    return rows.map((row) => {
+      if (Object.keys(row).length !== 1 || typeof row.explain !== "string") {
+        throw new Error(
+          "ClickHouse EXPLAIN must return rows with exactly one string `explain` column."
+        );
+      }
+      return row.explain;
+    });
+  }
+  async #hasUnsafeFunction(functions) {
+    if (functions.some(isScopeBypassingFunction)) return true;
+    if (functions.length === 0) return false;
+    const names = [...new Set(functions)].map((name) => `'${name.replaceAll("'", "''")}'`).join(", ");
+    const rows = readRows(
+      await this.#query(`
+        SELECT name, toString(origin) AS origin
+        FROM system.functions
+        WHERE name IN (${names})
+          AND origin != 'System'
+      `)
+    );
+    for (const row of rows) {
+      if (typeof row.name !== "string" || typeof row.origin !== "string") {
+        throw new Error(
+          "ClickHouse system.functions returned an unknown row shape."
+        );
+      }
+      if (row.origin !== "SQLUserDefined" && row.origin !== "ExecutableUserDefined" && row.origin !== "WasmUserDefined") {
+        throw new Error(`Unknown ClickHouse function origin: ${row.origin}`);
+      }
+    }
+    return rows.length > 0;
+  }
+};
+function isScopeBypassingFunction(name) {
+  const normalized = name.toLocaleLowerCase("en-US");
+  return normalized.startsWith("dict") || normalized.startsWith("joinget");
+}
+function readRows(result) {
+  const rows = Array.isArray(result) ? result : result && typeof result === "object" && "data" in result ? result.data : result && typeof result === "object" && "rows" in result ? result.rows : void 0;
+  if (!Array.isArray(rows) || rows.some((row) => !isRecord(row))) {
+    throw new Error(
+      "ClickHouse query callback must return row objects as an array, { data }, or { rows }."
+    );
+  }
+  return rows;
+}
+function analyzeAst(lines) {
+  const rootLines = lines.filter(
+    (line) => line.length - line.trimStart().length === 0
+  );
+  if (rootLines.length !== 1 || !rootLines[0]?.startsWith("SelectWithUnionQuery")) {
+    return { isSelect: false, functions: [] };
+  }
+  const roots = parseIndentedTree(lines, validateAstLine);
+  const root = roots[0];
+  const isSelect = roots.length === 1 && !!root && !root.children.some((child) => child.text.startsWith("Literal ")) && !containsTableFunction(root);
+  return {
+    isSelect,
+    functions: isSelect && root ? collectAstFunctions(root) : []
+  };
+}
+function validateAstLine(text) {
+  const type = /^([A-Za-z][A-Za-z0-9]*)/.exec(text)?.[1];
+  const allowed = /* @__PURE__ */ new Set([
+    "ArrayJoin",
+    "Asterisk",
+    "ExpressionList",
+    "Function",
+    "Identifier",
+    "Literal",
+    "OrderByElement",
+    "SelectQuery",
+    "SelectWithUnionQuery",
+    "Subquery",
+    "TableExpression",
+    "TableIdentifier",
+    "TableJoin",
+    "TablesInSelectQuery",
+    "TablesInSelectQueryElement",
+    "WithElement",
+    "WindowDefinition"
+  ]);
+  if (!type || !allowed.has(type)) {
+    throw new Error(`Unknown ClickHouse AST node: ${text}`);
+  }
+}
+function containsTableFunction(node) {
+  if (node.text.startsWith("TableExpression") && node.children.some((child) => child.text.startsWith("Function "))) {
+    return true;
+  }
+  return node.children.some(containsTableFunction);
+}
+function collectAstFunctions(node) {
+  const functions = [];
+  if (node.text.startsWith("Function ")) {
+    const name = /^Function (\S+)/.exec(node.text)?.[1];
+    if (!name) throw new Error(`Unknown ClickHouse AST function: ${node.text}`);
+    functions.push(name);
+  }
+  for (const child of node.children)
+    functions.push(...collectAstFunctions(child));
+  return functions;
+}
+function readQueryTreeRelations(lines, phase) {
+  const roots = parseIndentedTree(
+    lines,
+    (text, parent) => validateQueryTreeLine(text, parent)
+  );
+  if (roots.length !== 1 || !roots[0]?.text.startsWith("QUERY ") && !roots[0]?.text.startsWith("UNION ")) {
+    throw new Error(`Unknown ClickHouse ${phase} query-tree root.`);
+  }
+  const relations = [];
+  const cteNames = /* @__PURE__ */ new Set();
+  collectCteNames(roots[0], cteNames);
+  visitQueryTree(roots[0], false, phase, cteNames, relations);
+  return relations;
+}
+function validateQueryTreeLine(text, parent) {
+  const nodePatterns = [
+    /^QUERY id:/,
+    /^UNION id:/,
+    /^QUERIES$/,
+    /^PROJECTION(?: COLUMNS)?$/,
+    /^WITH$/,
+    /^LIST id:/,
+    /^MATCHER id:/,
+    /^COLUMN id:/,
+    /^JOIN TREE$/,
+    /^ARRAY_JOIN id:/,
+    /^IDENTIFIER id:/,
+    /^TABLE id:/,
+    /^JOIN id:/,
+    /^(?:(?:LEFT|RIGHT) )?TABLE EXPRESSION$/,
+    /^JOIN EXPRESSIONS?$/,
+    /^FUNCTION id:/,
+    /^ARGUMENTS$/,
+    /^CONSTANT id:/,
+    /^PREWHERE$/,
+    /^WHERE$/,
+    /^WINDOW$/,
+    /^WINDOW id:/,
+    /^PARTITION BY$/,
+    /^QUALIFY$/,
+    /^GROUP BY$/,
+    /^HAVING$/,
+    /^ORDER BY$/,
+    /^SORT id:/,
+    /^EXPRESSION(?: .*)?$/,
+    /^LIMIT BY LIMIT$/,
+    /^LIMIT BY$/,
+    /^LIMIT$/,
+    /^OFFSET$/
+  ];
+  if (nodePatterns.some((pattern) => pattern.test(text))) return;
+  if (parent?.text === "PROJECTION COLUMNS" && /^\S+\s+\S+/.test(text)) {
+    return;
+  }
+  throw new Error(`Unknown ClickHouse query-tree node: ${text}`);
+}
+function visitQueryTree(node, relationPosition, phase, cteNames, relations) {
+  if (relationPosition && node.text.startsWith("IDENTIFIER ")) {
+    const identifier = /(?:^|, )identifier: (.+)$/.exec(node.text)?.[1];
+    if (!identifier) {
+      throw new Error(`Unknown ClickHouse ${phase} relation: ${node.text}`);
+    }
+    if (!cteNames.has(identifier)) {
+      relations.push(identifier);
+    }
+  } else if (relationPosition && node.text.startsWith("TABLE ")) {
+    const table2 = /(?:^|, )table_name: ([^,]+)(?:,|$)/.exec(node.text)?.[1];
+    if (!table2) {
+      throw new Error(`Unknown ClickHouse ${phase} relation: ${node.text}`);
+    }
+    relations.push(table2);
+  }
+  for (const child of node.children) {
+    const childrenAreRelations = node.text === "JOIN TREE" || node.text === "LEFT TABLE EXPRESSION" || node.text === "RIGHT TABLE EXPRESSION" || node.text === "TABLE EXPRESSION";
+    visitQueryTree(child, childrenAreRelations, phase, cteNames, relations);
+  }
+}
+function collectCteNames(node, cteNames) {
+  const name = /(?:^|, )cte_name: ([^,]+)(?:,|$)/.exec(node.text)?.[1];
+  if (name) cteNames.add(name);
+  for (const child of node.children) collectCteNames(child, cteNames);
+}
+function parseIndentedTree(lines, validate) {
+  const roots = [];
+  const stack = [];
+  for (const line of lines) {
+    if (!line.trim())
+      throw new Error("ClickHouse EXPLAIN returned an empty line.");
+    const indent = line.length - line.trimStart().length;
+    const text = line.trimStart();
+    while (stack.length && stack.at(-1).indent >= indent) stack.pop();
+    const parent = stack.at(-1)?.node;
+    validate(text, parent);
+    const node = { text, children: [] };
+    if (parent) parent.children.push(node);
+    else roots.push(node);
+    stack.push({ indent, node });
+  }
+  return roots;
+}
+function isAllowedRelation(relation, allowedEntities) {
+  return allowedEntities.includes(relation);
+}
+function qualifyRelation(relation, database) {
+  return relation.includes(".") ? relation : `${database}.${relation}`;
+}
+function buildOutOfScopePayload(sql, referencedEntities, allowedEntities) {
+  return {
+    error: `Query references entities outside grounded scope: ${referencedEntities.join(", ")}`,
+    error_type: "OUT_OF_SCOPE",
+    suggestion: "Restrict the query to grounded tables/views or expand grounding to include the referenced entities.",
+    sql_attempted: sql,
+    referenced_entities: referencedEntities,
+    allowed_entities: allowedEntities
+  };
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// packages/text2sql/src/lib/adapters/clickhouse/clickhouse.ts
+var ClickHouse = class extends Adapter {
+  #options;
+  grounding;
+  defaultSchema;
+  systemSchemas = [
+    "system",
+    "information_schema",
+    "INFORMATION_SCHEMA"
+  ];
+  formatterLanguage = "clickhouse";
+  constructor(options) {
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("ClickHouse adapter requires an execute(sql) function.");
+    }
+    if (typeof options.validate !== "function") {
+      throw new Error("ClickHouse adapter requires a validate(sql) function.");
+    }
+    super(new ClickHouseSqlPolicyAnalyzer(options.execute));
+    this.#options = options;
+    this.grounding = options.grounding ?? [];
+    this.defaultSchema = options.defaultDatabase;
+  }
+  async executeImpl(sql) {
+    return rowsFromResult(await this.#options.execute(sql));
+  }
+  async validateImpl(sql) {
+    try {
+      return await this.#options.validate(sql);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return JSON.stringify({
+        error: message,
+        error_type: "CLICKHOUSE_ERROR",
+        suggestion: "Review the ClickHouse syntax and verify referenced databases, tables, columns, and functions.",
+        sql_attempted: sql
+      });
+    }
+  }
+  async runQuery(sql) {
+    return rowsFromResult(await this.#options.execute(sql));
+  }
+  quoteIdentifier(name) {
+    return `\`${name.replace(/`/g, "``")}\``;
+  }
+  escape(value) {
+    return value.replace(/`/g, "``");
+  }
+  buildSampleRowsQuery(tableName, columns, limit) {
+    const { schema, table: table2 } = this.parseTableName(tableName);
+    const relation = schema ? `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table2)}` : this.quoteIdentifier(table2);
+    const projection = columns?.length ? columns.map((column2) => this.quoteIdentifier(column2)).join(", ") : "*";
+    return `SELECT ${projection} FROM ${relation} LIMIT ${limit}`;
+  }
+};
+function rowsFromResult(result) {
+  if (Array.isArray(result)) return result;
+  if (result && typeof result === "object") {
+    const candidate = result;
+    if (Array.isArray(candidate.data)) return candidate.data;
+    if (Array.isArray(candidate.rows)) return candidate.rows;
+  }
+  throw new Error(
+    "ClickHouse execute() must return an array of rows, { data: rows }, or { rows }."
+  );
+}
+
+// packages/text2sql/src/lib/adapters/groundings/abstract.grounding.ts
+function filterColumns(columns, filter) {
+  if (Array.isArray(filter)) {
+    return columns.filter((col) => filter.includes(col.name));
+  }
+  if (filter instanceof RegExp) {
+    return columns.filter((col) => filter.test(col.name));
+  }
+  return columns.filter((col) => filter(col.name));
+}
+function applyColumnFilter(entity, columnsConfig) {
+  if (!columnsConfig) return entity;
+  const filter = columnsConfig[entity.name];
+  if (!filter) return entity;
+  return { ...entity, columns: filterColumns(entity.columns, filter) };
+}
+var AbstractGrounding = class {
+  /**
+   * Grounding identifier for debugging/logging.
+   */
+  name;
+  phase;
+  constructor(name, phase) {
+    this.name = name;
+    this.phase = phase;
+  }
+  /**
+   * Populate ctx with the tables/views this grounding makes available for scope
+   * resolution. Annotators decorate entities other groundings produced and add
+   * no membership, so the default is a no-op; entity-producing groundings
+   * override it. This lets scope resolution skip the annotators' metadata scans.
+   *
+   * @param _ctx - Shared context for accumulating entity membership
+   */
+  async contributeEntities(_ctx) {
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraint", "constraints");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their constraints.
+   */
+  async execute(ctx) {
+    const total = ctx.tables.length;
+    for (let i = 0; i < ctx.tables.length; i++) {
+      const table2 = ctx.tables[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "constraints",
+        table: table2.name,
+        message: `Loading constraints for ${table2.name}...`,
+        current: i + 1,
+        total
+      });
+      try {
+        table2.constraints = await this.getConstraints(table2.name);
+      } catch (error) {
+        console.warn("Error collecting constraints for", table2.name, error);
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/constraint.clickhouse.grounding.ts
+var ClickHouseConstraintGrounding = class extends ConstraintGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getConstraints(tableName) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    if (!schema) return [];
+    const rows = await this.#adapter.runQuery(`
+      SELECT name, type, default_kind, default_expression, is_in_primary_key
+      FROM system.columns
+      WHERE database = '${this.#adapter.escapeString(schema)}'
+        AND table = '${this.#adapter.escapeString(table2)}'
+      ORDER BY position
+    `);
+    const constraints2 = [];
+    const primaryKey = rows.filter((row) => Number(row.is_in_primary_key) === 1).map((row) => row.name);
+    if (primaryKey.length > 0) {
+      constraints2.push({
+        name: "PRIMARY_KEY",
+        type: "PRIMARY_KEY",
+        columns: primaryKey
+      });
+    }
+    for (const row of rows) {
+      if (!hasNullableType(row.type)) {
+        constraints2.push({
+          name: `${row.name}_not_null`,
+          type: "NOT_NULL",
+          columns: [row.name]
+        });
+      }
+      if (row.default_kind === "DEFAULT" && row.default_expression) {
+        constraints2.push({
+          name: `${row.name}_default`,
+          type: "DEFAULT",
+          columns: [row.name],
+          defaultValue: row.default_expression
+        });
+      }
+    }
+    return constraints2;
+  }
+};
+function hasNullableType(type) {
+  return /(?:^|\()Nullable\(/.test(type);
+}
+
+// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
+var IndexesGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("index", "indexes");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   */
+  async execute(ctx) {
+    const total = ctx.tables.length;
+    for (let i = 0; i < ctx.tables.length; i++) {
+      const table2 = ctx.tables[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "indexes",
+        table: table2.name,
+        message: `Loading indexes for ${table2.name}...`,
+        current: i + 1,
+        total
+      });
+      table2.indexes = await this.getIndexes(table2.name);
+      for (const index2 of table2.indexes ?? []) {
+        for (const colName of index2.columns) {
+          const column2 = table2.columns.find((c) => c.name === colName);
+          if (column2) {
+            column2.isIndexed = true;
+          }
+        }
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/indexes.clickhouse.grounding.ts
+var ClickHouseIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getIndexes(tableName) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    if (!schema) return [];
+    const [primaryKeyRows, indexRows] = await Promise.all([
+      this.#adapter.runQuery(`
+        SELECT name
+        FROM system.columns
+        WHERE database = '${this.#adapter.escapeString(schema)}'
+          AND table = '${this.#adapter.escapeString(table2)}'
+          AND is_in_primary_key = 1
+        ORDER BY position
+      `),
+      this.#adapter.runQuery(`
+        SELECT name, type_full AS type, expr AS expression
+        FROM system.data_skipping_indices
+        WHERE database = '${this.#adapter.escapeString(schema)}'
+          AND table = '${this.#adapter.escapeString(table2)}'
+        ORDER BY name
+      `)
+    ]);
+    const indexes2 = [];
+    if (primaryKeyRows.length > 0) {
+      indexes2.push({
+        name: "PRIMARY_KEY",
+        columns: primaryKeyRows.map((row) => row.name),
+        type: "PRIMARY_KEY"
+      });
+    }
+    indexes2.push(
+      ...indexRows.map((row) => ({
+        name: row.name,
+        columns: splitTopLevelExpressions(row.expression),
+        type: row.type
+      }))
+    );
+    return indexes2;
+  }
+};
+function splitTopLevelExpressions(expression) {
+  const parts = [];
+  let start = 0;
+  let depth = 0;
+  for (let index2 = 0; index2 < expression.length; index2++) {
+    const character = expression[index2];
+    if (character === "(" || character === "[") depth++;
+    if (character === ")" || character === "]") depth--;
+    if (character === "," && depth === 0) {
+      parts.push(expression.slice(start, index2).trim());
+      start = index2 + 1;
+    }
+  }
+  parts.push(expression.slice(start).trim());
+  return parts.filter(Boolean);
+}
+
+// packages/text2sql/src/lib/adapters/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialectInfo", "info");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/info.clickhouse.grounding.ts
+var ClickHouseInfoGrounding = class extends InfoGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async collectInfo() {
+    const rows = await this.#adapter.runQuery(
+      "SELECT version() AS version, currentDatabase() AS database"
+    );
+    const row = rows[0];
+    return {
+      dialect: "clickhouse",
+      version: row?.version,
+      database: row?.database || void 0,
+      details: {
+        identifierQuote: "`",
+        qualifiedTable: "database.table"
+      }
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("rowCount", "row_counts");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with row counts and size hints.
+   */
+  async execute(ctx) {
+    const total = ctx.tables.length;
+    for (let i = 0; i < ctx.tables.length; i++) {
+      const table2 = ctx.tables[i];
+      ctx.onProgress({
+        type: "phase:progress",
+        phase: "row_counts",
+        table: table2.name,
+        message: `Counting rows in ${table2.name}...`,
+        current: i + 1,
+        total
+      });
+      const count = await this.getRowCount(table2.name);
+      if (count != null) {
+        table2.rowCount = count;
+        table2.sizeHint = this.#classifyRowCount(count);
+      }
+    }
+  }
+  /**
+   * Classify row count into a size hint category.
+   */
+  #classifyRowCount(count) {
+    if (count < 100) return "tiny";
+    if (count < 1e3) return "small";
+    if (count < 1e4) return "medium";
+    if (count < 1e5) return "large";
+    return "huge";
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/row-count.clickhouse.grounding.ts
+var ClickHouseRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getRowCount(tableName) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    const relation = schema ? `${this.#adapter.quoteIdentifier(schema)}.${this.#adapter.quoteIdentifier(table2)}` : this.#adapter.quoteIdentifier(table2);
+    try {
+      const rows = await this.#adapter.runQuery(`SELECT count() AS count FROM ${relation}`);
+      return toNumber(rows[0]?.count);
+    } catch {
+      return void 0;
+    }
+  }
+};
+function toNumber(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "bigint") return Number(value);
+  if (typeof value === "string" && value.trim()) {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return void 0;
+}
+
+// packages/text2sql/src/lib/adapters/groundings/table.grounding.ts
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #columns;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("table", "tables");
+    this.#filter = config.filter;
+    this.#columns = config.columns;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered tables and relationships to the context.
+   */
+  async execute(ctx) {
+    const seedTables = await this.applyFilter();
+    const forward = this.#forward;
+    const backward = this.#backward;
+    if (!forward && !backward) {
+      const tables3 = await Promise.all(
+        seedTables.map(async (name, index2) => {
+          ctx.onProgress({
+            type: "phase:progress",
+            phase: "tables",
+            table: name,
+            message: `Loading table ${name}...`,
+            current: index2 + 1,
+            total: seedTables.length
+          });
+          return applyColumnFilter(await this.getTable(name), this.#columns);
+        })
+      );
+      ctx.tables.push(...tables3);
+      return;
+    }
+    const tables2 = {};
+    const allRelationships = [];
+    const seenRelationships = /* @__PURE__ */ new Set();
+    const forwardQueue = [];
+    const backwardQueue = [];
+    const forwardVisited = /* @__PURE__ */ new Set();
+    const backwardVisited = /* @__PURE__ */ new Set();
+    let loadedCount = 0;
+    for (const name of seedTables) {
+      if (forward) forwardQueue.push({ name, depth: 0 });
+      if (backward) backwardQueue.push({ name, depth: 0 });
+    }
+    const forwardLimit = forward === true ? Infinity : forward || 0;
+    while (forwardQueue.length > 0) {
+      const item = forwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (forwardVisited.has(name)) continue;
+      forwardVisited.add(name);
+      if (!tables2[name]) {
+        loadedCount++;
+        ctx.onProgress({
+          type: "phase:progress",
+          phase: "tables",
+          table: name,
+          message: `Loading table ${name}...`,
+          current: loadedCount
+        });
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          if (!this.isRelationshipVisible(rel)) continue;
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!forwardVisited.has(rel.referenced_table)) {
+            forwardQueue.push({ name: rel.referenced_table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const backwardLimit = backward === true ? Infinity : backward || 0;
+    while (backwardQueue.length > 0) {
+      const item = backwardQueue.shift();
+      if (!item) break;
+      const { name, depth } = item;
+      if (backwardVisited.has(name)) continue;
+      backwardVisited.add(name);
+      if (!tables2[name]) {
+        loadedCount++;
+        ctx.onProgress({
+          type: "phase:progress",
+          phase: "tables",
+          table: name,
+          message: `Loading table ${name}...`,
+          current: loadedCount
+        });
+        tables2[name] = applyColumnFilter(
+          await this.getTable(name),
+          this.#columns
+        );
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          if (!this.isRelationshipVisible(rel)) continue;
+          this.addRelationship(rel, allRelationships, seenRelationships);
+          if (!backwardVisited.has(rel.table)) {
+            backwardQueue.push({ name: rel.table, depth: depth + 1 });
+          }
+        }
+      }
+    }
+    const tablesList = Object.values(tables2);
+    ctx.tables.push(...tablesList);
+    ctx.relationships.push(...allRelationships);
+  }
+  /**
+   * Apply the filter to get seed table names.
+   * If filter is an explicit array, skip querying all table names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllTableNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+  /**
+   * Add a relationship to the collection, deduplicating by key.
+   */
+  addRelationship(rel, all, seen) {
+    const key = `${rel.table}:${rel.from.join(",")}:${rel.referenced_table}:${rel.to.join(",")}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      all.push(rel);
+    }
+  }
+  isRelationshipVisible(rel) {
+    return this.areColumnsVisible(rel.from, this.#columns?.[rel.table]) && this.areColumnsVisible(rel.to, this.#columns?.[rel.referenced_table]);
+  }
+  areColumnsVisible(names, filter) {
+    if (!filter) return true;
+    return filterColumns(
+      names.map((name) => ({ name })),
+      filter
+    ).length === names.length;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/table.clickhouse.grounding.ts
+var ClickHouseTableGrounding = class extends TableGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getAllTableNames() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT concat(database, '.', name) AS name
+      FROM system.tables
+      WHERE database NOT IN ('system', 'information_schema', 'INFORMATION_SCHEMA')
+        AND is_temporary = 0
+        AND engine != 'View'
+      ORDER BY database, name
+    `);
+    return rows.map((row) => row.name);
+  }
+  async getTable(tableName) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(tableName);
+    if (!schema) {
+      throw new Error(
+        `ClickHouse table grounding requires a qualified table name: ${tableName}`
+      );
+    }
+    const rows = await this.#adapter.runQuery(`
+      SELECT name, type
+      FROM system.columns
+      WHERE database = '${this.#adapter.escapeString(schema)}'
+        AND table = '${this.#adapter.escapeString(table2)}'
+      ORDER BY position
+    `);
+    return {
+      name: tableName,
+      schema,
+      rawName: table2,
+      columns: rows.map((row) => ({ name: row.name, type: row.type }))
+    };
+  }
+  async findOutgoingRelations() {
+    return [];
+  }
+  async findIncomingRelations() {
+    return [];
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  #columns;
+  includeDefinition;
+  constructor(config = {}) {
+    super("view", "views");
+    this.#filter = config.filter;
+    this.#columns = config.columns;
+    this.includeDefinition = config.includeDefinition ?? true;
+  }
+  async contributeEntities(ctx) {
+    await this.execute(ctx);
+  }
+  /**
+   * Execute the grounding process.
+   * Writes discovered views to the context.
+   */
+  async execute(ctx) {
+    const viewNames = await this.applyFilter();
+    const views2 = await Promise.all(
+      viewNames.map(async (name, index2) => {
+        ctx.onProgress({
+          type: "phase:progress",
+          phase: "views",
+          table: name,
+          message: `Loading view ${name}...`,
+          current: index2 + 1,
+          total: viewNames.length
+        });
+        return applyColumnFilter(await this.getView(name), this.#columns);
+      })
+    );
+    ctx.views.push(...views2);
+  }
+  /**
+   * Apply the filter to get view names.
+   * If filter is an explicit array, skip querying all view names.
+   */
+  async applyFilter() {
+    const filter = this.#filter;
+    if (Array.isArray(filter)) {
+      return filter;
+    }
+    const names = await this.getAllViewNames();
+    if (!filter) {
+      return names;
+    }
+    if (filter instanceof RegExp) {
+      return names.filter((name) => filter.test(name));
+    }
+    return names.filter(filter);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/view.clickhouse.grounding.ts
+var ClickHouseViewGrounding = class extends ViewGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getAllViewNames() {
+    const rows = await this.#adapter.runQuery(`
+      SELECT concat(database, '.', name) AS name
+      FROM system.tables
+      WHERE database NOT IN ('system', 'information_schema', 'INFORMATION_SCHEMA')
+        AND is_temporary = 0
+        AND endsWith(engine, 'View')
+      ORDER BY database, name
+    `);
+    return rows.map((row) => row.name);
+  }
+  async getView(viewName) {
+    const { schema, table: table2 } = this.#adapter.parseTableName(viewName);
+    if (!schema) {
+      throw new Error(
+        `ClickHouse view grounding requires a qualified view name: ${viewName}`
+      );
+    }
+    const [columns, definitionRows] = await Promise.all([
+      this.#adapter.runQuery(`
+        SELECT name, type
+        FROM system.columns
+        WHERE database = '${this.#adapter.escapeString(schema)}'
+          AND table = '${this.#adapter.escapeString(table2)}'
+        ORDER BY position
+      `),
+      this.includeDefinition ? this.#adapter.runQuery(`
+            SELECT create_table_query AS definition
+            FROM system.tables
+            WHERE database = '${this.#adapter.escapeString(schema)}'
+              AND name = '${this.#adapter.escapeString(table2)}'
+              AND endsWith(engine, 'View')
+          `) : Promise.resolve([])
+    ]);
+    return {
+      name: viewName,
+      schema,
+      rawName: table2,
+      definition: definitionRows[0]?.definition,
+      columns: columns.map((column2) => ({
+        name: column2.name,
+        type: column2.type
+      }))
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/clickhouse/index.ts
+function tables(config = {}) {
+  return (adapter) => new ClickHouseTableGrounding(adapter, config);
+}
+function views(config = {}) {
+  return (adapter) => new ClickHouseViewGrounding(adapter, config);
+}
+function info(config = {}) {
+  return (adapter) => new ClickHouseInfoGrounding(adapter, config);
+}
+function indexes(config = {}) {
+  return (adapter) => new ClickHouseIndexesGrounding(adapter, config);
+}
+function rowCount(config = {}) {
+  return (adapter) => new ClickHouseRowCountGrounding(adapter, config);
+}
+function constraints(config = {}) {
+  return (adapter) => new ClickHouseConstraintGrounding(adapter, config);
+}
+var clickhouse_default = {
+  ClickHouse,
+  constraints,
+  indexes,
+  info,
+  rowCount,
+  tables,
+  views
+};
+export {
+  ClickHouse,
+  ClickHouseSqlPolicyAnalyzer,
+  constraints,
+  clickhouse_default as default,
+  indexes,
+  info,
+  rowCount,
+  tables,
+  views
+};
+//# sourceMappingURL=index.js.map