Data Browser (Sidebar)

4. Data Browser (Sidebar)

The sidebar is your main entry for browsing and managing data. It is built from expandable / collapsible sections (an accordion). When content is long, the main sidebar area scrolls vertically; the scrollbar appears briefly while scrolling and stays out of the way otherwise.

4.1 Browse and Search Data Files

A search box sits at the bottom of the sidebar. After you type, filtering applies after a short pause (~0.5s) so the list is not recomputed on every keystroke; a small loading icon appears beside the input during the pause. Clearing the search restores the list immediately.

Filtering covers: local data files, cached tables, external connection schemas (connected sources load their schema in the background so you can search table names by keyword), and the sources and materialized tables inside MCP Sources. While searching, the summary rows and title counts all match the current, settled search term.

The number in parentheses beside the Data section title is a sum: local table count (Excel counts by sheet; when the sheet count is unknown it counts as 1) + cached table count + currently loaded external table count (only connections whose schema has loaded successfully). Right after you type a search, external connections may still be loading their schema, so the count may start lower and increase once loading finishes—this is normal and does not mean data is missing.

Main accordion sections, top to bottom:

• Workspace — Manage workspaces and saved persistent SQL tabs (the sidebar lists persist SQL tabs only, not markdown cache tabs; see §5.6).
• Projects — Manage projects and Plan / Report Markdown files; you can set display aliases (§11.2) or archive documents to the Archived docs area to keep the list tidy (§11.3).
• Data — In order: the Cached top-level node (cached tables listed beneath it; see Chapter 7), the local folder file tree, and the external connection schema tree. On the right of the title row: the Connections pill (connected count) and Refresh (a single action that rescans local files, refreshes the cache list, and re-fetches the schema of loaded connections).
• Tip: Collapsing the Data section does not clear loaded external tables. If a connection is disconnected (not in a successfully connected state), its tables may temporarily disappear from the sidebar; once reconnected you can expand it again, or press Refresh on the Data title row (which only re-fetches the structure of external connections that were previously loaded and are still connected).
• MCP Sources — Manage MCP sources and materialized tables (see §4.6).

Expand / collapse state is remembered per workspace; the Data sub-list sort preferences are also saved per workspace (as well as per local folder path and per external connection alias). Switching workspaces can give the sidebar a different layout (section collapse, width, and list sort).

Cached tables and local files refresh together via Refresh on the Data title row; the MCP Sources section still has its own refresh button.

List sorting (Data sub-lists):

Right-click a parent row or connection row → Sort by… to change the display order of the list beneath it. This sort only affects the sidebar display—it does not change DuckDB table names, show_tables, or query resolution; it is unrelated to "result table sorting" in Chapter 6.

After a sidebar search filter, results still follow your chosen sort. Excel sheet sub-lists stay ordered by sheet name, unaffected by file-level sorting.

[Image] Sidebar expanded, showing Workspace, Projects, Data (including external connections and Cached), MCP Sources

4.2 Excel Sheet Expand and Select

Excel files (.xls / .xlsx) appear expandable in the sidebar:

1. Click the expand arrow beside the Excel file.
2. The app automatically loads the names of all sheets in that workbook.
3. Click or double-click a specific sheet name to insert it into the editor.

Note: When querying an Excel file, you must specify a sheet. For example:

SELECT * FROM "report.xlsx"."Sheet1" LIMIT 10

4.3 Quick Insert Table Name into Editor

• Double-click a file name or cached table name in the sidebar to automatically insert the corresponding table name at the editor cursor (already wrapped in double quotes).

4.4 Right-Click Menu: SELECT First 100 Rows

Right-click a single data file, cached table, or Excel sheet and choose SELECT 100 rows. The app detects the file's column structure and inserts a SELECT ... LIMIT 100 query containing all column names into the editor.

To adjust the display order of the whole list, use Sort by… on the local folder row, the Cached parent row, or the external connection alias row (see §4.1 "List sorting").

[Image] Sidebar expanded, showing Workspace, Projects, Data (with Cached and external connections), MCP Sources

[Image] Right-click menu on a data file

4.5 External Database Connections

The Connections button on the right of the Data section title row manages external database connections.

Supported types:

• PostgreSQL
• MySQL
• SQLite

Create a connection:

