@deepagents/text2sql 0.13.1 → 0.15.1

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

@@ -0,0 +1,1321 @@
+// 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 }
+    }
+  };
+}
+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
+function createGroundingContext() {
+  return {
+    tables: [],
+    views: [],
+    relationships: [],
+    info: void 0
+  };
+}
+
+// packages/text2sql/src/lib/adapters/adapter.ts
+var Adapter = class {
+  /**
+   * 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);
+      await grounding.execute(ctx);
+    }
+    return this.#toSchemaFragments(ctx);
+  }
+  /**
+   * 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
+        })
+      );
+    }
+    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]));
+    for (const rel of ctx.relationships) {
+      const sourceTable = tableMap.get(rel.table);
+      const targetTable = tableMap.get(rel.referenced_table);
+      fragments.push(
+        this.#relationshipToFragment(rel, sourceTable, targetTable)
+      );
+    }
+    if (ctx.report) {
+      fragments.push({ name: "businessContext", data: ctx.report });
+    }
+    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 indexFragments = (t.indexes ?? []).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
+    ).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
+    });
+  }
+  /**
+   * 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/adapters/groundings/abstract.grounding.ts
+var AbstractGrounding = class {
+  /**
+   * Grounding identifier for debugging/logging.
+   */
+  name;
+  constructor(name) {
+    this.name = name;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/constraint.grounding.ts
+var ConstraintGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("constraint");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their constraints.
+   */
+  async execute(ctx) {
+    for (const table2 of ctx.tables) {
+      try {
+        table2.constraints = await this.getConstraints(table2.name);
+      } catch (error) {
+        console.warn("Error collecting constraints for", table2.name, error);
+      }
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/indexes.grounding.ts
+var IndexesGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("index");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with their indexes and marks indexed columns.
+   */
+  async execute(ctx) {
+    for (const table2 of ctx.tables) {
+      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/groundings/info.grounding.ts
+var InfoGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("dialectInfo");
+  }
+  /**
+   * Execute the grounding process.
+   * Writes database info to ctx.info.
+   */
+  async execute(ctx) {
+    ctx.info = await this.collectInfo();
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/report.grounding.ts
+import { groq } from "@ai-sdk/groq";
+import { tool } from "ai";
+import dedent from "dedent";
+import z from "zod";
+import "@deepagents/agent";
+import {
+  ContextEngine,
+  InMemoryContextStore,
+  agent,
+  fragment,
+  persona,
+  user
+} from "@deepagents/context";
+var ReportGrounding = class extends AbstractGrounding {
+  #adapter;
+  #model;
+  #cache;
+  #forceRefresh;
+  constructor(adapter, config = {}) {
+    super("business_context");
+    this.#adapter = adapter;
+    this.#model = config.model ?? groq("openai/gpt-oss-20b");
+    this.#cache = config.cache;
+    this.#forceRefresh = config.forceRefresh ?? false;
+  }
+  async execute(ctx) {
+    if (!this.#forceRefresh && this.#cache) {
+      const cached = await this.#cache.get();
+      if (cached) {
+        ctx.report = cached;
+        return;
+      }
+    }
+    const report2 = await this.#generateReport();
+    ctx.report = report2;
+    if (this.#cache) {
+      await this.#cache.set(report2);
+    }
+  }
+  async #generateReport() {
+    const context = new ContextEngine({
+      store: new InMemoryContextStore(),
+      chatId: `report-gen-${crypto.randomUUID()}`,
+      userId: "system"
+    });
+    context.set(
+      persona({
+        name: "db-report-agent",
+        role: "Database analyst",
+        objective: "Analyze the database and write a contextual report about what it represents"
+      }),
+      fragment(
+        "instructions",
+        dedent`
+          Write a business context that helps another agent answer questions accurately.
+
+          For EACH table, do queries ONE AT A TIME:
+          1. SELECT COUNT(*) to get row count
+          2. SELECT * LIMIT 3 to see sample data
+
+          Then write a report with:
+          - What business this database is for
+          - For each table: purpose, row count, and example of what the data looks like
+
+          Include concrete examples like "Track prices are $0.99",
+          "Customer names like 'Luís Gonçalves'", etc.
+
+          Keep it 400-600 words, conversational style.
+        `
+      ),
+      user(
+        "Please analyze the database and write a contextual report about what this database represents."
+      )
+    );
+    const adapter = this.#adapter;
+    const reportAgent = agent({
+      name: "db-report-agent",
+      model: this.#model,
+      context,
+      tools: {
+        query_database: tool({
+          description: "Execute a SELECT query to explore the database and gather insights.",
+          inputSchema: z.object({
+            sql: z.string().describe("The SELECT query to execute"),
+            purpose: z.string().describe(
+              "What insight you are trying to gather with this query"
+            )
+          }),
+          execute: ({ sql }) => {
+            return adapter.execute(sql);
+          }
+        })
+      }
+    });
+    const result = await reportAgent.generate({});
+    return result.text;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/row-count.grounding.ts
+var RowCountGrounding = class extends AbstractGrounding {
+  constructor(config = {}) {
+    super("rowCount");
+  }
+  /**
+   * Execute the grounding process.
+   * Annotates tables in ctx.tables with row counts and size hints.
+   */
+  async execute(ctx) {
+    for (const table2 of ctx.tables) {
+      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/groundings/table.grounding.ts
+var TableGrounding = class extends AbstractGrounding {
+  #filter;
+  #forward;
+  #backward;
+  constructor(config = {}) {
+    super("table");
+    this.#filter = config.filter;
+    this.#forward = config.forward;
+    this.#backward = config.backward;
+  }
+  /**
+   * 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((name) => this.getTable(name))
+      );
+      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();
+    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]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < forwardLimit) {
+        const rels = await this.findOutgoingRelations(name);
+        for (const rel of rels) {
+          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]) {
+        tables2[name] = await this.getTable(name);
+      }
+      if (depth < backwardLimit) {
+        const rels = await this.findIncomingRelations(name);
+        for (const rel of rels) {
+          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);
+    }
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/bigquery.ts
+function formatBigQueryError(sql, error) {
+  const errorMessage = error instanceof Error ? error.message : typeof error === "string" ? error : typeof error === "object" && error !== null ? error.message ?? JSON.stringify(error) : "Unknown error occurred";
+  return {
+    error: errorMessage,
+    error_type: "BIGQUERY_ERROR",
+    suggestion: "Validate the query (dry-run) and review table/dataset names, nested field paths, and parameter bindings.",
+    sql_attempted: sql
+  };
+}
+var BigQuery = class extends Adapter {
+  #options;
+  #datasetSet;
+  grounding;
+  defaultSchema;
+  systemSchemas = [];
+  constructor(options) {
+    super();
+    if (!options || typeof options.execute !== "function") {
+      throw new Error("BigQuery adapter requires an execute(sql) function.");
+    }
+    if (typeof options.validate !== "function") {
+      throw new Error(
+        "BigQuery adapter requires a validate(sql) function. Provide a BigQuery dry-run validator (recommended) so generated SQL can be validated before execution."
+      );
+    }
+    const datasets = (options.datasets ?? []).map((d) => d.trim()).filter(Boolean);
+    if (datasets.length === 0) {
+      throw new Error(
+        "BigQuery adapter requires a non-empty datasets list (e.g. datasets: ['analytics']). This scopes all introspection."
+      );
+    }
+    this.#options = { ...options, datasets };
+    this.#datasetSet = new Set(datasets);
+    this.grounding = options.grounding;
+    this.defaultSchema = datasets.length === 1 ? datasets[0] : void 0;
+  }
+  get datasets() {
+    return this.#options.datasets;
+  }
+  get projectId() {
+    return this.#options.projectId;
+  }
+  isDatasetAllowed(dataset) {
+    return this.#datasetSet.has(dataset);
+  }
+  /**
+   * Build a fully-qualified BigQuery INFORMATION_SCHEMA view reference.
+   * Uses standard BigQuery backtick quoting on the full path.
+   */
+  infoSchemaView(dataset, viewName) {
+    const projectPrefix = this.projectId ? `${this.projectId}.` : "";
+    return `\`${projectPrefix}${dataset}.INFORMATION_SCHEMA.${viewName}\``;
+  }
+  async execute(sql) {
+    return this.#options.execute(sql);
+  }
+  async validate(sql) {
+    try {
+      return await this.#options.validate(sql);
+    } catch (error) {
+      return JSON.stringify(formatBigQueryError(sql, error));
+    }
+  }
+  async runQuery(sql) {
+    const result = await this.#options.execute(sql);
+    if (Array.isArray(result)) {
+      return result;
+    }
+    if (result && typeof result === "object" && "rows" in result && Array.isArray(result.rows)) {
+      return result.rows;
+    }
+    throw new Error(
+      "BigQuery adapter execute() must return an array of rows or an object with a rows array when introspecting."
+    );
+  }
+  quoteIdentifier(name) {
+    return name.split(".").map((part) => `\`${part.replace(/`/g, "``")}\``).join(".");
+  }
+  escape(value) {
+    return value.replace(/`/g, "``");
+  }
+  buildSampleRowsQuery(tableName, columns, limit) {
+    const qualifiedTableName = this.#qualifyTableName(tableName);
+    const tableIdentifier = this.quoteIdentifier(qualifiedTableName);
+    const columnList = columns?.length ? columns.map((c) => c === "*" ? "*" : this.quoteIdentifier(c)).join(", ") : "*";
+    return `SELECT ${columnList} FROM ${tableIdentifier} LIMIT ${limit}`;
+  }
+  #qualifyTableName(tableName) {
+    if (!this.projectId) {
+      return tableName;
+    }
+    if (tableName.split(".").length >= 3) {
+      return tableName;
+    }
+    return `${this.projectId}.${tableName}`;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/constraint.bigquery.grounding.ts
+var BigQueryConstraintGrounding = class extends ConstraintGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getConstraints(tableName) {
+    const { schema: dataset, table: table2 } = this.#adapter.parseTableName(tableName);
+    const constraints2 = [];
+    const columnRows = await this.#adapter.runQuery(`
+      SELECT column_name, is_nullable, column_default
+      FROM ${this.#adapter.infoSchemaView(dataset, "COLUMNS")}
+      WHERE table_name = '${this.#adapter.escapeString(table2)}'
+      ORDER BY ordinal_position
+    `);
+    for (const row of columnRows) {
+      const col = row.column_name;
+      if (!col) continue;
+      if ((row.is_nullable ?? "").toUpperCase() === "NO") {
+        constraints2.push({
+          name: `${tableName}.${col}.NOT_NULL`,
+          type: "NOT_NULL",
+          columns: [col]
+        });
+      }
+      if (row.column_default != null && row.column_default !== "") {
+        constraints2.push({
+          name: `${tableName}.${col}.DEFAULT`,
+          type: "DEFAULT",
+          columns: [col],
+          defaultValue: row.column_default
+        });
+      }
+    }
+    const keyRows = await this.#adapter.runQuery(`
+      SELECT
+        tc.constraint_name,
+        tc.constraint_type,
+        kcu.column_name,
+        kcu.ordinal_position,
+        kcu.position_in_unique_constraint
+      FROM ${this.#adapter.infoSchemaView(dataset, "TABLE_CONSTRAINTS")} AS tc
+      JOIN ${this.#adapter.infoSchemaView(dataset, "KEY_COLUMN_USAGE")} AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.constraint_schema = kcu.constraint_schema
+      WHERE tc.table_name = '${this.#adapter.escapeString(table2)}'
+        AND tc.constraint_type IN ('PRIMARY KEY', 'FOREIGN KEY')
+      ORDER BY tc.constraint_name, kcu.ordinal_position
+    `);
+    const pkByName = /* @__PURE__ */ new Map();
+    const fkByName = /* @__PURE__ */ new Map();
+    for (const row of keyRows) {
+      if (!row.constraint_name || !row.column_name) continue;
+      const type = (row.constraint_type ?? "").toUpperCase();
+      if (type === "PRIMARY KEY") {
+        const cols = pkByName.get(row.constraint_name) ?? [];
+        cols.push(row.column_name);
+        pkByName.set(row.constraint_name, cols);
+        continue;
+      }
+      if (type === "FOREIGN KEY") {
+        const cols = fkByName.get(row.constraint_name) ?? [];
+        cols.push({
+          column: row.column_name,
+          ordinal: row.ordinal_position ?? 0,
+          pkOrdinal: row.position_in_unique_constraint
+        });
+        fkByName.set(row.constraint_name, cols);
+      }
+    }
+    for (const [name, cols] of pkByName.entries()) {
+      constraints2.push({
+        name,
+        type: "PRIMARY_KEY",
+        columns: cols
+      });
+    }
+    for (const [constraintName, cols] of fkByName.entries()) {
+      const fk = await this.#buildForeignKeyConstraint({
+        constraintDataset: dataset,
+        constraintName,
+        childTableName: `${dataset}.${table2}`,
+        childColumns: cols
+      });
+      if (fk) constraints2.push(fk);
+    }
+    return constraints2;
+  }
+  async #buildForeignKeyConstraint(args) {
+    const refRows = await this.#adapter.runQuery(`
+      SELECT DISTINCT table_schema, table_name
+      FROM ${this.#adapter.infoSchemaView(args.constraintDataset, "CONSTRAINT_COLUMN_USAGE")}
+      WHERE constraint_name = '${this.#adapter.escapeString(args.constraintName)}'
+    `);
+    const referenced = refRows.find((r) => r.table_schema && r.table_name);
+    if (!referenced?.table_schema || !referenced.table_name) {
+      return void 0;
+    }
+    const referencedDataset = referenced.table_schema;
+    const referencedTable = referenced.table_name;
+    if (!this.#adapter.isDatasetAllowed(referencedDataset)) {
+      return void 0;
+    }
+    const pkConstraintRows = await this.#adapter.runQuery(`
+      SELECT constraint_name
+      FROM ${this.#adapter.infoSchemaView(referencedDataset, "TABLE_CONSTRAINTS")}
+      WHERE constraint_type = 'PRIMARY KEY'
+        AND table_name = '${this.#adapter.escapeString(referencedTable)}'
+      LIMIT 1
+    `);
+    const pkConstraintName = pkConstraintRows[0]?.constraint_name;
+    if (!pkConstraintName) return void 0;
+    const pkColumns = await this.#adapter.runQuery(`
+      SELECT column_name, ordinal_position
+      FROM ${this.#adapter.infoSchemaView(referencedDataset, "KEY_COLUMN_USAGE")}
+      WHERE constraint_name = '${this.#adapter.escapeString(pkConstraintName)}'
+        AND table_name = '${this.#adapter.escapeString(referencedTable)}'
+      ORDER BY ordinal_position
+    `);
+    const pkByOrdinal = /* @__PURE__ */ new Map();
+    for (const row of pkColumns) {
+      if (!row.column_name || row.ordinal_position == null) continue;
+      pkByOrdinal.set(row.ordinal_position, row.column_name);
+    }
+    const orderedChild = [...args.childColumns].sort(
+      (a, b) => a.ordinal - b.ordinal
+    );
+    const columns = orderedChild.map((c) => c.column);
+    const referencedColumns = orderedChild.map((c) => {
+      const pkOrdinal = c.pkOrdinal ?? c.ordinal;
+      return pkByOrdinal.get(pkOrdinal) ?? "unknown";
+    });
+    return {
+      name: args.constraintName,
+      type: "FOREIGN_KEY",
+      columns,
+      referencedTable: `${referencedDataset}.${referencedTable}`,
+      referencedColumns
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/indexes.bigquery.grounding.ts
+var BigQueryIndexesGrounding = class extends IndexesGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getIndexes(tableName) {
+    const { schema: dataset, table: table2 } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT column_name, is_partitioning_column, clustering_ordinal_position
+      FROM ${this.#adapter.infoSchemaView(dataset, "COLUMNS")}
+      WHERE table_name = '${this.#adapter.escapeString(table2)}'
+        AND (is_partitioning_column = 'YES' OR clustering_ordinal_position IS NOT NULL)
+      ORDER BY clustering_ordinal_position
+    `);
+    const partitionColumns = [];
+    const clusteringColumns = [];
+    for (const row of rows) {
+      if (!row.column_name) continue;
+      if ((row.is_partitioning_column ?? "").toUpperCase() === "YES") {
+        partitionColumns.push(row.column_name);
+      }
+      if (row.clustering_ordinal_position != null) {
+        clusteringColumns.push({
+          name: row.column_name,
+          pos: row.clustering_ordinal_position
+        });
+      }
+    }
+    const indexes2 = [];
+    if (partitionColumns.length > 0) {
+      indexes2.push({
+        name: `${table2}_partition`,
+        columns: partitionColumns,
+        type: "PARTITION"
+      });
+    }
+    if (clusteringColumns.length > 0) {
+      clusteringColumns.sort((a, b) => a.pos - b.pos);
+      indexes2.push({
+        name: `${table2}_clustering`,
+        columns: clusteringColumns.map((c) => c.name),
+        type: "CLUSTERING"
+      });
+    }
+    return indexes2;
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/info.bigquery.grounding.ts
+var BigQueryInfoGrounding = class extends InfoGrounding {
+  #adapter;
+  constructor(adapter) {
+    super();
+    this.#adapter = adapter;
+  }
+  async collectInfo() {
+    return {
+      dialect: "bigquery",
+      database: this.#adapter.projectId,
+      details: {
+        identifierQuote: "`",
+        identifiers: {
+          qualifiedTable: "dataset.table",
+          nestedFieldPath: "col.path.to.field"
+        },
+        parameters: {
+          positional: "?",
+          named: "@name"
+        }
+      }
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/row-count.bigquery.grounding.ts
+var BigQueryRowCountGrounding = class extends RowCountGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async getRowCount(tableName) {
+    const { schema: dataset, table: table2 } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT total_rows
+      FROM ${this.#adapter.infoSchemaView(dataset, "TABLE_STORAGE")}
+      WHERE table_name = '${this.#adapter.escapeString(table2)}'
+      LIMIT 1
+    `);
+    const value = rows[0]?.total_rows;
+    return this.#adapter.toNumber(value);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/table.bigquery.grounding.ts
+var BigQueryTableGrounding = class extends TableGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async applyFilter() {
+    const names = await super.applyFilter();
+    return names.filter((name) => this.#isTableInScope(name));
+  }
+  async getAllTableNames() {
+    const names = [];
+    for (const dataset of this.#adapter.datasets) {
+      const rows = await this.#adapter.runQuery(`
+        SELECT table_name
+        FROM ${this.#adapter.infoSchemaView(dataset, "TABLES")}
+        WHERE table_type = 'BASE TABLE'
+        ORDER BY table_name
+      `);
+      for (const row of rows) {
+        if (!row.table_name) continue;
+        names.push(`${dataset}.${row.table_name}`);
+      }
+    }
+    return names;
+  }
+  async getTable(tableName) {
+    const { schema: dataset, table: table2 } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        f.field_path,
+        f.data_type,
+        c.ordinal_position
+      FROM ${this.#adapter.infoSchemaView(dataset, "COLUMN_FIELD_PATHS")} AS f
+      JOIN ${this.#adapter.infoSchemaView(dataset, "COLUMNS")} AS c
+        ON f.table_name = c.table_name
+        AND f.column_name = c.column_name
+      WHERE f.table_name = '${this.#adapter.escapeString(table2)}'
+      ORDER BY c.ordinal_position, f.field_path
+    `);
+    const seen = /* @__PURE__ */ new Set();
+    const columns = rows.map((r) => ({
+      name: r.field_path ?? "unknown",
+      type: r.data_type ?? "unknown",
+      ordinal: r.ordinal_position ?? 0
+    })).filter((c) => {
+      if (!c.name) return false;
+      if (seen.has(c.name)) return false;
+      seen.add(c.name);
+      return true;
+    }).map((c) => ({ name: c.name, type: c.type }));
+    return {
+      name: `${dataset}.${table2}`,
+      schema: dataset,
+      rawName: table2,
+      columns
+    };
+  }
+  async findOutgoingRelations(tableName) {
+    const { schema: dataset, table: table2 } = this.#adapter.parseTableName(tableName);
+    const rows = await this.#adapter.runQuery(`
+      SELECT
+        kcu.constraint_name,
+        kcu.column_name,
+        kcu.ordinal_position,
+        kcu.position_in_unique_constraint
+      FROM ${this.#adapter.infoSchemaView(dataset, "TABLE_CONSTRAINTS")} AS tc
+      JOIN ${this.#adapter.infoSchemaView(dataset, "KEY_COLUMN_USAGE")} AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.constraint_schema = kcu.constraint_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        AND tc.table_name = '${this.#adapter.escapeString(table2)}'
+      ORDER BY kcu.constraint_name, kcu.ordinal_position
+    `);
+    const byConstraint = /* @__PURE__ */ new Map();
+    for (const row of rows) {
+      if (!row.constraint_name || !row.column_name) continue;
+      const list = byConstraint.get(row.constraint_name) ?? [];
+      list.push({
+        column: row.column_name,
+        ordinal: row.ordinal_position ?? 0,
+        pkOrdinal: row.position_in_unique_constraint
+      });
+      byConstraint.set(row.constraint_name, list);
+    }
+    const rels = [];
+    for (const [constraintName, columns] of byConstraint.entries()) {
+      const rel = await this.#buildForeignKeyRelationship({
+        constraintDataset: dataset,
+        childDataset: dataset,
+        childTable: table2,
+        constraintName,
+        childColumns: columns
+      });
+      if (rel) rels.push(rel);
+    }
+    return rels;
+  }
+  async findIncomingRelations(tableName) {
+    const { schema: referencedDataset, table: referencedTable } = this.#adapter.parseTableName(tableName);
+    const rels = [];
+    for (const constraintDataset of this.#adapter.datasets) {
+      const rows = await this.#adapter.runQuery(`
+        SELECT DISTINCT constraint_name
+        FROM ${this.#adapter.infoSchemaView(constraintDataset, "CONSTRAINT_COLUMN_USAGE")}
+        WHERE table_schema = '${this.#adapter.escapeString(referencedDataset)}'
+          AND table_name = '${this.#adapter.escapeString(referencedTable)}'
+      `);
+      for (const row of rows) {
+        if (!row.constraint_name) continue;
+        const rel = await this.#buildForeignKeyRelationshipFromConstraintName(
+          constraintDataset,
+          row.constraint_name
+        );
+        if (rel && rel.referenced_table === `${referencedDataset}.${referencedTable}`) {
+          rels.push(rel);
+        }
+      }
+    }
+    return rels;
+  }
+  #isTableInScope(tableName) {
+    const { schema } = this.#adapter.parseTableName(tableName);
+    return this.#adapter.isDatasetAllowed(schema);
+  }
+  async #buildForeignKeyRelationshipFromConstraintName(constraintDataset, constraintName) {
+    const keyRows = await this.#adapter.runQuery(`
+      SELECT
+        kcu.constraint_name,
+        tc.table_name AS child_table_name,
+        kcu.column_name,
+        kcu.ordinal_position,
+        kcu.position_in_unique_constraint
+      FROM ${this.#adapter.infoSchemaView(constraintDataset, "TABLE_CONSTRAINTS")} AS tc
+      JOIN ${this.#adapter.infoSchemaView(constraintDataset, "KEY_COLUMN_USAGE")} AS kcu
+        ON tc.constraint_name = kcu.constraint_name
+        AND tc.constraint_schema = kcu.constraint_schema
+      WHERE tc.constraint_type = 'FOREIGN KEY'
+        AND tc.constraint_name = '${this.#adapter.escapeString(constraintName)}'
+      ORDER BY kcu.ordinal_position
+    `);
+    if (keyRows.length === 0) return void 0;
+    const childTable = keyRows[0]?.child_table_name;
+    if (!childTable) return void 0;
+    const childColumns = keyRows.filter((r) => r.column_name).map((r) => ({
+      column: r.column_name ?? "unknown",
+      ordinal: r.ordinal_position ?? 0,
+      pkOrdinal: r.position_in_unique_constraint
+    }));
+    return this.#buildForeignKeyRelationship({
+      constraintDataset,
+      childDataset: constraintDataset,
+      childTable,
+      constraintName,
+      childColumns
+    });
+  }
+  async #buildForeignKeyRelationship(args) {
+    const refTableRows = await this.#adapter.runQuery(`
+      SELECT DISTINCT table_schema, table_name
+      FROM ${this.#adapter.infoSchemaView(args.constraintDataset, "CONSTRAINT_COLUMN_USAGE")}
+      WHERE constraint_name = '${this.#adapter.escapeString(args.constraintName)}'
+    `);
+    const referenced = refTableRows.find((r) => r.table_schema && r.table_name);
+    if (!referenced?.table_schema || !referenced.table_name) {
+      return void 0;
+    }
+    const referencedDataset = referenced.table_schema;
+    const referencedTable = referenced.table_name;
+    if (!this.#adapter.isDatasetAllowed(referencedDataset)) {
+      return void 0;
+    }
+    const pkConstraintRows = await this.#adapter.runQuery(`
+      SELECT constraint_name
+      FROM ${this.#adapter.infoSchemaView(referencedDataset, "TABLE_CONSTRAINTS")}
+      WHERE constraint_type = 'PRIMARY KEY'
+        AND table_name = '${this.#adapter.escapeString(referencedTable)}'
+      LIMIT 1
+    `);
+    const pkConstraintName = pkConstraintRows[0]?.constraint_name;
+    if (!pkConstraintName) {
+      return void 0;
+    }
+    const pkColumnRows = await this.#adapter.runQuery(`
+      SELECT column_name, ordinal_position
+      FROM ${this.#adapter.infoSchemaView(referencedDataset, "KEY_COLUMN_USAGE")}
+      WHERE constraint_name = '${this.#adapter.escapeString(pkConstraintName)}'
+        AND table_name = '${this.#adapter.escapeString(referencedTable)}'
+      ORDER BY ordinal_position
+    `);
+    const pkByOrdinal = /* @__PURE__ */ new Map();
+    for (const row of pkColumnRows) {
+      if (!row.column_name || row.ordinal_position == null) continue;
+      pkByOrdinal.set(row.ordinal_position, row.column_name);
+    }
+    const orderedChild = [...args.childColumns].sort(
+      (a, b) => a.ordinal - b.ordinal
+    );
+    const from = orderedChild.map((c) => c.column);
+    const to = orderedChild.map((c) => {
+      const pkOrdinal = c.pkOrdinal ?? c.ordinal;
+      return pkByOrdinal.get(pkOrdinal) ?? "unknown";
+    });
+    return {
+      table: `${args.childDataset}.${args.childTable}`,
+      from,
+      referenced_table: `${referencedDataset}.${referencedTable}`,
+      to
+    };
+  }
+};
+
+// packages/text2sql/src/lib/adapters/groundings/view.grounding.ts
+var ViewGrounding = class extends AbstractGrounding {
+  #filter;
+  constructor(config = {}) {
+    super("view");
+    this.#filter = config.filter;
+  }
+  /**
+   * 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((name) => this.getView(name))
+    );
+    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/bigquery/view.bigquery.grounding.ts
+var BigQueryViewGrounding = class extends ViewGrounding {
+  #adapter;
+  constructor(adapter, config = {}) {
+    super(config);
+    this.#adapter = adapter;
+  }
+  async applyFilter() {
+    const names = await super.applyFilter();
+    return names.filter((name) => this.#isViewInScope(name));
+  }
+  async getAllViewNames() {
+    const names = [];
+    for (const dataset of this.#adapter.datasets) {
+      const rows = await this.#adapter.runQuery(`
+        SELECT table_name
+        FROM ${this.#adapter.infoSchemaView(dataset, "TABLES")}
+        WHERE table_type IN ('VIEW', 'MATERIALIZED VIEW')
+        ORDER BY table_name
+      `);
+      for (const row of rows) {
+        if (!row.table_name) continue;
+        names.push(`${dataset}.${row.table_name}`);
+      }
+    }
+    return names;
+  }
+  async getView(viewName) {
+    const { schema: dataset, table: table2 } = this.#adapter.parseTableName(viewName);
+    const defRows = await this.#adapter.runQuery(`
+      SELECT ddl
+      FROM ${this.#adapter.infoSchemaView(dataset, "TABLES")}
+      WHERE table_name = '${this.#adapter.escapeString(table2)}'
+        AND table_type IN ('VIEW', 'MATERIALIZED VIEW')
+      LIMIT 1
+    `);
+    const columns = await this.#adapter.runQuery(`
+      SELECT column_name, data_type
+      FROM ${this.#adapter.infoSchemaView(dataset, "COLUMNS")}
+      WHERE table_name = '${this.#adapter.escapeString(table2)}'
+      ORDER BY ordinal_position
+    `);
+    return {
+      name: `${dataset}.${table2}`,
+      schema: dataset,
+      rawName: table2,
+      definition: defRows[0]?.ddl ?? void 0,
+      columns: columns.map((c) => ({
+        name: c.column_name ?? "unknown",
+        type: c.data_type ?? "unknown"
+      }))
+    };
+  }
+  #isViewInScope(viewName) {
+    const { schema } = this.#adapter.parseTableName(viewName);
+    return this.#adapter.isDatasetAllowed(schema);
+  }
+};
+
+// packages/text2sql/src/lib/adapters/bigquery/index.ts
+function tables(config = {}) {
+  return (adapter) => new BigQueryTableGrounding(adapter, config);
+}
+function info(config = {}) {
+  return (adapter) => new BigQueryInfoGrounding(adapter);
+}
+function views(config = {}) {
+  return (adapter) => new BigQueryViewGrounding(adapter, config);
+}
+function indexes(config = {}) {
+  return (adapter) => new BigQueryIndexesGrounding(adapter, config);
+}
+function rowCount(config = {}) {
+  return (adapter) => new BigQueryRowCountGrounding(adapter, config);
+}
+function constraints(config = {}) {
+  return (adapter) => new BigQueryConstraintGrounding(adapter, config);
+}
+function report(config = {}) {
+  return (adapter) => new ReportGrounding(adapter, config);
+}
+var bigquery_default = {
+  tables,
+  info,
+  views,
+  indexes,
+  rowCount,
+  constraints,
+  report,
+  BigQuery
+};
+export {
+  BigQuery,
+  constraints,
+  bigquery_default as default,
+  indexes,
+  info,
+  report,
+  rowCount,
+  tables,
+  views
+};
+//# sourceMappingURL=index.js.map