資料瀏覽器（側邊欄）

4. 資料瀏覽器（側邊欄）

側邊欄是你瀏覽和管理資料的主要入口，由多個可展開／收合的區塊（手風琴）組成。內容較長時，側邊欄主區域可垂直捲動；捲動時捲軸會短暫顯示，平時盡量不干擾閱讀。

4.1 瀏覽與搜尋資料檔案

側邊欄底部有搜尋框。輸入後會稍作停頓（約 0.5 秒）再套用過濾，避免每打一個字就重算；停頓期間輸入框旁會出現小載入圖示。清空搜尋會立即還原列表。

過濾範圍包含：本地資料檔案、快取表、外部連線 schema（已連線者會在背景載入 schema 以便用關鍵字搜表名）、以及 MCP Sources 內的來源與物化表。搜尋狀態下，摘要列與標題上的數字皆與目前穩定後的搜尋字一致。

Data 區塊標題旁括號內的數字為加總：本地表數（Excel 依工作表數；未知工作表數時先計 1）+ 快取表數 + 目前載入的外部表數（僅統計已成功載入 schema 的連線）。在輸入搜尋後，外部連線可能尚在載入 schema，數字可能先較少、載入完成後再增加——屬正常現象，不代表資料遺失。

主手風琴區塊由上而下為：

• Workspace — 管理工作區與已儲存的 SQL 持久分頁（側欄僅列出 persist SQL tab，不含 markdown 快取 tab；見 §5.6）。
• Projects — 管理專案與 Plan / Report Markdown 檔案，並可設定顯示別名（§11.2）或將文件封存至 Archived docs 區以保持列表簡潔（§11.3）。
• Data — 依序包含：Cached 一級節點（快取表列於其下；見第 7 章）、初始資料夾檔案樹、以及經 Connections 掛載且目前可查詢的來源（資料庫 schema 樹、connected 的外部 DB；Additional folder 為 available；Cloud folder 為 available 或 degraded）。Disconnect 後的來源僅在 Connections 對話框可見，不會出現在 Data 樹中。標題列右側：Connections 膠囊（Link2 數字 = 所有已連線／已掛載來源：外部 DB connected + folder available + cloud available／degraded，不含 MCP 與 offline 綁定）、Refresh（一次重新掃描本地檔案與額外文件夾、刷新快取列表、並對已載入的連線重新抓取 schema）。v1 不會自動監聽檔案系統變更，新增檔案後請按 Refresh。
• 提示： 收合 Data 區不會清掉已載入的外部資料表。若外部 DB 未連線（disconnected／error 等），側邊欄不顯示該 alias 的 schema 樹；請到 Connections 對該來源按 Connect（或 Edit 修正設定後 Save），再視需要按 Data → Refresh 重抓 schema。
• MCP Sources — 管理 MCP 來源與物化表（詳見 §4.6）。

各區塊的展開／收合狀態會依工作區分別記住；Data 子列表的排序偏好亦會依工作區（以及本地資料夾路徑、各外部連線 alias）分別保存。切換工作區時，側邊欄版面（含各區收合、寬度與列表排序）可各自不同。

快取表與本地檔案的重新整理可由 Data 標題列的 Refresh 一次完成；MCP Sources 區塊仍有獨立的重新整理按鈕。

列表排序（Data 子列表）：

在下列父列或連線列上右鍵 → Sort by…，可調整其下清單的顯示順序。此排序僅影響側邊欄顯示，不改變 DuckDB 表名、show_tables 或查詢解析；與第 6 章「結果表格排序」無關。

側邊欄搜尋過濾後，結果仍依你選的排序顯示。Excel 工作表子列表維持依工作表名稱排列，不受檔案層排序影響。

[圖片] 側邊欄展開狀態，顯示 Workspace、Projects、Data（含外部連線與 Cached）、MCP Sources 等各區塊

4.2 Excel 工作表展開與選擇

Excel 檔案（.xls / .xlsx）在側邊欄中會以可展開的方式呈現：

1. 點擊 Excel 檔案旁的展開箭頭。
2. 系統會自動載入該活頁簿中所有工作表的名稱。
3. 你可以點擊或雙擊特定工作表名稱，將它插入到編輯器中。

注意： 查詢 Excel 檔案時，必須指定工作表。例如：

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

4.3 快速插入表名到編輯器

• 雙擊側邊欄中的檔案名稱或快取表名稱，即可自動在編輯器的游標位置插入對應的表名（已自動加上雙引號）。

4.4 右鍵選單：SELECT 前 100 筆

