From 1fccf50f547ecdf2091ea038c536c1f0d7171456 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 19:52:47 +0530 Subject: [PATCH 1/7] fix(dbt-cost-estimate): EXPLAIN deadline, trailing comments, section heading in a literal, zero bytes, leaf with inner plan; say what altimate-dbt is Co-Authored-By: Claude Sonnet 5.5 --- .opencode/skills/dbt-analyze/SKILL.md | 2 + .opencode/skills/dbt-develop/SKILL.md | 2 + .opencode/skills/dbt-docs/SKILL.md | 2 + .opencode/skills/dbt-schema-verify/SKILL.md | 2 + .opencode/skills/dbt-test/SKILL.md | 2 + .opencode/skills/dbt-troubleshoot/SKILL.md | 2 + .opencode/skills/dbt-unit-tests/SKILL.md | 2 + .opencode/skills/sql-review/SKILL.md | 2 + .../guides/using-with-claude-code.md | 4 + .../src/altimate/tools/dbt-cost-estimate.ts | 107 ++++++++++++++++-- .../test/altimate/dbt-cost-estimate.test.ts | 106 ++++++++++++++++- 11 files changed, 219 insertions(+), 14 deletions(-) diff --git a/.opencode/skills/dbt-analyze/SKILL.md b/.opencode/skills/dbt-analyze/SKILL.md index d300284e86..3696fe0d27 100644 --- a/.opencode/skills/dbt-analyze/SKILL.md +++ b/.opencode/skills/dbt-analyze/SKILL.md @@ -5,6 +5,8 @@ description: Analyze downstream impact of dbt model changes using column-level l # dbt Impact Analysis +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** any (read-only analysis) **Tools used:** bash (runs `altimate-dbt` commands), read, glob, dbt_manifest, lineage_check, dbt_lineage, sql_analyze, altimate_core_extract_metadata diff --git a/.opencode/skills/dbt-develop/SKILL.md b/.opencode/skills/dbt-develop/SKILL.md index 32b4254420..5e79b711eb 100644 --- a/.opencode/skills/dbt-develop/SKILL.md +++ b/.opencode/skills/dbt-develop/SKILL.md @@ -29,6 +29,8 @@ description: | # dbt Model Development +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** builder or migrator (requires file write access) **Tools used:** bash (runs `altimate-dbt` commands), read, glob, write, edit, schema_search, dbt_profiles, sql_analyze, altimate_core_validate, altimate_core_column_lineage diff --git a/.opencode/skills/dbt-docs/SKILL.md b/.opencode/skills/dbt-docs/SKILL.md index e34ee516a2..60d0a5c8fa 100644 --- a/.opencode/skills/dbt-docs/SKILL.md +++ b/.opencode/skills/dbt-docs/SKILL.md @@ -5,6 +5,8 @@ description: Document dbt models and columns in schema.yml with business context # dbt Documentation +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** builder or migrator (requires file write access) **Tools used:** bash (runs `altimate-dbt` commands), read, glob, write, edit diff --git a/.opencode/skills/dbt-schema-verify/SKILL.md b/.opencode/skills/dbt-schema-verify/SKILL.md index 80b7dab31d..f40ce54889 100644 --- a/.opencode/skills/dbt-schema-verify/SKILL.md +++ b/.opencode/skills/dbt-schema-verify/SKILL.md @@ -23,6 +23,8 @@ description: | # dbt schema-verify +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## When to invoke this skill — every time Run `altimate-dbt schema-verify --model ` before declaring any of the diff --git a/.opencode/skills/dbt-test/SKILL.md b/.opencode/skills/dbt-test/SKILL.md index 3c3cdf82db..54f8e7a14e 100644 --- a/.opencode/skills/dbt-test/SKILL.md +++ b/.opencode/skills/dbt-test/SKILL.md @@ -5,6 +5,8 @@ description: Add schema tests, unit tests, and data quality checks to dbt models # dbt Testing +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** builder or migrator (requires file write access) **Tools used:** bash (runs `altimate-dbt` commands), read, glob, write, edit, altimate_core_testgen, altimate_core_validate diff --git a/.opencode/skills/dbt-troubleshoot/SKILL.md b/.opencode/skills/dbt-troubleshoot/SKILL.md index 914a489104..4037213bcb 100644 --- a/.opencode/skills/dbt-troubleshoot/SKILL.md +++ b/.opencode/skills/dbt-troubleshoot/SKILL.md @@ -5,6 +5,8 @@ description: Debug dbt errors — compilation failures, runtime database errors, # dbt Troubleshooting +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** any (read-only diagnosis), builder (if applying fixes) **Tools used:** bash (runs `altimate-dbt` commands), read, glob, edit, altimate_core_semantics, altimate_core_column_lineage, altimate_core_correct, altimate_core_fix, sql_fix diff --git a/.opencode/skills/dbt-unit-tests/SKILL.md b/.opencode/skills/dbt-unit-tests/SKILL.md index 619ae60f3f..d2ac449fe6 100644 --- a/.opencode/skills/dbt-unit-tests/SKILL.md +++ b/.opencode/skills/dbt-unit-tests/SKILL.md @@ -5,6 +5,8 @@ description: Generate dbt unit tests automatically for any model. Analyzes SQL l # dbt Unit Test Generation +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** builder or migrator (requires file write access) **Tools used:** dbt_unit_test_gen, dbt_manifest, dbt_lineage, altimate_core_validate, altimate_core_testgen, bash (runs `altimate-dbt` commands), read, glob, write, edit diff --git a/.opencode/skills/sql-review/SKILL.md b/.opencode/skills/sql-review/SKILL.md index 5f3babbf5f..f1840d651a 100644 --- a/.opencode/skills/sql-review/SKILL.md +++ b/.opencode/skills/sql-review/SKILL.md @@ -5,6 +5,8 @@ description: Pre-merge SQL quality gate — lint 26 anti-patterns, grade readabi # SQL Review +The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. + ## Requirements **Agent:** any (read-only analysis) **Tools used:** altimate_core_check, altimate_core_grade, sql_analyze, read, glob, bash (for git operations) diff --git a/docs/docs/data-engineering/guides/using-with-claude-code.md b/docs/docs/data-engineering/guides/using-with-claude-code.md index 18a5f4d111..9d1b5f6533 100644 --- a/docs/docs/data-engineering/guides/using-with-claude-code.md +++ b/docs/docs/data-engineering/guides/using-with-claude-code.md @@ -24,6 +24,10 @@ This gives Claude Code access to: - dbt manifest parsing and model scaffolding - Cross-dialect SQL translation +### What `altimate-dbt` is + +When altimate works on a dbt project, it often runs `altimate-dbt`. It is a small command-line tool for dbt tasks: it finds your dbt project, Python environment and adapter, then compiles models, runs and tests them, and inspects columns and schemas. It is installed together with altimate-code, so there is nothing separate to set up, and altimate runs it for you as part of a task. You can also run it yourself in a terminal. See [dbt Tools](../tools/dbt-tools.md#altimate-dbt-cli) for its commands. + ## Example workflows ### Code review with cost analysis diff --git a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts index b9b3b21b68..640866c336 100644 --- a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts +++ b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts @@ -65,6 +65,12 @@ export function formatBytes(bytes: number): string { return `${n.toFixed(1)} ${UNITS[i]}` } +/** + * A plan with no size for a leaf: `relation` names it when the plan does, and `unread` marks a leaf that printed no + * size this parser could read (as opposed to Spark's default size for a table without statistics). + */ +export type NoStats = { noStats: true; relation?: string; unread?: true } + /** A scan estimate from the warehouse's query planner: what EXPLAIN says the query reads, without running it. */ export type PlanEstimate = { bytes: number; partitionsAssigned?: number; partitionsTotal?: number } @@ -108,6 +114,13 @@ const SPARK_NO_SIZE = 2 ** 62 /** The headers Spark writes between the sections of an EXPLAIN. */ const SPARK_SECTION = /^== (Parsed Logical Plan|Analyzed Logical Plan|Optimized Logical Plan|Physical Plan) ==\s*$/ +/** Whether a node's text has more opening brackets than closing ones: its line continues on the next. */ +function opensBracket(text: string): boolean { + let open = 0 + for (const c of text) open += c === "(" || c === "[" ? 1 : c === ")" || c === "]" ? -1 : 0 + return open > 0 +} + /** A `sizeInBytes=` figure read back into bytes: "12.3 MiB", "16.0 B", or past a long "1.23E+21 B". */ function sparkBytes(figure: string): number | undefined { const match = /^(\d+(?:\.\d+)?(?:E[+-]?\d+)?)\s*([A-Za-z]+)$/i.exec(figure.trim()) @@ -125,15 +138,16 @@ function sparkBytes(figure: string): number | undefined { * size or Spark's default for a relation without statistics (with the relation's name when the leaf gives one); * undefined when there is no plan to read. */ -export function parseDatabricksExplainCost(plan: unknown): PlanEstimate | { noStats: true; relation?: string } | undefined { +export function parseDatabricksExplainCost(plan: unknown): PlanEstimate | NoStats | undefined { if (typeof plan !== "string") return undefined const lines = plan.replace(/\r\n?/g, "\n").split("\n") const start = lines.findIndex((line) => /^\s*==\s*Optimized Logical Plan\s*==\s*$/i.test(line)) if (start < 0) return undefined const nodes: { depth: number; text: string }[] = [] for (const line of lines.slice(start + 1)) { - // Only Spark's own section headers end the plan: a line of a multi-line node could look like one. - if (SPARK_SECTION.test(line)) break + // Only Spark's own section headers end the plan: a line of a multi-line node could look like one. A header + // while the node above still has an open bracket is the rest of that node (a literal holding a line break). + if (SPARK_SECTION.test(line) && !(nodes.length > 0 && opensBracket(nodes[nodes.length - 1].text))) break if (!line.trim()) continue // Each level of the tree is three characters: ": " or " " for an ancestor, ":- " or "+- " for the node itself. const prefix = /^(?:: | )*(?:[:+]- )?/.exec(line)![0] @@ -145,10 +159,18 @@ export function parseDatabricksExplainCost(plan: unknown): PlanEstimate | { noSt nodes.push({ depth: prefix.length / 3, text: line.slice(prefix.length) }) } if (nodes.length === 0) return undefined + // A node has a child when a later node sits one level below it before the tree comes back up to its level. An inner + // plan (a subquery) is printed two levels below, so a node holding one and no child is still a leaf. + const hasChild = nodes.map(() => false) + const open: number[] = [] + nodes.forEach((node, i) => { + while (open.length > 0 && nodes[open[open.length - 1]].depth >= node.depth) open.pop() + if (open.length > 0 && nodes[open[open.length - 1]].depth === node.depth - 1) hasChild[open[open.length - 1]] = true + open.push(i) + }) let bytes = 0 for (let i = 0; i < nodes.length; i++) { - // A leaf is a node the next line does not go below. - if (i + 1 < nodes.length && nodes[i + 1].depth > nodes[i].depth) continue + if (hasChild[i]) continue // Only the suffix Spark appends to the node: a column can be named anything, "Statistics(sizeInBytes=…)" too. const figure = /, Statistics\(sizeInBytes=([^,()]+)(?:, [^()]*)?\)\s*$/.exec(nodes[i].text)?.[1] const size = figure === undefined ? undefined : sparkBytes(figure) @@ -156,7 +178,8 @@ export function parseDatabricksExplainCost(plan: unknown): PlanEstimate | { noSt // "Relation main.sales.orders[…] parquet": Spark prints the name unquoted, so only a plain one (letters, digits, // underscores, dots) right before the column list is surely the whole name; any other gives none. const relation = /^Relation ([A-Za-z_][A-Za-z0-9_]*(?:\.[A-Za-z_][A-Za-z0-9_]*)*)\[/.exec(nodes[i].text)?.[1] - return relation ? { noStats: true, relation } : { noStats: true } + const unread = size === undefined ? { unread: true as const } : {} + return { noStats: true, ...(relation && { relation }), ...unread } } bytes += size } @@ -190,7 +213,7 @@ export function readsFiles(sql: string): boolean { * The warehouses with no dry run whose planner still says what a query reads, the EXPLAIN that asks it, and the * reader of its one row. */ -const PLANNERS: Record PlanEstimate | { noStats: true; relation?: string } | undefined }> = { +const PLANNERS: Record PlanEstimate | NoStats | undefined }> = { snowflake: { owner: "Snowflake's", explain: "EXPLAIN USING JSON", read: parseSnowflakeExplain }, databricks: { owner: "Databricks'", explain: "EXPLAIN COST", read: parseDatabricksExplainCost }, } @@ -208,6 +231,37 @@ export function explainJinja(explain: string, sql: string): string { return `{%- if execute -%}{%- set altimate_plan = run_query(${literal}) -%}{{ tojson(altimate_plan.columns[0].values() | list) }}{%- else -%}[]{%- endif -%}` } +/** + * The SQL up to its first semicolon outside quotes and comments. Past one `mayBeScript` allows only whitespace, + * semicolons and comments, which the driver would still split off and send as a statement of their own + * (`select 1; /* a\nb *\/`, `select 1;; -- c`): none of it is sent. Read for SQL `mayBeScript` accepted, so the + * quotes and comments it models are the only ones there are. + */ +export function firstStatement(sql: string, type: string): string { + const databricks = type === "databricks" + let i = 0 + while (i < sql.length) { + const c = sql[i] + const two = sql.slice(i, i + 2) + if (two === "--") { + const end = sql.indexOf("\n", i) + if (end < 0) break + i = end + 1 + } else if (two === "/*") { + const end = sql.indexOf("*/", i + 2) + if (end < 0) break + i = end + 2 + } else if (c === "'" || c === '"' || (databricks && c === "`")) { + let j = i + 1 + while (j < sql.length && sql[j] !== c) j += c !== "`" && sql[j] === "\\" ? 2 : 1 + i = j + 1 + } else if (c === ";") { + return sql.slice(0, i) + } else i++ + } + return sql +} + /** * Whether the SQL may be more than one statement, as the warehouse's driver splits it: dbt-snowflake runs each * statement it splits off, so a second one after the EXPLAIN would run for real. One pass, left to right, that @@ -280,6 +334,12 @@ export function scanSql(input: string, type: string): { script: boolean; code: s return { script: /\bexecute\s+immediate\b/i.test(code), code } } +/** Test seams. */ +export const dbtCostEstimateInternals = { + /** How long a call waits for a planner's EXPLAIN before it gives up; the plugin's own wait is 120 s. */ + explainTimeoutMs: 90_000, +} + /** Starts `start` and waits for it, but gives up as soon as the call is cancelled; a cancelled call starts nothing. */ export function untilAbort(start: () => Promise, signal: AbortSignal): Promise { if (signal.aborted) return Promise.reject(signal.reason) @@ -325,18 +385,38 @@ async function explainEstimate( ) } let row: unknown + // The EXPLAIN is bounded like the dbt adapter's start: a call that outlasts the deadline stops waiting for it (the + // adapter takes no signal, so the statement itself runs on) and a cancelled call stops at once. + const deadline = new AbortController() + const timer = setTimeout( + () => deadline.abort(new Error(`${planner.explain} did not answer within ${dbtCostEstimateInternals.explainTimeoutMs / 1000} s`)), + dbtCostEstimateInternals.explainTimeoutMs, + ) try { - const rendered = await untilAbort(() => adapter.unsafeCompileQuery(explainJinja(planner.explain, sql), undefined), signal) + const rendered = await untilAbort( + () => adapter.unsafeCompileQuery(explainJinja(planner.explain, firstStatement(sql, type)), undefined), + AbortSignal.any([signal, deadline.signal]), + ) const rows = typeof rendered === "string" ? JSON.parse(rendered.trim()) : undefined if (!Array.isArray(rows) || rows.length === 0) throw new Error(`${planner.explain} returned no plan`) row = rows[0] } catch (e) { if (signal.aborted) throw e return failure("explain failed", `${planner.owner} ${planner.explain} failed: ${e instanceof Error ? e.message : String(e)}`, extra) + } finally { + clearTimeout(timer) } const parsed = planner.read(row) if (parsed && "noStats" in parsed) { const table = parsed.relation ?? "" + // A leaf that printed no readable size (rather than Spark's default) is not known to lack statistics: no advice. + if (parsed.unread) { + return failure( + "no estimate", + `${planner.owner} ${planner.explain} printed no size this tool can read for ${parsed.relation ?? "a table this query reads"}, so it is not estimated.`, + extra, + ) + } return failure( "no estimate", `${planner.owner} planner has no size for ${parsed.relation ?? "a table this query reads"} (it shows Spark's default for a table without statistics). ANALYZE TABLE ${table} COMPUTE STATISTICS NOSCAN records its size from file metadata without reading the data; without NOSCAN, ANALYZE scans the whole table.`, @@ -351,8 +431,11 @@ async function explainEstimate( parsed.partitionsAssigned !== undefined && parsed.partitionsTotal !== undefined ? `${parsed.partitionsAssigned} of ${parsed.partitionsTotal} partitions after pruning; ` : "" - const accuracy = - type === "snowflake" + // Snowflake may give 0 for a source it cannot size when it compiles (an external table, a stage): not a cap. + const unsized = type === "snowflake" && parsed.bytes === 0 + const accuracy = unsized + ? "Snowflake also reports 0 for a source it cannot size at compile time, such as an external table or a stage, so this is not a cap" + : type === "snowflake" ? `${partitions}an upper bound: runtime pruning can scan less, and a cached result none` : "table sizes before column pruning and file skipping, which usually read less; not a bound either way" return { @@ -363,7 +446,7 @@ async function explainEstimate( adapter: type, source: "explain", // Snowflake documents bytesAssigned as an upper bound; Spark's sizes are the planner's guess, either way. - bound: type === "snowflake" ? "upper" : "estimate", + bound: unsized ? "unknown" : type === "snowflake" ? "upper" : "estimate", bytes: parsed.bytes, display: shown, ...(parsed.partitionsAssigned !== undefined && { partitionsAssigned: parsed.partitionsAssigned }), @@ -376,7 +459,7 @@ async function explainEstimate( export const DbtCostEstimateTool = Tool.define("dbt_cost_estimate", { description: - "Estimate the bytes a dbt model or a SQL query would scan, without running it. BigQuery answers from a dry run (`maxBytes` bounds it, or `lowerBound` marks a floor); Snowflake (`EXPLAIN USING JSON`, bytes left after pruning) and Databricks (`EXPLAIN COST`, the sizes of the tables it reads) answer from the planner (`source: \"explain\"`; `bound` is \"upper\" on Snowflake, \"estimate\" on Databricks), and none when Databricks has no table statistics. EXPLAIN compiles the query on the warehouse and scans no data: on Snowflake it needs no running warehouse (cloud-services time only); on Databricks it runs on the SQL warehouse or cluster the profile connects to, and starts it (billed while up) if it is stopped. A query that may be more than one statement is never EXPLAINed, nor on Databricks one that reads files directly (read_files, cloud_files, json.`path`), whose planning reads the files to infer a schema. Any other warehouse answers `supported: false` and nothing is compiled. Starts the dbt adapter (which runs `dbt deps`), so it needs write permission (`--allow-write` on `tool run` or the MCP server). The dry run never executes the final query, but compiling either input can render Jinja, and macros such as `run_query` can run real queries that are billed. Pass `model` (a model name, compiled as dbt would) or `sql` (may use Jinja).", + "Estimate the bytes a dbt model or a SQL query would scan, without running it. BigQuery answers from a dry run (`maxBytes` bounds it, or `lowerBound` marks a floor); Snowflake (`EXPLAIN USING JSON`, bytes left after pruning) and Databricks (`EXPLAIN COST`, the sizes of the tables it reads) answer from the planner (`source: \"explain\"`; `bound` is \"upper\" on Snowflake (\"unknown\" when it reports 0, which it also does for a source it cannot size), \"estimate\" on Databricks), and none when Databricks has no table statistics. EXPLAIN compiles the query on the warehouse and scans no data: on Snowflake it needs no running warehouse (cloud-services time only); on Databricks it runs on the SQL warehouse or cluster the profile connects to, and starts it (billed while up) if it is stopped. A query that may be more than one statement is never EXPLAINed, nor on Databricks one that reads files directly (read_files, cloud_files, json.`path`), whose planning reads the files to infer a schema. Any other warehouse answers `supported: false` and nothing is compiled. Starts the dbt adapter (which runs `dbt deps`), so it needs write permission (`--allow-write` on `tool run` or the MCP server). The dry run never executes the final query, but compiling either input can render Jinja, and macros such as `run_query` can run real queries that are billed. Pass `model` (a model name, compiled as dbt would) or `sql` (may use Jinja).", parameters: z.object({ model: z.string().optional().describe("Model name to compile and estimate"), sql: z.string().optional().describe("SQL (may use Jinja) to compile and estimate"), diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index a2b54ca496..e0165715bd 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -11,7 +11,9 @@ import { SessionID, MessageID } from "@/session/schema" import { dbtAdapterInternals, resetDbtAdapter } from "@/altimate/native/connections/register" import { DbtCostEstimateTool, + dbtCostEstimateInternals, explainJinja, + firstStatement, mayBeScript, parseBytesProcessed, readsFiles, @@ -481,7 +483,7 @@ describe("parseDatabricksExplainCost", () => { }) test("a leaf with no statistics at all is no estimate", () => { - expect(parseDatabricksExplainCost("== Optimized Logical Plan ==\nProject [a#0], Statistics(sizeInBytes=1.0 KiB)\n+- Relation main.t[a#0] parquet")).toEqual({ noStats: true, relation: "main.t" }) + expect(parseDatabricksExplainCost("== Optimized Logical Plan ==\nProject [a#0], Statistics(sizeInBytes=1.0 KiB)\n+- Relation main.t[a#0] parquet")).toEqual({ noStats: true, relation: "main.t", unread: true }) }) test.each([ @@ -680,7 +682,7 @@ describe("parseDatabricksExplainCost reads only the statistics Spark appends", ( }) test("nor stands in for missing statistics, or for Spark's default size", () => { - expect(parseDatabricksExplainCost("== Optimized Logical Plan ==\nRelation main.t[Statistics(sizeInBytes=0.0 B)#0] parquet")).toEqual({ noStats: true, relation: "main.t" }) + expect(parseDatabricksExplainCost("== Optimized Logical Plan ==\nRelation main.t[Statistics(sizeInBytes=0.0 B)#0] parquet")).toEqual({ noStats: true, relation: "main.t", unread: true }) expect(parseDatabricksExplainCost("== Optimized Logical Plan ==\nRelation [Statistics(sizeInBytes=0 B)#0] parquet, Statistics(sizeInBytes=8.0 EiB)")).toEqual({ noStats: true }) }) }) @@ -995,3 +997,103 @@ describe("review follow-ups, round twelve", () => { } }) }) + +describe("follow-ups to the planner estimate", () => { + const rendered = (row: unknown) => async () => JSON.stringify([row]) + const originalTimeout = dbtCostEstimateInternals.explainTimeoutMs + afterEach(() => { + dbtCostEstimateInternals.explainTimeoutMs = originalTimeout + }) + + test("an EXPLAIN that outlasts its deadline is no estimate, and the call stops waiting", async () => { + dbtCostEstimateInternals.explainTimeoutMs = 50 + useAdapter(calls, { type: "databricks", explain: () => new Promise(() => {}) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.title).toBe("dbt_cost_estimate: explain failed") + expect(result.output).toContain("did not answer within 0.05 s") + expect(result.metadata.bytes).toBeUndefined() + }) + + test("an EXPLAIN that answers within its deadline is read as before", async () => { + dbtCostEstimateInternals.explainTimeoutMs = 5_000 + useAdapter(calls, { type: "snowflake", explain: rendered(SNOWFLAKE_PLAN) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.metadata.bytes).toBe(2_147_483_648) + }) + + test.each([ + ["a multi-line block comment", "select 1; /* a\nb */", "select 1"], + ["a second semicolon and a comment", "select 1;; -- c", "select 1"], + ["a comment on the next line", "select 1;\n-- done\n", "select 1"], + ])("Snowflake sends %s after the final semicolon to nobody", async (_, compiled, sent) => { + expect(mayBeScript(compiled, "snowflake")).toBe(false) + useAdapter(calls, { type: "snowflake", compile: async () => compiled, explain: rendered(SNOWFLAKE_PLAN) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(calls.queries).toEqual([[explainJinja("EXPLAIN USING JSON", sent), undefined]]) + expect(result.metadata.success).toBe(true) + }) + + test.each([ + ["select 'a;b' from t; -- c", "snowflake", "select 'a;b' from t"], + ["select \"a;b\" /* ; */ from t", "snowflake", 'select "a;b" /* ; */ from t'], + ["select `a;b` from t; /* x */", "databricks", "select `a;b` from t"], + ["select 1 -- not; a split", "snowflake", "select 1 -- not; a split"], + ["select 1", "snowflake", "select 1"], + ])("firstStatement(%p, %s) keeps what the driver sends as the statement", (sql, type, expected) => { + expect(firstStatement(sql, type)).toBe(expected) + }) + + test("a section heading inside a multi-line literal does not end the plan", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Project [concat(w#1, ", + "== Physical Plan ==", + ") AS z#2], Statistics(sizeInBytes=1.0 KiB)", + "+- Relation spark_catalog.default.b[w#1] parquet, Statistics(sizeInBytes=2.0 GiB)", + "", + "== Physical Plan ==", + "*(1) Project", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 2 * 1024 ** 3 }) + }) + + test("a section heading after a finished node still ends the plan", () => { + const plan = "== Optimized Logical Plan ==\nRelation main.t[a#0] parquet, Statistics(sizeInBytes=4.0 KiB)\n== Physical Plan ==\nRelation main.u[a#0] parquet, Statistics(sizeInBytes=9.0 GiB)" + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 4096 }) + }) + + test("a leaf that holds an inner plan keeps its own size", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Relation main.s.t[a#0] parquet, Statistics(sizeInBytes=2.0 GiB)", + ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) + }) + + test("a node with a child and an inner plan is still not a leaf", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Filter (a#0 IN (list#5 [])), Statistics(sizeInBytes=1.0 GiB)", + ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", + "+- Relation main.s.t[a#0] parquet, Statistics(sizeInBytes=2.0 GiB)", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) + }) + + test("Snowflake's 0 bytes is not called an upper bound: it also reports 0 for a source it cannot size", async () => { + useAdapter(calls, { type: "snowflake", explain: rendered('{"GlobalStats":{"partitionsTotal":0,"partitionsAssigned":0,"bytesAssigned":0}}') }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ sql: "select $1 from @stage" }, ctx) + expect(result.metadata).toMatchObject({ success: true, bound: "unknown", bytes: 0 }) + expect(result.output).toContain("not a cap") + expect(result.output).not.toContain("an upper bound") + }) + + test("a leaf with no readable size gets no ANALYZE advice: it is not known to lack statistics", async () => { + useAdapter(calls, { type: "databricks", explain: rendered("== Optimized Logical Plan ==\nRelation main.t[a#0] parquet") }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.metadata.success).toBe(false) + expect(result.output).toContain("printed no size this tool can read for main.t") + expect(result.output).not.toContain("ANALYZE") + }) +}) From 7433d66444f3f2226f6ff75e51991b98eac08f74 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 19:53:39 +0530 Subject: [PATCH 2/7] test(dbt-cost-estimate): place the follow-up tests ahead of the script tests --- .../test/altimate/dbt-cost-estimate.test.ts | 200 +++++++++--------- 1 file changed, 100 insertions(+), 100 deletions(-) diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index e0165715bd..e74398d5c7 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -619,6 +619,106 @@ describe("dbt_cost_estimate on a warehouse with a planner", () => { }) }) +describe("follow-ups to the planner estimate", () => { + const rendered = (row: unknown) => async () => JSON.stringify([row]) + const originalTimeout = dbtCostEstimateInternals.explainTimeoutMs + afterEach(() => { + dbtCostEstimateInternals.explainTimeoutMs = originalTimeout + }) + + test("an EXPLAIN that outlasts its deadline is no estimate, and the call stops waiting", async () => { + dbtCostEstimateInternals.explainTimeoutMs = 50 + useAdapter(calls, { type: "databricks", explain: () => new Promise(() => {}) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.title).toBe("dbt_cost_estimate: explain failed") + expect(result.output).toContain("did not answer within 0.05 s") + expect(result.metadata.bytes).toBeUndefined() + }) + + test("an EXPLAIN that answers within its deadline is read as before", async () => { + dbtCostEstimateInternals.explainTimeoutMs = 5_000 + useAdapter(calls, { type: "snowflake", explain: rendered(SNOWFLAKE_PLAN) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.metadata.bytes).toBe(2_147_483_648) + }) + + test.each([ + ["a multi-line block comment", "select 1; /* a\nb */", "select 1"], + ["a second semicolon and a comment", "select 1;; -- c", "select 1"], + ["a comment on the next line", "select 1;\n-- done\n", "select 1"], + ])("Snowflake sends %s after the final semicolon to nobody", async (_, compiled, sent) => { + expect(mayBeScript(compiled, "snowflake")).toBe(false) + useAdapter(calls, { type: "snowflake", compile: async () => compiled, explain: rendered(SNOWFLAKE_PLAN) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(calls.queries).toEqual([[explainJinja("EXPLAIN USING JSON", sent), undefined]]) + expect(result.metadata.success).toBe(true) + }) + + test.each([ + ["select 'a;b' from t; -- c", "snowflake", "select 'a;b' from t"], + ["select \"a;b\" /* ; */ from t", "snowflake", 'select "a;b" /* ; */ from t'], + ["select `a;b` from t; /* x */", "databricks", "select `a;b` from t"], + ["select 1 -- not; a split", "snowflake", "select 1 -- not; a split"], + ["select 1", "snowflake", "select 1"], + ])("firstStatement(%p, %s) keeps what the driver sends as the statement", (sql, type, expected) => { + expect(firstStatement(sql, type)).toBe(expected) + }) + + test("a section heading inside a multi-line literal does not end the plan", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Project [concat(w#1, ", + "== Physical Plan ==", + ") AS z#2], Statistics(sizeInBytes=1.0 KiB)", + "+- Relation spark_catalog.default.b[w#1] parquet, Statistics(sizeInBytes=2.0 GiB)", + "", + "== Physical Plan ==", + "*(1) Project", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 2 * 1024 ** 3 }) + }) + + test("a section heading after a finished node still ends the plan", () => { + const plan = "== Optimized Logical Plan ==\nRelation main.t[a#0] parquet, Statistics(sizeInBytes=4.0 KiB)\n== Physical Plan ==\nRelation main.u[a#0] parquet, Statistics(sizeInBytes=9.0 GiB)" + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 4096 }) + }) + + test("a leaf that holds an inner plan keeps its own size", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Relation main.s.t[a#0] parquet, Statistics(sizeInBytes=2.0 GiB)", + ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) + }) + + test("a node with a child and an inner plan is still not a leaf", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Filter (a#0 IN (list#5 [])), Statistics(sizeInBytes=1.0 GiB)", + ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", + "+- Relation main.s.t[a#0] parquet, Statistics(sizeInBytes=2.0 GiB)", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) + }) + + test("Snowflake's 0 bytes is not called an upper bound: it also reports 0 for a source it cannot size", async () => { + useAdapter(calls, { type: "snowflake", explain: rendered('{"GlobalStats":{"partitionsTotal":0,"partitionsAssigned":0,"bytesAssigned":0}}') }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ sql: "select $1 from @stage" }, ctx) + expect(result.metadata).toMatchObject({ success: true, bound: "unknown", bytes: 0 }) + expect(result.output).toContain("not a cap") + expect(result.output).not.toContain("an upper bound") + }) + + test("a leaf with no readable size gets no ANALYZE advice: it is not known to lack statistics", async () => { + useAdapter(calls, { type: "databricks", explain: rendered("== Optimized Logical Plan ==\nRelation main.t[a#0] parquet") }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.metadata.success).toBe(false) + expect(result.output).toContain("printed no size this tool can read for main.t") + expect(result.output).not.toContain("ANALYZE") + }) +}) + describe("mayBeScript", () => { test.each([ ["snowflake", "select 1; delete from orders"], @@ -997,103 +1097,3 @@ describe("review follow-ups, round twelve", () => { } }) }) - -describe("follow-ups to the planner estimate", () => { - const rendered = (row: unknown) => async () => JSON.stringify([row]) - const originalTimeout = dbtCostEstimateInternals.explainTimeoutMs - afterEach(() => { - dbtCostEstimateInternals.explainTimeoutMs = originalTimeout - }) - - test("an EXPLAIN that outlasts its deadline is no estimate, and the call stops waiting", async () => { - dbtCostEstimateInternals.explainTimeoutMs = 50 - useAdapter(calls, { type: "databricks", explain: () => new Promise(() => {}) }) - const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) - expect(result.title).toBe("dbt_cost_estimate: explain failed") - expect(result.output).toContain("did not answer within 0.05 s") - expect(result.metadata.bytes).toBeUndefined() - }) - - test("an EXPLAIN that answers within its deadline is read as before", async () => { - dbtCostEstimateInternals.explainTimeoutMs = 5_000 - useAdapter(calls, { type: "snowflake", explain: rendered(SNOWFLAKE_PLAN) }) - const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) - expect(result.metadata.bytes).toBe(2_147_483_648) - }) - - test.each([ - ["a multi-line block comment", "select 1; /* a\nb */", "select 1"], - ["a second semicolon and a comment", "select 1;; -- c", "select 1"], - ["a comment on the next line", "select 1;\n-- done\n", "select 1"], - ])("Snowflake sends %s after the final semicolon to nobody", async (_, compiled, sent) => { - expect(mayBeScript(compiled, "snowflake")).toBe(false) - useAdapter(calls, { type: "snowflake", compile: async () => compiled, explain: rendered(SNOWFLAKE_PLAN) }) - const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) - expect(calls.queries).toEqual([[explainJinja("EXPLAIN USING JSON", sent), undefined]]) - expect(result.metadata.success).toBe(true) - }) - - test.each([ - ["select 'a;b' from t; -- c", "snowflake", "select 'a;b' from t"], - ["select \"a;b\" /* ; */ from t", "snowflake", 'select "a;b" /* ; */ from t'], - ["select `a;b` from t; /* x */", "databricks", "select `a;b` from t"], - ["select 1 -- not; a split", "snowflake", "select 1 -- not; a split"], - ["select 1", "snowflake", "select 1"], - ])("firstStatement(%p, %s) keeps what the driver sends as the statement", (sql, type, expected) => { - expect(firstStatement(sql, type)).toBe(expected) - }) - - test("a section heading inside a multi-line literal does not end the plan", () => { - const plan = [ - "== Optimized Logical Plan ==", - "Project [concat(w#1, ", - "== Physical Plan ==", - ") AS z#2], Statistics(sizeInBytes=1.0 KiB)", - "+- Relation spark_catalog.default.b[w#1] parquet, Statistics(sizeInBytes=2.0 GiB)", - "", - "== Physical Plan ==", - "*(1) Project", - ].join("\n") - expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 2 * 1024 ** 3 }) - }) - - test("a section heading after a finished node still ends the plan", () => { - const plan = "== Optimized Logical Plan ==\nRelation main.t[a#0] parquet, Statistics(sizeInBytes=4.0 KiB)\n== Physical Plan ==\nRelation main.u[a#0] parquet, Statistics(sizeInBytes=9.0 GiB)" - expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 4096 }) - }) - - test("a leaf that holds an inner plan keeps its own size", () => { - const plan = [ - "== Optimized Logical Plan ==", - "Relation main.s.t[a#0] parquet, Statistics(sizeInBytes=2.0 GiB)", - ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", - ].join("\n") - expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) - }) - - test("a node with a child and an inner plan is still not a leaf", () => { - const plan = [ - "== Optimized Logical Plan ==", - "Filter (a#0 IN (list#5 [])), Statistics(sizeInBytes=1.0 GiB)", - ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", - "+- Relation main.s.t[a#0] parquet, Statistics(sizeInBytes=2.0 GiB)", - ].join("\n") - expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) - }) - - test("Snowflake's 0 bytes is not called an upper bound: it also reports 0 for a source it cannot size", async () => { - useAdapter(calls, { type: "snowflake", explain: rendered('{"GlobalStats":{"partitionsTotal":0,"partitionsAssigned":0,"bytesAssigned":0}}') }) - const result = await (await initTool(DbtCostEstimateTool)).execute({ sql: "select $1 from @stage" }, ctx) - expect(result.metadata).toMatchObject({ success: true, bound: "unknown", bytes: 0 }) - expect(result.output).toContain("not a cap") - expect(result.output).not.toContain("an upper bound") - }) - - test("a leaf with no readable size gets no ANALYZE advice: it is not known to lack statistics", async () => { - useAdapter(calls, { type: "databricks", explain: rendered("== Optimized Logical Plan ==\nRelation main.t[a#0] parquet") }) - const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) - expect(result.metadata.success).toBe(false) - expect(result.output).toContain("printed no size this tool can read for main.t") - expect(result.output).not.toContain("ANALYZE") - }) -}) From 310db304a82c2b519add97707763a068ea368c0c Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 20:01:21 +0530 Subject: [PATCH 3/7] fix(dbt-cost-estimate): end a plan section at Spark's empty line before a heading, and keep a total beside an unsized Snowflake scan from being a cap Co-Authored-By: Claude Sonnet 5.5 --- .../src/altimate/tools/dbt-cost-estimate.ts | 40 ++++++++++++------- .../test/altimate/dbt-cost-estimate.test.ts | 31 +++++++++++++- 2 files changed, 56 insertions(+), 15 deletions(-) diff --git a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts index 640866c336..8749438163 100644 --- a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts +++ b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts @@ -72,7 +72,13 @@ export function formatBytes(bytes: number): string { export type NoStats = { noStats: true; relation?: string; unread?: true } /** A scan estimate from the warehouse's query planner: what EXPLAIN says the query reads, without running it. */ -export type PlanEstimate = { bytes: number; partitionsAssigned?: number; partitionsTotal?: number } +export type PlanEstimate = { + bytes: number + partitionsAssigned?: number + partitionsTotal?: number + /** Snowflake: the total may leave out a source it cannot size (an external table, a stage), so it is not a cap. */ + unsized?: true +} const count = (value: unknown) => (typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined) @@ -96,8 +102,18 @@ export function parseSnowflakeExplain(content: unknown): PlanEstimate | undefine if (bytes === undefined) return undefined const partitionsAssigned = count(stats.partitionsAssigned) const partitionsTotal = count(stats.partitionsTotal) + // A total of 0 beside a scan (or with no operations to read), or a scan of an external table or stage, or one with no + // size of its own, may leave data out of it. A 0 with no scan at all is a query that reads nothing. + const operations = (plan as { Operations?: unknown }).Operations + const scans = (Array.isArray(operations) ? operations.flat(2) : []).filter( + (op): op is { operation: string; bytesAssigned?: unknown } => typeof (op as { operation?: unknown } | null)?.operation === "string", + ) + const unsized = + (bytes === 0 && (!Array.isArray(operations) || scans.some((op) => /scan/i.test(op.operation)))) || + scans.some((op) => /external|stage/i.test(op.operation) || (/scan/i.test(op.operation) && count(op.bytesAssigned) === undefined)) return { bytes: Math.round(bytes), + ...(unsized && { unsized: true as const }), ...(partitionsAssigned !== undefined && { partitionsAssigned }), ...(partitionsTotal !== undefined && { partitionsTotal }), } @@ -114,13 +130,6 @@ const SPARK_NO_SIZE = 2 ** 62 /** The headers Spark writes between the sections of an EXPLAIN. */ const SPARK_SECTION = /^== (Parsed Logical Plan|Analyzed Logical Plan|Optimized Logical Plan|Physical Plan) ==\s*$/ -/** Whether a node's text has more opening brackets than closing ones: its line continues on the next. */ -function opensBracket(text: string): boolean { - let open = 0 - for (const c of text) open += c === "(" || c === "[" ? 1 : c === ")" || c === "]" ? -1 : 0 - return open > 0 -} - /** A `sizeInBytes=` figure read back into bytes: "12.3 MiB", "16.0 B", or past a long "1.23E+21 B". */ function sparkBytes(figure: string): number | undefined { const match = /^(\d+(?:\.\d+)?(?:E[+-]?\d+)?)\s*([A-Za-z]+)$/i.exec(figure.trim()) @@ -144,10 +153,13 @@ export function parseDatabricksExplainCost(plan: unknown): PlanEstimate | NoStat const start = lines.findIndex((line) => /^\s*==\s*Optimized Logical Plan\s*==\s*$/i.test(line)) if (start < 0) return undefined const nodes: { depth: number; text: string }[] = [] - for (const line of lines.slice(start + 1)) { - // Only Spark's own section headers end the plan: a line of a multi-line node could look like one. A header - // while the node above still has an open bracket is the rest of that node (a literal holding a line break). - if (SPARK_SECTION.test(line) && !(nodes.length > 0 && opensBracket(nodes[nodes.length - 1].text))) break + for (const [at, line] of lines.slice(start + 1).entries()) { + const previous = at > 0 ? lines[start + at] : undefined + // Only Spark's own section headers end the plan: a line of a multi-line node could look like one. Spark sets + // each section off with an empty line, which the line of a literal holding a line break does not have before it. + // A literal built to hold an empty line, a heading and a statistics suffix would still end the plan early; the + // SQL is the agent's own, so that is not defended against. + if (SPARK_SECTION.test(line) && (previous === undefined || !previous.trim())) break if (!line.trim()) continue // Each level of the tree is three characters: ": " or " " for an ancestor, ":- " or "+- " for the node itself. const prefix = /^(?:: | )*(?:[:+]- )?/.exec(line)![0] @@ -432,9 +444,9 @@ async function explainEstimate( ? `${parsed.partitionsAssigned} of ${parsed.partitionsTotal} partitions after pruning; ` : "" // Snowflake may give 0 for a source it cannot size when it compiles (an external table, a stage): not a cap. - const unsized = type === "snowflake" && parsed.bytes === 0 + const unsized = type === "snowflake" && parsed.unsized === true const accuracy = unsized - ? "Snowflake also reports 0 for a source it cannot size at compile time, such as an external table or a stage, so this is not a cap" + ? "Snowflake can leave a source it cannot size at compile time (an external table, a stage) out of this figure, or report 0, so it is not a cap" : type === "snowflake" ? `${partitions}an upper bound: runtime pruning can scan less, and a cached result none` : "table sizes before column pruning and file skipping, which usually read less; not a bound either way" diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index e74398d5c7..31f99ac7c9 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -679,10 +679,39 @@ describe("follow-ups to the planner estimate", () => { }) test("a section heading after a finished node still ends the plan", () => { - const plan = "== Optimized Logical Plan ==\nRelation main.t[a#0] parquet, Statistics(sizeInBytes=4.0 KiB)\n== Physical Plan ==\nRelation main.u[a#0] parquet, Statistics(sizeInBytes=9.0 GiB)" + const plan = "== Optimized Logical Plan ==\nRelation main.t[a#0] parquet, Statistics(sizeInBytes=4.0 KiB)\n\n== Physical Plan ==\nRelation main.u[a#0] parquet, Statistics(sizeInBytes=9.0 GiB)" expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 4096 }) }) + test("brackets inside a printed name do not stretch a node over the plan's real end", () => { + const plan = "== Optimized Logical Plan ==\nRelation main.t[a(b#0] parquet, Statistics(sizeInBytes=2.0 GiB)\n\n== Physical Plan ==\nFileScan parquet main.t[a(b#0]" + expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 2 * 1024 ** 3 }) + }) + + test("Snowflake: a scan of an external table or stage, or a scan with no size, keeps the total from being a cap", () => { + const mixed = (extra: object) => + JSON.stringify({ + GlobalStats: { bytesAssigned: 1024 }, + Operations: [[{ id: 1, operation: "TableScan", objects: ["T"], bytesAssigned: 1024 }, { id: 2, ...extra }]], + }) + expect(parseSnowflakeExplain(mixed({ operation: "ExternalScan", bytesAssigned: 0 }))).toEqual({ bytes: 1024, unsized: true }) + expect(parseSnowflakeExplain(mixed({ operation: "StageScan" }))).toEqual({ bytes: 1024, unsized: true }) + expect(parseSnowflakeExplain(mixed({ operation: "TableScan", objects: ["U"] }))).toEqual({ bytes: 1024, unsized: true }) + expect(parseSnowflakeExplain(mixed({ operation: "Filter" }))).toEqual({ bytes: 1024 }) + expect(parseSnowflakeExplain(SNOWFLAKE_PLAN)).toEqual({ bytes: 2_147_483_648, partitionsAssigned: 37, partitionsTotal: 1240 }) + }) + + test("Snowflake: a positive total beside an external scan is not called an upper bound", async () => { + const plan = JSON.stringify({ + GlobalStats: { partitionsTotal: 2, partitionsAssigned: 2, bytesAssigned: 1024 }, + Operations: [[{ id: 1, operation: "TableScan", objects: ["T"], bytesAssigned: 1024 }, { id: 2, operation: "ExternalScan", objects: ["E"] }]], + }) + useAdapter(calls, { type: "snowflake", explain: rendered(plan) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ sql: "select * from t join e" }, ctx) + expect(result.metadata).toMatchObject({ success: true, bound: "unknown", bytes: 1024 }) + expect(result.output).not.toContain("an upper bound") + }) + test("a leaf that holds an inner plan keeps its own size", () => { const plan = [ "== Optimized Logical Plan ==", From 6ad48d8d2c7f683c5bf39151bef1776d277b0bc9 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 20:25:59 +0530 Subject: [PATCH 4/7] fix(dbt-cost-estimate): a Snowflake secure view hides what it scans, so its total is not a cap Co-Authored-By: Claude Sonnet 5.5 --- packages/opencode/src/altimate/tools/dbt-cost-estimate.ts | 4 ++-- packages/opencode/test/altimate/dbt-cost-estimate.test.ts | 4 ++++ 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts index 8749438163..9428c86a7f 100644 --- a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts +++ b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts @@ -102,7 +102,7 @@ export function parseSnowflakeExplain(content: unknown): PlanEstimate | undefine if (bytes === undefined) return undefined const partitionsAssigned = count(stats.partitionsAssigned) const partitionsTotal = count(stats.partitionsTotal) - // A total of 0 beside a scan (or with no operations to read), or a scan of an external table or stage, or one with no + // A total of 0 beside a scan (or with no operations to read), or a scan of an external table or stage, a secure view (its scanned size is hidden), or one with no // size of its own, may leave data out of it. A 0 with no scan at all is a query that reads nothing. const operations = (plan as { Operations?: unknown }).Operations const scans = (Array.isArray(operations) ? operations.flat(2) : []).filter( @@ -110,7 +110,7 @@ export function parseSnowflakeExplain(content: unknown): PlanEstimate | undefine ) const unsized = (bytes === 0 && (!Array.isArray(operations) || scans.some((op) => /scan/i.test(op.operation)))) || - scans.some((op) => /external|stage/i.test(op.operation) || (/scan/i.test(op.operation) && count(op.bytesAssigned) === undefined)) + scans.some((op) => /external|stage|secure/i.test(op.operation) || (/scan/i.test(op.operation) && count(op.bytesAssigned) === undefined)) return { bytes: Math.round(bytes), ...(unsized && { unsized: true as const }), diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index 31f99ac7c9..9b81233231 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -696,6 +696,10 @@ describe("follow-ups to the planner estimate", () => { }) expect(parseSnowflakeExplain(mixed({ operation: "ExternalScan", bytesAssigned: 0 }))).toEqual({ bytes: 1024, unsized: true }) expect(parseSnowflakeExplain(mixed({ operation: "StageScan" }))).toEqual({ bytes: 1024, unsized: true }) + expect(parseSnowflakeExplain(mixed({ operation: "SecureView", objects: ["V"] }))).toEqual({ bytes: 1024, unsized: true }) + expect(parseSnowflakeExplain(mixed({ operation: "DynamicSecureView" }))).toEqual({ bytes: 1024, unsized: true }) + // A secure view hides what it scans, so a total of 0 beside one is not a cap either. + expect(parseSnowflakeExplain('{"GlobalStats":{"bytesAssigned":0},"Operations":[[{"id":1,"operation":"SecureView"}]]}')).toEqual({ bytes: 0, unsized: true }) expect(parseSnowflakeExplain(mixed({ operation: "TableScan", objects: ["U"] }))).toEqual({ bytes: 1024, unsized: true }) expect(parseSnowflakeExplain(mixed({ operation: "Filter" }))).toEqual({ bytes: 1024 }) expect(parseSnowflakeExplain(SNOWFLAKE_PLAN)).toEqual({ bytes: 2_147_483_648, partitionsAssigned: 37, partitionsTotal: 1240 }) From 30dfaab68fe18eae556d46990cf06e6c196690a8 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 20:34:55 +0530 Subject: [PATCH 5/7] test(dbt-cost-estimate): inner plan without a size, late rejection after the deadline; docs: where altimate-dbt is on the path Co-Authored-By: Claude Sonnet 5.5 --- .../guides/using-with-claude-code.md | 2 +- .../test/altimate/dbt-cost-estimate.test.ts | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/docs/docs/data-engineering/guides/using-with-claude-code.md b/docs/docs/data-engineering/guides/using-with-claude-code.md index 9d1b5f6533..1fc3769270 100644 --- a/docs/docs/data-engineering/guides/using-with-claude-code.md +++ b/docs/docs/data-engineering/guides/using-with-claude-code.md @@ -26,7 +26,7 @@ This gives Claude Code access to: ### What `altimate-dbt` is -When altimate works on a dbt project, it often runs `altimate-dbt`. It is a small command-line tool for dbt tasks: it finds your dbt project, Python environment and adapter, then compiles models, runs and tests them, and inspects columns and schemas. It is installed together with altimate-code, so there is nothing separate to set up, and altimate runs it for you as part of a task. You can also run it yourself in a terminal. See [dbt Tools](../tools/dbt-tools.md#altimate-dbt-cli) for its commands. +When altimate works on a dbt project, it often runs `altimate-dbt`. It is a small command-line tool for dbt tasks: it finds your dbt project, Python environment and adapter, then compiles models, runs and tests them, and inspects columns and schemas. It is installed together with altimate-code, so there is nothing separate to set up, and altimate runs it for you as part of a task. It is on the path of the commands altimate runs, which is not necessarily your own terminal's. See [dbt Tools](../tools/dbt-tools.md#altimate-dbt-cli) for its commands. ## Example workflows diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index 9b81233231..f4fe1188a3 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -725,6 +725,26 @@ describe("follow-ups to the planner estimate", () => { expect(parseDatabricksExplainCost(plan)).toEqual({ bytes: 5 * 1024 ** 3 }) }) + test("a leaf with an inner plan but no size of its own is no estimate, not the inner plan's size", () => { + const plan = [ + "== Optimized Logical Plan ==", + "Relation main.s.t[a#0] parquet", + ": +- Relation main.s.u[a#1] parquet, Statistics(sizeInBytes=3.0 GiB)", + ].join("\n") + expect(parseDatabricksExplainCost(plan)).toEqual({ noStats: true, relation: "main.s.t", unread: true }) + }) + + test("an EXPLAIN that rejects after its deadline changes nothing", async () => { + dbtCostEstimateInternals.explainTimeoutMs = 30 + let reject!: (e: Error) => void + useAdapter(calls, { type: "snowflake", explain: () => new Promise((_, r) => (reject = r)) }) + const result = await (await initTool(DbtCostEstimateTool)).execute({ model: "orders" }, ctx) + expect(result.title).toBe("dbt_cost_estimate: explain failed") + reject(new Error("late")) + await new Promise((resolve) => setTimeout(resolve, 20)) + expect(result.metadata.success).toBe(false) + }) + test("a node with a child and an inner plan is still not a leaf", () => { const plan = [ "== Optimized Logical Plan ==", From ab8cdbecea479e75d7c9a4865dcc653e1fef55f8 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Thu, 19 Nov 2026 20:39:26 +0530 Subject: [PATCH 6/7] fix(dbt-cost-estimate): a zero-sized Snowflake scan is unsized too; name every unsized source; reword the altimate-dbt line; fix the execute example Co-Authored-By: Claude Sonnet 5.5 --- .opencode/skills/dbt-analyze/SKILL.md | 2 +- .opencode/skills/dbt-develop/SKILL.md | 2 +- .opencode/skills/dbt-docs/SKILL.md | 2 +- .opencode/skills/dbt-schema-verify/SKILL.md | 2 +- .opencode/skills/dbt-test/SKILL.md | 2 +- .opencode/skills/dbt-troubleshoot/SKILL.md | 2 +- .opencode/skills/dbt-unit-tests/SKILL.md | 2 +- .opencode/skills/sql-review/SKILL.md | 2 +- docs/docs/data-engineering/tools/dbt-tools.md | 2 +- .../opencode/src/altimate/tools/dbt-cost-estimate.ts | 12 ++++++------ .../opencode/test/altimate/dbt-cost-estimate.test.ts | 1 + 11 files changed, 16 insertions(+), 15 deletions(-) diff --git a/.opencode/skills/dbt-analyze/SKILL.md b/.opencode/skills/dbt-analyze/SKILL.md index 3696fe0d27..d063e3122f 100644 --- a/.opencode/skills/dbt-analyze/SKILL.md +++ b/.opencode/skills/dbt-analyze/SKILL.md @@ -5,7 +5,7 @@ description: Analyze downstream impact of dbt model changes using column-level l # dbt Impact Analysis -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** any (read-only analysis) diff --git a/.opencode/skills/dbt-develop/SKILL.md b/.opencode/skills/dbt-develop/SKILL.md index 5e79b711eb..076c280b30 100644 --- a/.opencode/skills/dbt-develop/SKILL.md +++ b/.opencode/skills/dbt-develop/SKILL.md @@ -29,7 +29,7 @@ description: | # dbt Model Development -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** builder or migrator (requires file write access) diff --git a/.opencode/skills/dbt-docs/SKILL.md b/.opencode/skills/dbt-docs/SKILL.md index 60d0a5c8fa..ec98007e79 100644 --- a/.opencode/skills/dbt-docs/SKILL.md +++ b/.opencode/skills/dbt-docs/SKILL.md @@ -5,7 +5,7 @@ description: Document dbt models and columns in schema.yml with business context # dbt Documentation -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** builder or migrator (requires file write access) diff --git a/.opencode/skills/dbt-schema-verify/SKILL.md b/.opencode/skills/dbt-schema-verify/SKILL.md index f40ce54889..14e62ae116 100644 --- a/.opencode/skills/dbt-schema-verify/SKILL.md +++ b/.opencode/skills/dbt-schema-verify/SKILL.md @@ -23,7 +23,7 @@ description: | # dbt schema-verify -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## When to invoke this skill — every time diff --git a/.opencode/skills/dbt-test/SKILL.md b/.opencode/skills/dbt-test/SKILL.md index 54f8e7a14e..7b4044784f 100644 --- a/.opencode/skills/dbt-test/SKILL.md +++ b/.opencode/skills/dbt-test/SKILL.md @@ -5,7 +5,7 @@ description: Add schema tests, unit tests, and data quality checks to dbt models # dbt Testing -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** builder or migrator (requires file write access) diff --git a/.opencode/skills/dbt-troubleshoot/SKILL.md b/.opencode/skills/dbt-troubleshoot/SKILL.md index 4037213bcb..abe4c5374b 100644 --- a/.opencode/skills/dbt-troubleshoot/SKILL.md +++ b/.opencode/skills/dbt-troubleshoot/SKILL.md @@ -5,7 +5,7 @@ description: Debug dbt errors — compilation failures, runtime database errors, # dbt Troubleshooting -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** any (read-only diagnosis), builder (if applying fixes) diff --git a/.opencode/skills/dbt-unit-tests/SKILL.md b/.opencode/skills/dbt-unit-tests/SKILL.md index d2ac449fe6..2224ce86d9 100644 --- a/.opencode/skills/dbt-unit-tests/SKILL.md +++ b/.opencode/skills/dbt-unit-tests/SKILL.md @@ -5,7 +5,7 @@ description: Generate dbt unit tests automatically for any model. Analyzes SQL l # dbt Unit Test Generation -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** builder or migrator (requires file write access) diff --git a/.opencode/skills/sql-review/SKILL.md b/.opencode/skills/sql-review/SKILL.md index f1840d651a..527fc6b527 100644 --- a/.opencode/skills/sql-review/SKILL.md +++ b/.opencode/skills/sql-review/SKILL.md @@ -5,7 +5,7 @@ description: Pre-merge SQL quality gate — lint 26 anti-patterns, grade readabi # SQL Review -The first time you name `altimate-dbt` to the user, say what it is: the dbt command-line tool installed with altimate-code. +The first time you name `altimate-dbt` to the user, say what it is: a command-line tool for dbt tasks, installed with altimate-code. ## Requirements **Agent:** any (read-only analysis) diff --git a/docs/docs/data-engineering/tools/dbt-tools.md b/docs/docs/data-engineering/tools/dbt-tools.md index 79714e1bb5..c61b697b92 100644 --- a/docs/docs/data-engineering/tools/dbt-tools.md +++ b/docs/docs/data-engineering/tools/dbt-tools.md @@ -158,7 +158,7 @@ altimate-dbt run altimate-dbt test # Utilities -altimate-dbt execute "SELECT 1" # Run a query via dbt adapter +altimate-dbt execute --query "SELECT 1" # Run a query via dbt adapter altimate-dbt columns my_model # List model columns altimate-dbt graph # View lineage/DAG altimate-dbt deps # Manage dependencies diff --git a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts index 9428c86a7f..6d05684c8d 100644 --- a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts +++ b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts @@ -76,7 +76,7 @@ export type PlanEstimate = { bytes: number partitionsAssigned?: number partitionsTotal?: number - /** Snowflake: the total may leave out a source it cannot size (an external table, a stage), so it is not a cap. */ + /** Snowflake: the total may leave out a source it cannot size (an external table, a stage, a secure view), so it is not a cap. */ unsized?: true } @@ -102,7 +102,7 @@ export function parseSnowflakeExplain(content: unknown): PlanEstimate | undefine if (bytes === undefined) return undefined const partitionsAssigned = count(stats.partitionsAssigned) const partitionsTotal = count(stats.partitionsTotal) - // A total of 0 beside a scan (or with no operations to read), or a scan of an external table or stage, a secure view (its scanned size is hidden), or one with no + // A total of 0 beside a scan (or with no operations to read), or a scan of an external table or stage, a secure view (its scanned size is hidden), or one with no or a zero // size of its own, may leave data out of it. A 0 with no scan at all is a query that reads nothing. const operations = (plan as { Operations?: unknown }).Operations const scans = (Array.isArray(operations) ? operations.flat(2) : []).filter( @@ -110,7 +110,7 @@ export function parseSnowflakeExplain(content: unknown): PlanEstimate | undefine ) const unsized = (bytes === 0 && (!Array.isArray(operations) || scans.some((op) => /scan/i.test(op.operation)))) || - scans.some((op) => /external|stage|secure/i.test(op.operation) || (/scan/i.test(op.operation) && count(op.bytesAssigned) === undefined)) + scans.some((op) => /external|stage|secure/i.test(op.operation) || (/scan/i.test(op.operation) && !count(op.bytesAssigned))) return { bytes: Math.round(bytes), ...(unsized && { unsized: true as const }), @@ -443,10 +443,10 @@ async function explainEstimate( parsed.partitionsAssigned !== undefined && parsed.partitionsTotal !== undefined ? `${parsed.partitionsAssigned} of ${parsed.partitionsTotal} partitions after pruning; ` : "" - // Snowflake may give 0 for a source it cannot size when it compiles (an external table, a stage): not a cap. + // Snowflake may give 0 for a source it cannot size when it compiles (an external table, a stage, a secure view): not a cap. const unsized = type === "snowflake" && parsed.unsized === true const accuracy = unsized - ? "Snowflake can leave a source it cannot size at compile time (an external table, a stage) out of this figure, or report 0, so it is not a cap" + ? "Snowflake can leave a source it cannot size at compile time (an external table, a stage, a secure view) out of this figure, or report 0, so it is not a cap" : type === "snowflake" ? `${partitions}an upper bound: runtime pruning can scan less, and a cached result none` : "table sizes before column pruning and file skipping, which usually read less; not a bound either way" @@ -471,7 +471,7 @@ async function explainEstimate( export const DbtCostEstimateTool = Tool.define("dbt_cost_estimate", { description: - "Estimate the bytes a dbt model or a SQL query would scan, without running it. BigQuery answers from a dry run (`maxBytes` bounds it, or `lowerBound` marks a floor); Snowflake (`EXPLAIN USING JSON`, bytes left after pruning) and Databricks (`EXPLAIN COST`, the sizes of the tables it reads) answer from the planner (`source: \"explain\"`; `bound` is \"upper\" on Snowflake (\"unknown\" when it reports 0, which it also does for a source it cannot size), \"estimate\" on Databricks), and none when Databricks has no table statistics. EXPLAIN compiles the query on the warehouse and scans no data: on Snowflake it needs no running warehouse (cloud-services time only); on Databricks it runs on the SQL warehouse or cluster the profile connects to, and starts it (billed while up) if it is stopped. A query that may be more than one statement is never EXPLAINed, nor on Databricks one that reads files directly (read_files, cloud_files, json.`path`), whose planning reads the files to infer a schema. Any other warehouse answers `supported: false` and nothing is compiled. Starts the dbt adapter (which runs `dbt deps`), so it needs write permission (`--allow-write` on `tool run` or the MCP server). The dry run never executes the final query, but compiling either input can render Jinja, and macros such as `run_query` can run real queries that are billed. Pass `model` (a model name, compiled as dbt would) or `sql` (may use Jinja).", + "Estimate the bytes a dbt model or a SQL query would scan, without running it. BigQuery answers from a dry run (`maxBytes` bounds it, or `lowerBound` marks a floor); Snowflake (`EXPLAIN USING JSON`, bytes left after pruning) and Databricks (`EXPLAIN COST`, the sizes of the tables it reads) answer from the planner (`source: \"explain\"`; `bound` is \"upper\" on Snowflake (\"unknown\" when the plan leaves out a source it cannot size: it reports 0 for one, or a scan of an external table, a stage or a secure view, or a scan with no size), \"estimate\" on Databricks), and none when Databricks has no table statistics. EXPLAIN compiles the query on the warehouse and scans no data: on Snowflake it needs no running warehouse (cloud-services time only); on Databricks it runs on the SQL warehouse or cluster the profile connects to, and starts it (billed while up) if it is stopped. A query that may be more than one statement is never EXPLAINed, nor on Databricks one that reads files directly (read_files, cloud_files, json.`path`), whose planning reads the files to infer a schema. Any other warehouse answers `supported: false` and nothing is compiled. Starts the dbt adapter (which runs `dbt deps`), so it needs write permission (`--allow-write` on `tool run` or the MCP server). The dry run never executes the final query, but compiling either input can render Jinja, and macros such as `run_query` can run real queries that are billed. Pass `model` (a model name, compiled as dbt would) or `sql` (may use Jinja).", parameters: z.object({ model: z.string().optional().describe("Model name to compile and estimate"), sql: z.string().optional().describe("SQL (may use Jinja) to compile and estimate"), diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index f4fe1188a3..79319778cc 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -696,6 +696,7 @@ describe("follow-ups to the planner estimate", () => { }) expect(parseSnowflakeExplain(mixed({ operation: "ExternalScan", bytesAssigned: 0 }))).toEqual({ bytes: 1024, unsized: true }) expect(parseSnowflakeExplain(mixed({ operation: "StageScan" }))).toEqual({ bytes: 1024, unsized: true }) + expect(parseSnowflakeExplain(mixed({ operation: "TableScan", objects: ["U"], bytesAssigned: 0 }))).toEqual({ bytes: 1024, unsized: true }) expect(parseSnowflakeExplain(mixed({ operation: "SecureView", objects: ["V"] }))).toEqual({ bytes: 1024, unsized: true }) expect(parseSnowflakeExplain(mixed({ operation: "DynamicSecureView" }))).toEqual({ bytes: 1024, unsized: true }) // A secure view hides what it scans, so a total of 0 beside one is not a cap either. From 27ff9e334094f43605076cf7925ceb7cc9146ae8 Mon Sep 17 00:00:00 2001 From: Harish Kumar Date: Fri, 20 Nov 2026 00:44:52 +0530 Subject: [PATCH 7/7] fix: name PATH in the altimate-dbt docs, pin the cost-estimate deadline failure, index loop Co-Authored-By: Claude Sonnet 5.5 --- docs/docs/data-engineering/guides/using-with-claude-code.md | 2 +- packages/opencode/src/altimate/tools/dbt-cost-estimate.ts | 5 +++-- packages/opencode/test/altimate/dbt-cost-estimate.test.ts | 2 ++ 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docs/data-engineering/guides/using-with-claude-code.md b/docs/docs/data-engineering/guides/using-with-claude-code.md index 1fc3769270..f7ede7ea56 100644 --- a/docs/docs/data-engineering/guides/using-with-claude-code.md +++ b/docs/docs/data-engineering/guides/using-with-claude-code.md @@ -26,7 +26,7 @@ This gives Claude Code access to: ### What `altimate-dbt` is -When altimate works on a dbt project, it often runs `altimate-dbt`. It is a small command-line tool for dbt tasks: it finds your dbt project, Python environment and adapter, then compiles models, runs and tests them, and inspects columns and schemas. It is installed together with altimate-code, so there is nothing separate to set up, and altimate runs it for you as part of a task. It is on the path of the commands altimate runs, which is not necessarily your own terminal's. See [dbt Tools](../tools/dbt-tools.md#altimate-dbt-cli) for its commands. +When altimate works on a dbt project, it often runs `altimate-dbt`. It is a small command-line tool for dbt tasks: it finds your dbt project, Python environment and adapter, then compiles models, runs and tests them, and inspects columns and schemas. It is installed together with altimate-code, so there is nothing separate to set up, and altimate runs it for you as part of a task. altimate adds it to the `PATH` of the commands it runs, which is not necessarily your terminal's `PATH`. See [dbt Tools](../tools/dbt-tools.md#altimate-dbt-cli) for its commands. ## Example workflows diff --git a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts index 6d05684c8d..d6ca409db6 100644 --- a/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts +++ b/packages/opencode/src/altimate/tools/dbt-cost-estimate.ts @@ -153,8 +153,9 @@ export function parseDatabricksExplainCost(plan: unknown): PlanEstimate | NoStat const start = lines.findIndex((line) => /^\s*==\s*Optimized Logical Plan\s*==\s*$/i.test(line)) if (start < 0) return undefined const nodes: { depth: number; text: string }[] = [] - for (const [at, line] of lines.slice(start + 1).entries()) { - const previous = at > 0 ? lines[start + at] : undefined + for (let i = start + 1; i < lines.length; i++) { + const line = lines[i] + const previous = i > start + 1 ? lines[i - 1] : undefined // Only Spark's own section headers end the plan: a line of a multi-line node could look like one. Spark sets // each section off with an empty line, which the line of a literal holding a line break does not have before it. // A literal built to hold an empty line, a heading and a statistics suffix would still end the plan early; the diff --git a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts index 79319778cc..c551ec0f4d 100644 --- a/packages/opencode/test/altimate/dbt-cost-estimate.test.ts +++ b/packages/opencode/test/altimate/dbt-cost-estimate.test.ts @@ -744,6 +744,8 @@ describe("follow-ups to the planner estimate", () => { reject(new Error("late")) await new Promise((resolve) => setTimeout(resolve, 20)) expect(result.metadata.success).toBe(false) + expect(result.output).toContain("did not answer within 0.03 s") + expect(result.output).not.toContain("late") }) test("a node with a child and an inner plan is still not a leaf", () => {