fix(dbt-cost-estimate): follow-ups to the planner estimate; say what altimate-dbt is

HK
13m ago
+262-16

Issue for this PR

Follow-up to #1768 (the remaining minor points of its approved review) and a docs note on altimate-dbt. Independent of #1776, which touches the same file in disjoint places: a merge of the two is clean (checked with git merge-tree).

Type of change

  • Bug fix
  • New feature
  • Refactor / code improvement
  • Documentation

What does this PR do?

dbt_cost_estimate on Snowflake and Databricks (packages/opencode/src/altimate/tools/dbt-cost-estimate.ts):

  • EXPLAIN deadline. The EXPLAIN now has a deadline (90 s, dbtCostEstimateInternals.explainTimeoutMs) next to the existing cancellation: a call that outlasts it answers "explain failed" instead of waiting. The adapter's unsafeCompileQuery(sql, model) takes no signal, so the statement already sent cannot be cancelled from here; the call stops waiting for it. That half of the review point is declined.
  • Comment-only text after the final ;. mayBeScript already allows comments and semicolons there, but they were still sent and the driver split them off as a second statement (select 1; /* a\nb */). Only the SQL up to the first ; outside quotes and comments is sent now (firstStatement).
  • Section heading inside a multi-line literal. A == Physical Plan == line ends the Databricks plan only when the node above it has no open bracket; otherwise it is the rest of that node.
  • bytesAssigned: 0. Snowflake can report 0 for a source it cannot size at compile time, so 0 is no longer called an upper bound: bound: "unknown", and the text says it is not a cap.
  • A leaf with an inner plan. A node is a leaf when no later node sits one level below it before the tree comes back up, so Relation t followed by an inner plan at two levels keeps its own size.
  • No-statistics message. The ANALYZE TABLE advice is given only when Spark's default size was seen; a leaf that printed no readable size gets "printed no size this tool can read" and no advice.

Docs: docs/docs/data-engineering/guides/using-with-claude-code.md says what altimate-dbt is (installed with altimate-code, run by the agent, links to dbt Tools), and the dbt skills that name it tell the agent to say so the first time it names it to a user.

How did you verify your code works?

  • bun test test/altimate/dbt-cost-estimate.test.ts (211 pass) and bun test test/skill (1383 pass); bun typecheck clean.
  • Each fix has a regression test that fails on origin/main: 10 of the 16 new test cases fail there (the rest pin behaviour that must not change).

Cost side effects

None. No new model calls, warehouse queries or cloud resources: the same single EXPLAIN is sent, now bounded by a deadline, and with trailing comments left out.

Checklist

  • I have tested my changes locally
  • I have not included unrelated changes in this PR
  • I checked for cost side effects (model calls, queries or cloud resources that grow with user data) and described them, or wrote "none"

Summary by cubic

Fixes several edge cases in the dbt-cost-estimate planner estimate and explains what altimate-dbt is wherever it is first named.

  • An EXPLAIN that doesn't answer within 90 seconds is treated as no estimate instead of waiting forever; the call gives up while the statement keeps running on the warehouse.
  • EXPLAIN is now sent only the first statement of the SQL, so trailing semicolons or comments (including multi-line block comments) after it are no longer sent to the warehouse.
  • Spark section headings end a plan only after the empty line that sets a section off, so a heading inside a multi-line literal no longer cuts parsing short, and a leaf that holds an inner plan on its own line keeps its own size.
  • Snowflake sizes that may leave a source out — an external table, a stage, a scan without a size, or 0 bytes — are now bound: "unknown" instead of "upper", since Snowflake reports 0 (or an incomplete total) for sources it cannot size at compile time.
  • A leaf with no readable size (as opposed to Spark's default) gets no ANALYZE advice, because it isn't known to lack statistics.
  • The dbt skills and the Claude Code guide now state what altimate-dbt is the first time it's named.

Summary by CodeRabbit

  • Documentation

    • Clarified that altimate-dbt is the dbt command-line tool installed with altimate-code, and added guidance on its role in dbt workflows.
  • Bug Fixes

    • Improved cost estimates for Databricks and Snowflake, including clearer handling when plan statistics are unavailable or a zero-byte result does not provide a reliable limit.
    • Cost estimation now processes only the first SQL statement and stops waiting after 90 seconds.