在單一資料檔案、快取表或 Excel 工作表上按右鍵，選擇「SELECT 100 rows」，系統會自動偵測該檔案的欄位結構，並在編輯器中插入一條包含所有欄位名稱的 SELECT ... LIMIT 100 查詢語句。

若要調整整份列表的顯示順序，請在本地資料夾列、Cached 父列或外部連線 alias 列上使用 Sort by…（見 §4.1「列表排序」）。

[圖片] 側邊欄展開狀態，顯示 Workspace、Projects、Data（含 Cached 與外部連線）、MCP Sources 等各區塊

[圖片] 資料檔案的右鍵選單

4.5 資料源與連線（Connections）

Data 區段標題列右側有 Connections 按鈕，可管理本工作區的資料源：常見資料庫、額外本機資料夾、Cloud folder 與 SQL Server／Azure SQL。初始資料夾仍由 Data 區本機資料夾列管理（見 §2.2、§3.2），不經此對話框建立。

Source Type：

完整開放： 所有資料來源可建立、測試、連線與重連，外部資料庫沒有產品設定的同時連線數上限；Header 不顯示方案或升級入口。

建立資料源：

1. 點擊 Data 區段的 Connections。
2. 選擇 Source Type 與唯一的 Alias（與初始資料夾語意、其他連線、MCP alias 不得衝突）。視窗內容較多時會出現捲軸。
3. 依類型填寫：資料庫連線資訊、Additional folder 的 Browse 路徑、Cloud folder 的 provider／bucket／prefix／credential，或 SQL Server／Azure SQL 的 Server／Database／帳密等。
4. 資料庫類型：先 Test Connection，再 Connect。Additional folder：確認路徑後掛載即可。Cloud folder：可先 Test connection，再 Add Cloud Folder（Add 時也會 list／驗證）。

Additional folder：

• 工作區須先綁定初始資料夾，才能新增 Additional folder（空工作區請先完成 §2.2 或 §3.2）。
• 支援與初始資料夾相同的常見格式（CSV／TSV／TXT／Parquet／JSON／JSONL／Excel .xlsx 等）。
• 引用："alias"."file.csv"；子路徑："alias"."subdir/orders.csv"；Excel："alias"."book.xlsx"."Sheet1"。
• 檔案不會被搬移或刪除；新增檔後請按 Data → Refresh（無自動 filesystem watcher）。
• 側邊欄 Additional folder alias 列右鍵可 Edit、Connect、Disconnect（英文選單）；Connect 會重新掃描索引並掛載，無須到 Connections 找 Refresh 按鈕。
• Additional folder 提供獨立 alias、Connect／Disconnect 與可攜管理；不是本機檔案 DRM（仍可自行改初始資料夾指向等方式讀多路徑）。

Cloud folder：

• 支援 Amazon S3、Alibaba Cloud OSS、ADLS Gen2、Azure Blob，以及已 OS 掛載的 Azure Files 路徑。
• 引用格式與 Additional folder 相同："alias"."file.parquet"、"alias"."subdir/orders.csv"、"alias"."book.xlsx"."Sheet1"。
• Credential 存於 OS vault；Remove 只解綁 Lantide，不刪除雲端物件。匯出工作區預設不含雲端 physical data，匯入後需 Edit／重填 credential 並 Connect。
• 遠端檔案建議優先使用 Parquet；Connect 會重新 list prefix 下物件並建索引（有硬上限，避免掃描整桶）。若 Sidebar 展開後提示需索引，請到 Connections 或側邊欄右鍵對該 alias Connect。
• 側邊欄 Cloud folder alias 列右鍵可 Edit、Connect、Disconnect（英文選單）。
• ADLS Gen2／Azure Blob 表單可用 Autofill from SAS URL 貼上 Azure SAS 連結，拆出 account／container／token（原始 URL 不會存檔）。
• Add 前可選 Test connection（list 驗證）；Add 仍可直接提交。Sidebar Select 100 rows 走 POST /api_v1/probe/describe（與本機／Additional folder 相同），不經 /query。

SQL Server / Azure SQL：