1. Click Connections in the Data section.
2. In the dialog, choose the database type and fill in the connection details and alias. When the dialog is tall, a scrollbar appears so you can scroll within a fixed height.
3. Click Test Connection to verify first, then Connect to attach.

Connection state and limits:

• The connected count shows on the button (e.g. Connections (1)).
• If any connection is in an error state, the button shows a yellow warning.
• The Trial role allows at most 1 active connection at a time; exceeding it triggers a 402 upgrade prompt (message in English). A fresh desktop install usually shows Trial in the header until a formal license is activated, so a second connection hits this limit.

Errors when removing or reconnecting show as Toast notifications (the error text may be in English). Operations such as a remote disconnect can take a while—please wait for them to finish.

Browse external tables and insert SQL:

• After connecting, the Data section shows an external schema tree (alias -> schema -> table).
• Double-click a table name to insert a reference.
• Right-click the connection alias row and use Sort by… → Name to reorder tables within each schema group under that connection (see §4.1 "List sorting").
• Right-click a single table row and use SELECT 100 rows to quickly generate preview SQL.

Reference format:

-- PostgreSQL
SELECT * FROM pg_db.public.orders LIMIT 10;

-- MySQL / SQLite
SELECT * FROM my_db.orders LIMIT 10;

Cross-source JOIN example:

SELECT o.order_id, l.name
FROM sdb.main.orders o
JOIN "local.csv" l ON o.customer_id = l.customer_id;

4.6 MCP Sources (Materialized Data Sources)

The MCP Sources section manages MCP sources and materialized tables (for section position and operations, see §4.1). Source cards and sidebar aliases both provide Edit / Connect or Disconnect / Remove.

The built-in Agent and external Agents in Execute or Admin mode use the same MCP Source controls. Credentials are never shown again; creating, replacing, clearing credentials, or removing a source requires confirmation.

Manage sources:

1. Click the gear or ＋ on the right of the MCP Sources title row to open the management dialog.
2. On the left, Add MCP Source lets you configure:

• transport=stdio: enter the launch command (e.g. npx ...).
• transport=http: enter the URL, optional Token, and Headers JSON.

3. Click Test to test the connection first; results appear in a separate result dialog (JSON is copyable).
4. Click Add to add the source config only; the default state is disconnected.
5. Source cards on the right offer:

• Edit: the alias is immutable; command, token, and headers are not shown again—explicitly preserve, replace, or clear them.
• Connect / Disconnect: HTTP Connect validates the endpoint first.
• Remove: choose Keep data to remove only the configuration, or Clear data to remove configuration and materialized tables.

Saving an edit returns the source to disconnected; connect it again afterwards.

Import from another workspace: In the Existing Sources header, choose Import from other workspaces. Select a source workspace, add sources to the import list, optionally rename their aliases, then confirm. It copies source settings only—never materialized data, download cache, or secrets—and imported sources start disconnected.

States:

• connected: connection available
• disconnected: configured but not yet connected
• error: the last reconnect/test failed (see the card message for the error)
• unbound (sidebar only): configuration was removed while materialized tables remain; remove it again to delete those tables

After an app restart or returning to a workspace, each source that was previously connected gets one automatic reconnect attempt. A source explicitly disconnected by the user is not retried. When a source is disconnected or error, a yellow warning icon appears beside its name in the sidebar.

Sidebar controls:

• Right-click the MCP source row (the alias parent row, not its materialized tables) and choose Edit, Connect / Disconnect, or Remove. Unbound rows offer only Remove.
• Success or failure shows a Toast; duplicate actions are temporarily disabled while running.

Start in Chat guidance:

• When a source has no materialized tables yet, click Start in Chat.
• Choosing Scan Source automatically opens the AI panel, creates a new conversation, and fills in an exploration prompt.
• Choosing Skip fills in no prompt.

Using materialized tables:

• After the Agent finishes pulling data, the table appears in the MCP Sources section.
• SQL can reference mcp_alias__table directly (the system maps it to the corresponding Parquet file at execution time).
• Right-click a materialized table row for SELECT 100 rows, Agent Refresh, View details, or Delete.
• Agent Refresh supplies a redacted refresh contract to the Agent. It must obtain a new, current write ID and use mcp_pull_table; it never reuses an old task, URL, or result handle. In external-Agent mode, Agent Refresh copies this handoff instead, while Add to chat becomes Copy table name.