Skip to content

fix: Mosaic table references for memory-backed datasets - #774

Merged
ilyabo merged 2 commits into
mainfrom
implement-mosaic-table-fix
Jun 28, 2026
Merged

ilyabo merged 2 commits into
mainfrom
implement-mosaic-table-fix

Conversation

@ilyabo

@ilyabo ilyabo commented Jun 28, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • Normalize dashboard, chart, and explorer table selection to use stable SQLRooms identities instead of leaking the memory catalog.
  • Split Mosaic table-reference helpers into execution, raw SQL, and vgplot-friendly forms so queries keep working across DuckDB WASM and serialized specs.
  • Update dashboard and block-document flows to resolve selected tables from the live table list before storing or rendering them.
  • Add coverage for catalog stripping, dotted identifiers, and ambiguous legacy table-name resolution.

Testing

  • Added and updated unit tests for table-reference resolution, data-table explorer query generation, and line-chart spec generation.
  • Not run (not requested).

Summary by CodeRabbit

  • New Features
    • Improved table identity resolution for charts, dashboards, and data-table explorers, keeping the selected table consistent across the UI.
    • Cleaner table-reference formatting for chart/SQL outputs, omitting catalog details when appropriate.
  • Bug Fixes
    • Fixed handling of DuckDB “memory” table identities and ensured generated references don’t include those catalog parts.
    • Improved correctness for quoted and dotted identifiers, plus safer behavior when table names are ambiguous.
  • Tests
    • Added/updated unit tests covering reference normalization and selection behavior.

@coderabbitai

coderabbitai Bot commented Jun 28, 2026 •

Copy link
Copy Markdown
Contributor

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e446edb0-455c-4525-82c3-c99be6f2a103

📥 Commits

Reviewing files that changed from the base of the PR and between bfe301b and a12804d.

📒 Files selected for processing (6)
  • packages/mosaic/__tests__/dashboard-ai-tools.test.ts
  • packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts
  • packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts
  • packages/mosaic/src/ai/dashboard/createDashboardChartTools.ts
  • packages/mosaic/src/ai/dashboard/createDashboardDataTableExplorerTool.ts
  • packages/mosaic/src/mosaicTableReference.ts
🚧 Files skipped from review as they are similar to previous changes (5)
  • packages/mosaic/src/ai/dashboard/createDashboardDataTableExplorerTool.ts
  • packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts
  • packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts
  • packages/mosaic/src/ai/dashboard/createDashboardChartTools.ts
  • packages/mosaic/src/mosaicTableReference.ts

📝 Walkthrough

Walkthrough

Adds catalog-aware table-reference helpers and threads canonical Mosaic table identities through chart SQL, dashboard selection, AI tool flows, and tests. The new behavior omits DuckDB "memory" from execution references while preserving it in persisted identities.

Changes

Mosaic table reference normalization

Layer / File(s) Summary
Core table reference helpers
packages/mosaic/src/mosaicTableReference.ts
Adds vgplot and raw SQL table-reference helpers, catalog-aware resolution, and a deprecated alias for the old string API.
Chart and explorer SQL references
packages/mosaic/src/charts/chart-types/base-types.ts, packages/mosaic/src/charts/chart-types/box-plot/renderer/BoxPlotClient.ts, packages/mosaic/src/data-table-explorer/useDataTableExplorer.ts, packages/mosaic/__tests__/chart-types/line-chart-spec.test.ts, packages/mosaic/__tests__/data-table-explorer.utils.test.ts
Updates chart and data-table explorer query builders to use vgplot-specific or raw SQL table references, with tests covering catalog-free output.
Dashboard table resolution
packages/mosaic/src/charts/dashboard/MosaicDashboardChartRenderer.tsx, packages/mosaic/src/dashboard/panel/MosaicDashboardPanels.tsx, packages/mosaic/src/dashboard/toolbar/MosaicDashboardDataTableSelector.tsx, packages/mosaic/src/dashboard/toolbar/MosaicDashboardToolbar.tsx, packages/mosaic/src/dashboard/useSelectedOrFirstTable.ts, packages/mosaic/src/data-table-explorer/dashboard/MosaicDashboardDataTableExplorerPanelRenderer.tsx
Replaces direct table lookup hooks with catalog-aware resolution in dashboard renderers, selectors, toolbars, and selection hooks, and stores canonical table identities on change.
AI tools store canonical table identities
packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts, packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts, packages/mosaic/src/ai/dashboard/createDashboardAgentTool.ts, packages/mosaic/src/ai/dashboard/createDashboardChartTools.ts, packages/mosaic/src/ai/dashboard/createDashboardDataTableExplorerTool.ts
Changes block-document and dashboard AI tools to resolve tableName through the adapter, derive getMosaicTableIdentity, and pass canonical identities into selection and block creation paths.
Reference normalization tests
packages/mosaic/__tests__/mosaicTableReference.test.ts, packages/mosaic/__tests__/dashboard-ai-tools.test.ts
Adds tests covering vgplot/raw SQL reference generation, catalog omission, ambiguous resolution handling, and dashboard AI selection expectations.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

  • sqlrooms/sqlrooms#683: Touches chart table-reference handling and getChartTableReference, which this PR also changes in the chart SQL reference path.
  • sqlrooms/sqlrooms#731: Directly related — updates the same table-reference helpers and downstream chart/data-table-explorer SQL generation for catalog identity handling.
  • sqlrooms/sqlrooms#736: Modifies the same createDashboardChartTools.ts addChart flow that this PR updates to use canonical table identity.

Suggested reviewers

  • dmitriy-kostianetskiy
  • lixun910

🐇 Hop, hop, the catalog got light,
"memory" slipped off into the night.
"main"."events" now shines so neat,
with identities canonical and sweet.
🥕 A tidy burrow for SQL delight!

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: fixing Mosaic table references for memory-backed datasets.
Docstring Coverage ✅ Passed Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch implement-mosaic-table-fix

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (2)
packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts (1)

41-57: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Normalize the fallback table identity too.

If findTable() misses, the raw tableName is stored unchanged, so whitespace-only or padded names bypass the canonical identity path.

Proposed fix
     addChart: ({config, tableName, title}) => {
-      if (!tableName) {
+      const requestedTableIdentity = getMosaicTableIdentity(tableName ?? '');
+      if (!requestedTableIdentity) {
         throw new Error(
           'tableName is required for block document chart blocks but was empty or undefined',
         );
       }
 
-      const resolvedTable = databaseAdapter.findTable(tableName);
+      const resolvedTable = databaseAdapter.findTable(requestedTableIdentity);
       const tableIdentity = resolvedTable?.table
         ? getMosaicTableIdentity(resolvedTable.table)
-        : tableName;
+        : requestedTableIdentity;
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts`
around lines 41 - 57, The fallback table identity in addChart is not normalized
when databaseAdapter.findTable() returns nothing, so padded or whitespace-only
names can be stored as-is. Update createBlockDocumentChartTools’s addChart logic
so the tableName fallback goes through the same normalization/canonicalization
path as resolvedTable.table, using getMosaicTableIdentity or equivalent
normalization before passing tableName into blockDocumentAdapter.addBlock.
packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts (1)

49-76: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Normalize the fallback table identity before storing it.

When resolution fails, this persists the original tableName, skipping the trimming/canonicalization that getMosaicTableIdentity provides.

Proposed fix
     databaseAdapter,
     addDataTable: async ({title, tableName, intent}) => {
-      if (!tableName) {
+      const requestedTableIdentity = getMosaicTableIdentity(tableName ?? '');
+      if (!requestedTableIdentity) {
         throw new Error(
           'Table name is required to add a data table explorer block',
         );
       }
 
       blockDocumentAdapter.ensureBlockDocument(blockDocumentId);
-      const resolvedTable = databaseAdapter.findTable(tableName);
+      const resolvedTable = databaseAdapter.findTable(requestedTableIdentity);
       const tableIdentity = resolvedTable?.table
         ? getMosaicTableIdentity(resolvedTable.table)
-        : tableName;
+        : requestedTableIdentity;
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In
`@packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts`
around lines 49 - 76, The fallback table identity in addDataTable should be
normalized before it is stored, because the current resolvedTable?.table ?
getMosaicTableIdentity(...) : tableName path skips canonicalization when lookup
fails. Update createBlockDocumentDataTableExplorerTool so the tableName fallback
also goes through getMosaicTableIdentity (or equivalent normalization logic)
before passing it to addDataTableExplorerBlock, createDataTableExplorerBlock,
and blockDocumentAdapter.addBlock.
🧹 Nitpick comments (1)
packages/mosaic/src/mosaicTableReference.ts (1)

10-11: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add TSDoc for the new exported types.

MosaicTableReferenceInput and MosaicTableReferenceCandidate are new public exports, but they ship undocumented while the surrounding helpers are documented. Please add brief TSDoc so consumers can distinguish persisted identities from runtime candidates. As per coding guidelines, packages/**/*.{ts,tsx}: Add tsdoc to exported types and functions in @sqlrooms/* packages.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/mosaic/src/mosaicTableReference.ts` around lines 10 - 11, Add brief
TSDoc comments to the new public exported types `MosaicTableReferenceInput` and
`MosaicTableReferenceCandidate` in `mosaicTableReference.ts`. Document that
`MosaicTableReferenceInput` accepts either a string or `QualifiedTableName`, and
that `MosaicTableReferenceCandidate` represents a runtime object containing a
`table: QualifiedTableName`, so consumers can distinguish persisted identities
from runtime candidates.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/mosaic/src/ai/dashboard/createDashboardChartTools.ts`:
- Around line 48-57: The selectedTable value is being persisted with a raw
tableName fallback when databaseAdapter.findTable(tableName) misses, which
leaves dashboard state non-canonical. Update createDashboardChartTools so it
only writes a resolved table reference, using ensureTable(...) from tool-helpers
or otherwise skipping dashboardAdapter.setSelectedTable when no table is found.
Keep the change centered on the selectedTableIdentity resolution logic so the
dashboard toolbar, selector, and chart renderer can continue resolving through
resolveMosaicTableReference(...).table.

In `@packages/mosaic/src/ai/dashboard/createDashboardDataTableExplorerTool.ts`:
- Around line 34-44: The addDataTable flow in
createDashboardDataTableExplorerTool should not persist an unresolved raw
tableName into dashboardAdapter.setSelectedTable. Update the addDataTable
handler to fail fast with ensureTable(...) when
databaseAdapter.findTable(tableName) does not resolve, or otherwise preserve the
existing selection instead of overwriting it with the unresolved string. Keep
the fix localized to the addDataTable logic and use the existing
dashboardAdapter and databaseAdapter symbols to locate the change.

---

Outside diff comments:
In `@packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts`:
- Around line 41-57: The fallback table identity in addChart is not normalized
when databaseAdapter.findTable() returns nothing, so padded or whitespace-only
names can be stored as-is. Update createBlockDocumentChartTools’s addChart logic
so the tableName fallback goes through the same normalization/canonicalization
path as resolvedTable.table, using getMosaicTableIdentity or equivalent
normalization before passing tableName into blockDocumentAdapter.addBlock.

In
`@packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts`:
- Around line 49-76: The fallback table identity in addDataTable should be
normalized before it is stored, because the current resolvedTable?.table ?
getMosaicTableIdentity(...) : tableName path skips canonicalization when lookup
fails. Update createBlockDocumentDataTableExplorerTool so the tableName fallback
also goes through getMosaicTableIdentity (or equivalent normalization logic)
before passing it to addDataTableExplorerBlock, createDataTableExplorerBlock,
and blockDocumentAdapter.addBlock.

---

Nitpick comments:
In `@packages/mosaic/src/mosaicTableReference.ts`:
- Around line 10-11: Add brief TSDoc comments to the new public exported types
`MosaicTableReferenceInput` and `MosaicTableReferenceCandidate` in
`mosaicTableReference.ts`. Document that `MosaicTableReferenceInput` accepts
either a string or `QualifiedTableName`, and that
`MosaicTableReferenceCandidate` represents a runtime object containing a `table:
QualifiedTableName`, so consumers can distinguish persisted identities from
runtime candidates.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 921e4396-7714-4e63-a2cb-e50b667b8a56

📥 Commits

Reviewing files that changed from the base of the PR and between 8648895 and bfe301b.

📒 Files selected for processing (18)
  • packages/mosaic/__tests__/chart-types/line-chart-spec.test.ts
  • packages/mosaic/__tests__/data-table-explorer.utils.test.ts
  • packages/mosaic/__tests__/mosaicTableReference.test.ts
  • packages/mosaic/src/ai/block-document/createBlockDocumentChartTools.ts
  • packages/mosaic/src/ai/block-document/createBlockDocumentDataTableExplorerTool.ts
  • packages/mosaic/src/ai/dashboard/createDashboardAgentTool.ts
  • packages/mosaic/src/ai/dashboard/createDashboardChartTools.ts
  • packages/mosaic/src/ai/dashboard/createDashboardDataTableExplorerTool.ts
  • packages/mosaic/src/charts/chart-types/base-types.ts
  • packages/mosaic/src/charts/chart-types/box-plot/renderer/BoxPlotClient.ts
  • packages/mosaic/src/charts/dashboard/MosaicDashboardChartRenderer.tsx
  • packages/mosaic/src/dashboard/panel/MosaicDashboardPanels.tsx
  • packages/mosaic/src/dashboard/toolbar/MosaicDashboardDataTableSelector.tsx
  • packages/mosaic/src/dashboard/toolbar/MosaicDashboardToolbar.tsx
  • packages/mosaic/src/dashboard/useSelectedOrFirstTable.ts
  • packages/mosaic/src/data-table-explorer/dashboard/MosaicDashboardDataTableExplorerPanelRenderer.tsx
  • packages/mosaic/src/data-table-explorer/useDataTableExplorer.ts
  • packages/mosaic/src/mosaicTableReference.ts

Comment thread packages/mosaic/src/ai/dashboard/createDashboardChartTools.ts Outdated

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bfe301bdfb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +55 to +57
if (selectedTableIdentity) {
await dashboardAdapter.setSelectedTable(selectedTableIdentity);
}

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Move table selection after panel validation

When a chart tool call includes a tableName and a stale or non-chart panelId, this mutates the dashboard's selected table before the panel existence/type checks below throw. The tool then reports failure without updating any panel, but existing dashboard panels have already switched datasets; keep this mutation after the panelId validation succeeds, or roll it back on validation failure.

Useful? React with 👍 / 👎.

@ilyabo
ilyabo merged commit f7b7a2e into main Jun 28, 2026
4 checks passed
@ilyabo
ilyabo deleted the implement-mosaic-table-fix branch June 28, 2026 14:58
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