• 本機須安裝 Microsoft ODBC Driver 18；App 會偵測並提供安裝指引（含 Detect again、Open installation guide）。偵測通過後即可填寫連線。
• Deployment 可選 SQL Server 或 Azure SQL；Authentication 為 SQL login（v1 不支援 Entra／Azure AD）。可用 Autofill from connection string 貼上連線字串填入欄位（原始字串不會存檔）。
• 連線成功後密碼存於 OS vault（macOS Keychain／Windows Credential Manager）。
• 查詢為 read-only（SELECT／CTE）。SQL 須為 DuckDB 相容語法；表引用格式為 "alias"."schema"."object"（或省略 schema 時 "alias"."object"）。系統會將可下推的篩選／聚合轉為 T-SQL 在遠端執行，其餘在本機處理。
• ODBC staged 跨源規則（與 ATTACH 原生 DB 不同）： PostgreSQL／MySQL／SQLite 經 DuckDB ATTACH 後，可與本機檔案在同一 SQL 中 JOIN。SQL Server 不 ATTACH；每條遠端查詢須單源（僅引用該 alias），先在遠端篩選／聚合並物化為本機 cache，再與本地檔案、其他 cache 或已 ATTACH 的 DB 做第二步 JOIN。不支援在單一 statement 中對 SQL Server 與其他來源做透明跨源 JOIN。
• 大結果 preflight： 當遠端優化器估計結果超過 500,000 列 時，Agent 的 validate_query 或 run_query 會回傳需確認的警告（含 warning_id）。Agent 應先 ask_user，你同意後再以 large_remote_warning_id 重試。若無法取得估計值，可能仍執行但附 REMOTE_ESTIMATE_UNAVAILABLE 軟警告——此時 Agent 應收斂篩選或再次請你確認。

連線狀態：

• Link2 旁數字 = 所有已連線／已掛載來源（外部 DB + Additional folder + Cloud folder），非僅 DB 條數。
• 若任何外部 DB 為 error，Connections 按鈕會顯示黃色警示（MCP 斷線仍走 §4.6 黃標，不計入此數字）。
• 常見狀態：connected（DB 已 ATTACH）、available（folder 已掛載）、degraded（cloud 可用但索引可能不完整）、disconnected（使用者主動 Disconnect，僅 Connections 可見）、error／missing 等。
• 移除、斷連或改綁若會影響 SQL 分頁引用，系統會先顯示 impact 確認（列出引用 tab 數；必要時須勾選確認）。

管理現有連線（Connections 對話框右側卡片）：

每筆 DB／Additional folder／Cloud folder 綁定有三個圖示（英文 tooltip）：

從其他工作區匯入（Import from other workspaces）：

• 在 Existing Connections 標題列右側點 ☰，選 Import from other workspaces。
• 開啟第二層對話框：左側 From 選來源工作區並瀏覽連線卡片；點 → 將綁定加入右側 To 待匯入清單（可跨多個工作區累積）。
• 右側可 ✎ 修改匯入後的 alias，或 × 移除該筆；若 alias 與本工作區既有名稱衝突，Confirm 會整批擋下並提示改名。
• Confirm 後才複製設定至目前工作區；不會切換工作區、不會改動來源工作區，也不會自動 Connect。新匯入的 DB／folder／cloud 皆為 disconnected，請在卡片上按 Connect 後再查詢。

瀏覽與插入 SQL：

• 資料庫連線成功後，Data 區出現 schema 樹（alias -> schema -> table）。Additional folder 以該 alias 下列出可查檔案。
• 雙擊表名／檔名可插入引用；右鍵可用「SELECT 100 rows」。
• 在連線 alias 列右鍵可用 Sort by… → Name（見 §4.1）。

引用格式：

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

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

-- Additional folder
SELECT * FROM "sales_drop"."orders.csv" LIMIT 10;

跨源 JOIN 範例（本地／cache／已 ATTACH 的原生 DB）：

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（物化數據源）

MCP Sources 區段用於管理 MCP 來源與已物化表（區塊位置與操作請參考 §4.1）。MCP 仍維持獨立管理對話框，但來源卡片與 Sidebar alias 右鍵現在同樣提供 Edit／Connect 或 Disconnect／Remove。

內建 Agent 與外部 Agent（Execute／Admin） 也可透過 MCP source 控制工具管理同一組來源設定（mcp_upsert_source、mcp_connect_source、mcp_test_source 等）。憑證永不回顯；新增、替換或清除憑證與 Remove 需先取得你的確認。Sidebar 會在 Agent 變更來源後自動刷新。

管理來源：

1. 點擊 MCP Sources 標題列右側的 齒輪 或 ＋，開啟管理對話框。
2. 左側 Add MCP Source 可設定：

• transport=stdio：填入啟動命令（如 npx ...）。
• transport=http：填入 URL、可選 Token 與 Headers JSON。

3. 點擊 Test 先測試連線；結果會顯示在獨立結果彈窗（可複製 JSON）。
4. 點擊 Add 僅加入來源設定；不論 stdio 或 HTTP，初始狀態皆為 disconnected。
5. 右側來源卡片可用：

• Edit icon：編輯來源；alias 不可改。command、token、headers 不會回顯，請選擇保留、替換或清除。
• Connect／Disconnect icon：連線或停止目前 runtime；HTTP 的 Connect 會先驗證 endpoint。
• Remove icon：先選擇 Keep data（僅移除連線設定，物化表保留）或 Clear data（連線與物化表一併刪除）；進行中的 MCP operation 會取消。

編輯並儲存後不會自動連線，會回到 disconnected，請再按 Connect。切換 stdio / HTTP 時需明確確認，且原 transport 的 credentials 會清除。

從其他工作區匯入（Import from other workspaces）：

• 在 Existing Sources 標題列右側點 ☰，選 Import from other workspaces。
• 左側選來源工作區並點來源卡片上的 → 加入右側待匯入清單；右側可改 alias 或移除項目。
• Confirm 後複製 MCP 來源設定至目前工作區（不含物化表與下載快取）；匯入後為 disconnected，請再按 Connect。

狀態說明：

• connected：連線可用
• disconnected：已設定但尚未連線
• error：最近一次重連/測試失敗（可從卡片訊息查看錯誤）
• unbound（僅側邊欄）：連線設定已移除但物化表仍在；父列圖示為 CloudOff，右鍵僅 Remove；管理對話框不顯示此列

重啟 App 或切換回工作區時，系統會對先前已 Connect 的來源各自動嘗試重連一輪；若遠端暫時不可用，來源會顯示 error，你可稍後再手動 Connect。若你曾主動 Disconnect，該來源不會在重啟後自動重連。編輯並 Save 後當次仍不會自動連線。

當來源為 disconnected 或 error 時，側邊欄來源名稱旁會顯示黃色警示圖示；將滑鼠移上去可查看錯誤摘要。

側邊欄來源控制：

• 在 MCP 來源列（alias 父行，非底下的物化表列）上按右鍵，可選擇 Edit、Connect／Disconnect 或 Remove（已移除連線、僅剩資料的 unbound 列僅 Remove）。
• 成功或失敗皆會以 Toast 通知；同一來源操作進行中會暫時停用重複操作。
• Remove 會跳出 Keep data／Clear data／Cancel：Keep 只刪連線設定，側邊欄仍顯示同 alias 的 unbound 列且 SQL 仍可查；Clear 連線與物化表一併刪除。unbound 列再 Remove 則清掉剩餘物化表並從側邊欄消失。
• 單表刪除請在物化表列右鍵選擇 Delete。

Start in Chat 引導：

• 當來源尚未有物化表時，可點 Start in Chat。
• 選擇 Scan Source 時，系統會自動開啟 AI 面板、建立新對話並填入探索提示。
• 選擇 Skip 時，不會填入任何提示。

物化表使用方式：

• Agent 拉取完成後，表會出現在 MCP Sources 區段。
• SQL 可直接引用 mcp_alias__table（系統會在執行期映射到對應 Parquet 檔案）。
• 在物化表列上按右鍵，可進行 SELECT 100 rows（插入 LIMIT 100 預覽查詢）、Agent Refresh（unbound 來源無此項）、View details、Delete。
• View details 會顯示脫敏後的 Pull contract（來源工具、流程與查詢），可用來理解或重建表；它不是短效 batch／task ID 或下載 URL。
• Agent Refresh 會將 canonical mcp_table_info 送到聊天。Agent 依目前來源 schema 重新完成 submit／status／fetch；取得本輪 ready write ID 後，以 mcp_pull_table 安全覆寫本地表（inline／builtin download 用 mcp_result_id；自訂 download 配方 validate 後用 normalization_id）。系統不會重用歷史 task、batch、URL 或其他短效 handle，也不會從後端自動重播遠端流程。有效 write ID 存活期間請勿再次 fetch，以免舊 ID 作廢。
• 當 External agent mode（Execute／Admin 外部工作階段）啟用、內建 Agent 暫停時，Agent Refresh 改為複製含完整 refresh 契約的 GUI handoff 到剪貼簿，供貼到外部 agent；Add to chat 在資料表列上改為 Copy table name（複製 SQL 可用的 quoted identifier）。
• 若來源仍在處理中，請讓 Agent 依該來源的工具契約繼續確認狀態；關閉或中斷對話後，重新從表的 Agent Refresh 或新的查詢開始。並行 Refresh 遇到資料已更新時不會覆蓋較新的表，請先查看最新 details 再決定是否重跑。
• 在**來源列（alias 父行）**上按右鍵，可選擇 Edit、Connect／Disconnect 或 Remove（見上文「側邊欄來源控制」）。