Skip to content

feat(appkit): resolve schema-relative typegen queries via catalog/schema context#464

Open
QuentinAmbard wants to merge 1 commit into
databricks:mainfrom
QuentinAmbard:feat/typegen-catalog-schema-context
Open

feat(appkit): resolve schema-relative typegen queries via catalog/schema context#464
QuentinAmbard wants to merge 1 commit into
databricks:mainfrom
QuentinAmbard:feat/typegen-catalog-schema-context

Conversation

@QuentinAmbard

Copy link
Copy Markdown

Problem

The type-generator's DESCRIBE pass runs DESCRIBE QUERY <sql> with only a warehouse_id and no session catalog/schema. Queries written schema-relative — unqualified table names like FROM orders — therefore fail at typegen time with TABLE_OR_VIEW_NOT_FOUND, even though they resolve fine at runtime (the analytics route can pass catalog/schema as statement context). When DESCRIBE fails, the generated types silently degrade to result: unknown, so apps lose chart type-safety with no obvious cause.

This is increasingly common: writing queries schema-relative (and supplying catalog/schema as session context) is how an app stays portable across workspaces without hardcoding catalog.schema.table in every .sql.

Repro

Same table, same warehouse — only difference is the session context:

// No catalog/schema (what typegen does today):
{ "warehouse_id": "", "statement": "SELECT * FROM silver_returns LIMIT 1" }
// → FAILED: [TABLE_OR_VIEW_NOT_FOUND] The table or view `silver_returns` cannot be found.

// With catalog/schema (what the runtime route does):
{ "warehouse_id": "", "catalog": "retail_consumer_goods", "schema": "luxebeauty_demo",
  "statement": "SELECT * FROM silver_returns LIMIT 1" }
// → SUCCEEDED

Fix

Thread an optional catalog/schema through the typegen path so DESCRIBE runs with the same session context the runtime uses:

  • vite-plugin.ts reads DATABRICKS_CATALOG / DATABRICKS_SCHEMA from env (right next to the existing DATABRICKS_WAREHOUSE_ID) and forwards them.
  • generateFromEntryPointgenerateQueriesFromDescribedescribeAdaptive carry the optional context down to executeStatement, which honors top-level catalog/schema as the equivalent of USE CATALOG / USE SCHEMA for that one statement.

I used the native top-level catalog/schema fields rather than prepending USE CATALOG; … to the statement string, since the Statement Execution API already supports them and it avoids multi-statement handling.

Backward compatibility

When the env vars are unset, no catalog/schema keys are added to the request and behavior is byte-for-byte unchanged. Existing behavior for fully-qualified queries is unaffected.

Tests

Added two describeAdaptive tests in statement-result.test.ts:

  • forwards catalog/schema to executeStatement when context is provided;
  • omits both keys when no context is passed (back-compat).

Full package: tsc --noEmit clean, biome check clean, commitlint clean, 524 type-generator + analytics tests pass.

…ema context

The type-generator DESCRIBE pass ran `DESCRIBE QUERY <sql>` with only a
warehouse id and no session catalog/schema. Schema-relative queries —
unqualified table names like `FROM orders`, which resolve fine at runtime when
the app passes catalog/schema as statement context — therefore failed at
typegen time with TABLE_OR_VIEW_NOT_FOUND, and the generated types silently
degraded to `result: unknown`.

Thread an optional catalog/schema through the typegen path so DESCRIBE runs
with the same session context the runtime uses:

- vite-plugin reads DATABRICKS_CATALOG / DATABRICKS_SCHEMA from env (next to
  the existing DATABRICKS_WAREHOUSE_ID) and forwards them.
- generateFromEntryPoint -> generateQueriesFromDescribe -> describeAdaptive
  carry the optional context down to executeStatement, which honors top-level
  catalog/schema as the equivalent of USE CATALOG / USE SCHEMA for that one
  statement.

Fully backward compatible: when the env vars are unset, no catalog/schema keys
are added to the request and behavior is unchanged. Adds describeAdaptive tests
covering both the forwarded-context and omitted-context (back-compat) paths.

Signed-off-by: Quentin Ambard <quentin.ambard@databricks.com>
@QuentinAmbard QuentinAmbard requested a review from a team as a code owner June 26, 2026 11:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant