18. 常見問題（FAQ）
為什麼查詢結果最多只顯示 500 筆？
畫面中的結果預覽限制為 500 筆，這是為了保持介面流暢。如果你需要完整的查詢結果，請使用匯出功能將資料儲存為檔案，匯出不受此限制。Result Panel 的 Copy for Excel/Spreadsheet 同樣最多複製畫面上的 500 列（見 §6.5）。
Agent 與 Ask 有什麼差別？為什麼不能改我的 Plan？
聊天輸入區的 Agent 可寫入 Plan／Report／HTML／SQL 正文；Ask 只回答與跑查詢，不改這些產物。若 Agent「不肯改檔」，請確認是否停在 Ask——切回 Agent 再送一次。Ask 不是 MCP 的 Observe（Observe 只約束外部連線）。見 §12.1.1。
為什麼我的 Excel 檔案無法直接查詢？
查詢 Excel 檔案時，必須指定工作表名稱。正確的寫法是：
SELECT * FROM "檔案名稱.xlsx"."工作表名稱"
你可以在側邊欄展開 Excel 檔案，查看並選取工作表名稱。
為什麼匯出不支援 .json 格式？
Lantide Data 使用 .jsonl（JSON Lines）格式替代 .json。JSON Lines 格式每行一筆資料，更適合大量資料的讀寫。匯出時將副檔名改為 .jsonl 即可。
可以執行 INSERT、UPDATE 等寫入操作嗎？
不可以。Lantide Data 僅支援唯讀查詢，包括 SELECT、DESCRIBE、SHOW、PRAGMA。這是為了保護你的原始資料不被意外修改。
快取表在什麼時候會消失？
快取表會在以下情況被清除：
- 切換到另一個工作區時。
- 重新啟動應用程式時。
清除後，只要重新執行對應的持久分頁，即可重新產生快取表。
來源執行顯示錯誤「需要單一 SQL 語句」怎麼辦？
來源執行和血統分析要求每個分頁只包含一條 SQL 語句。請確認分頁中沒有多條以分號分隔的語句。如果你需要組合多個步驟，請將每個步驟放在獨立的分頁中，透過快取表串連。
我可以跨工作區查詢快取表嗎？
不可以。每個工作區的快取表是完全隔離的，你無法在工作區 A 中引用工作區 B 的快取表。
原因在於 Lantide Data 的快取機制是基於 DuckDB 的記憶體暫存表（Temp Table）實作的——每次切換工作區時，系統會先清除前一個工作區的所有暫存表，再載入新工作區的資料環境。因此，同一時間只有當前工作區的快取表存在於記憶體中。
如果你需要在不同工作區之間共用某份查詢結果，建議先將該結果匯出為檔案（例如 CSV 或 Parquet），然後在另一個工作區的資料目錄中載入該檔案。亦或是將需要分析的數據都放置在同一個工作區目錄下。
AI 建立的 SQL Tab 和我手動建立的有什麼不同？
沒有不同。AI 建立的 SQL Tab 與你手動建立的完全一致——它們是同樣的持久分頁（Persist Tab），儲存在工作區中，查詢結果同樣會物化為快取表。你可以在 AI 建立的 Tab 上繼續手動編輯、重新執行，或用來源執行串連上下游依賴。
AI 可以修改或刪除我的原始資料檔案嗎？
不可以。AI Agent 的所有操作都是唯讀的——它只能執行 SELECT 類查詢，無法透過 INSERT、UPDATE、DELETE 等語句修改你的原始資料。這個安全限制由後端的 SQL 驗證層強制執行，AI 無法繞過。
為什麼 PostgreSQL / MySQL 連線測試失敗（Connection refused）？
這通常表示本機沒有啟動對應資料庫服務，或主機/埠號設定不正確（例如 127.0.0.1:5432、127.0.0.1:3306）。
請依序檢查：
- 資料庫服務是否已啟動。
- host / port / database / username / password 是否正確。
- 本機防火牆與網路策略是否允許連線。
- 若是遠端資料庫，是否已將你的 IP 加入白名單。
如何連接 SQL Server / Azure SQL？
- 在 Connections 選擇 SQL Server / Azure SQL。本機需安裝 Microsoft ODBC Driver 18；若偵測失敗，對話框會顯示安裝指引（Copy commands／Open installation guide），裝好後按 Detect again。
- Trial 看得到 Pro 選項與說明，但無法填寫或提交；升級 Pro 後才能連線。Trial 的「1 條 active 外部 DB」限制仍適用於 SQL Server。
- 密碼在連線成功後存於 OS vault（Keychain／Credential Manager）。詳見 §4.5。
為什麼不能把 SQL Server 表和本地 CSV 寫在同一條 JOIN 裡直接跑？
SQL Server／Azure SQL 路徑會先在遠端完成篩選／聚合並物化為本機 cache，再與本地檔案或其他來源 JOIN。產品不支援單一 statement 的透明跨源 JOIN。請先取數物化，再對 cache／本地表寫 JOIN。
Additional folder 和「Change data folder」有什麼不同？
Change data folder 更換工作區的唯一初始資料夾。Additional folder 是經 Connections 掛上的額外本機根，有獨立 alias（如 "sales_drop"."orders.csv"），不搬移來源檔，也不取代初始資料夾。工作區須先綁定初始資料夾，才能新增 Additional folder。新增檔後請按 Data → Refresh（無自動監看）。這是受支援的多資料區工作流，不是檔案 DRM。
AI 面板的狀態指示器顯示的狀態和實際不一致？
極少情況下，前端計算的 Agent 狀態可能與後端不一致。此時以後端為準——後端的 State Router 決定 AI 可以使用哪些工具。你可以嘗試切換分頁或重新整理頁面來同步狀態。
AI 說「已建立 Tab」但我沒看到新分頁？
多數情況下，側邊欄工作區列表會在 Agent 建立持久分頁後即時更新。若編輯器分頁列仍未出現，可點擊側邊欄中對應的持久分頁重新開啟；仍缺漏時可切換工作區再切回，或重新載入頁面。
Agent 寫入 SQL 後為什麼沒有 * 號？
Agent 透過工具寫入的內容已直接落盤至工作區，分頁不會標示未儲存 *。只有你手動編輯後才會出現 *，關閉分頁時亦會照常提示儲存或捨棄（見 §5.2）。
對話裡 validate_query 和 run_query 有什麼差別？
validate_query 以 LIMIT 0 試跑 SQL，僅回傳成功或錯誤，不回傳資料列，適合探索與試錯。對 SQL Server／Azure SQL，若遠端估計超過 500,000 列，可能回傳 warning_required 與 warning_id，Agent 須先請你確認。run_query 執行查詢並回傳預覽，最多 200 行，供 Agent 分析取數；大結果須帶 large_remote_warning_id 重試。歷史對話若顯示舊工具名 test_query，僅為舊紀錄。詳見 §12.6、§4.5。
run_query 什麼時候會物化成快取表？
系統自動推斷，無需每次手動設 materialize=true。一般會物化的情况：對話中已有成功的查詢步驟（多步分析）、SQL 引用了既有快取表、或查詢較複雜（例如多表 JOIN、大量 CTE）。單表探索查詢（含 LIMIT、無 JOIN/GROUP）通常僅回傳預覽、不物化。若模型傳 materialize=false 但系統判定必須物化，仍會物化並在工具結果附 warnings 說明。詳見 §12.6 與 §7.4。
agent 快取和 persist 快取有什麼不同？
| 類型 | 來源 | Source Run | 查看 SQL |
|---|---|---|---|
| persist 快取 | 持久分頁執行（run_sql_tab / 手動 Run） |
支援 | 通常來自分頁 SQL |
| agent 快取 | 後台 run_query 條件物化 |
不支援 | 來自 registry / ledger |
兩者皆可在 Data → Cached 右鍵 查看 SQL、SELECT 100 rows 或於 SQL 中 FROM 引用（同一工作區內）。
查看 SQL 顯示「已不可用」怎麼辦？
表示系統無法從快取 registry、對話 ledger 或結果管理器還原該快取的 SQL（常見於舊版快取、重啟後 metadata 遺失、或對應 result_id 已過期）。你可刪除該快取後讓 Agent 重新執行，或對 persist 快取使用 Open Tab / Run 從分頁重新取得 SQL。
HTML Report 產出的報告支援哪些瀏覽器？
HTML Report 會以系統預設瀏覽器開啟。產出的 HTML 是標準網頁檔案，支援所有現代瀏覽器（Chrome、Firefox、Safari、Edge）。Presentation 模式 + CDN 需網路載入 reveal.js；Standard + CDN 需網路載入 Chart.js。關閉 CDN 則產出完全離線的 HTML，無需網路即可檢視（不含 Chart.js）。Custom Script 報告可能另載 D3／Plotly 等函式庫。
Context Usage 圓環顯示的數字代表什麼？
圓環顯示的是當前對話的 token 消耗量占模型 context window 的比例。tooltip 中的數值如 42.3% · 18.5K / 43.7K context used，代表已使用 18.5K tokens，模型 context window 為 43.7K tokens，消耗了 42.3%。當比例越高，表示剩餘空間越少——若接近 100%，建議開啟新對話以獲得最佳回覆品質。
AI 正在回應時，我不小心切換了工作區怎麼辦？
當 AI 正在生成時，切換工作區、新建／切換對話、Fork 等操作會先彈出確認對話框。若你選擇取消，操作不會執行，AI 繼續生成；若你確認，當前生成會被中斷，但已完成的回覆會保留在對話歷史中。
收起 AI 面板或切換至 Export 不會中斷生成；Agent 在背景繼續執行時，右側 Astroid 圖示會 pulse 並顯示綠點（見 §12.2）。
記憶體用量過高怎麼辦？
點擊標題列右上角的記憶體條圖示（MemoryStick），開啟 Memory Dashboard。你可以：逐一刪除不需要的快取表、降低「Max In-Memory Results」讓多餘的結果自動溢出磁碟，或直接點擊 Emergency Clean 一鍵釋放所有可回收的記憶體。詳見第 17 章。
AI 的分析工具需要安裝額外套件嗎？
不需要。統計分析工具（t 檢定、迴歸、預測等）全部內建於 AI Agent，不需要你額外安裝任何套件。AI 會在需要使用分析工具時先向你確認，你只需同意即可。
Agent Memory 已開啟，為什麼 Agent 好像不記得我的業務規則？
請先確認對話框中的 Enabled 是否為開啟，以及該條知識是否已從 Queued Knowledge 套用到 User 或 Project 知識檔——佇列中尚未核准的項目不會注入模型。關閉 Automatic suggestions 只會停止對話後背景萃取，不會停用已核准知識的注入。你亦可開啟 Agent Memory 分頁直接檢視或手動編輯知識檔。
我在卡片上套用了知識，為什麼 Queued Knowledge 裡找不到？
Queued Knowledge 只顯示尚未處理的 pending 項目。 套用成功後該筆會從佇列移除，這是預期行為。請到 Agent Memory 分頁查看：User 套用 → 左側選 User Knowledge；Project 套用 → 左側選對應專案的 Project Knowledge（不會出現在 User Knowledge）。套用當下應有英文 toast 說明寫入位置。
我點了 Project 套用，但知識好像沒寫進去？
常見原因：(1) 該筆先前已 Dismiss 或已套用，再次點選不會重寫（會提示 Already dismissed / Already saved）；(2) 在 User Knowledge 裡找 Project 套用的內容——應到該專案的 Project Knowledge 檔查看；(3) 若無聚焦專案且建議未指定專案，需手動 Pick project。
重開應用後，工具呼叫顯示「Tool execution interrupted」？
新版會從對話歷史還原已完成的工具結果與知識提案卡片狀態。升級前建立的舊對話若仍異常，請由開發者在本機對 chat_sessions 執行 backend/scripts/migrate_tool_call_ids.py（先 dry-run，確認後加 --apply；執行前請備份資料）。
Agent Memory 的知識會被 AI 提供者看到嗎？
在 Agent Memory 的 Enabled 為開啟、且相關內容已作為知識注入時：是的。該些知識會作為系統提示詞的一部分傳送給你設定的 LLM 服務（Ollama / OpenAI / Custom），與其他上下文資訊的隱私保護方式一致。若你使用本地模型（Ollama），資料不會離開你的電腦。若總開關關閉，則不會因記憶功能向模型注入這類知識。
我手動編輯了 user_knowledge.md，AI 會立即感知嗎？
是的。系統使用檔案修改時間（mtime）偵測變更，下一次 AI 對話時會自動重新讀取最新內容，無需重啟應用程式。
知識庫太大了，重組後還是超過上限怎麼辦？
LLM 重組時會嘗試合併相似條目並壓縮描述。如果知識確實很多且都不重複，你可以手動刪除過時或較少使用的條目。知識庫的 6,000 字元上限約可容納 30-50 條結構化知識。
App 畫面突然變成錯誤提示怎麼辦？
這是 Error Boundary（錯誤邊界）機制，用來防止應用程式完全白屏。如果是局部區域（編輯器或 AI 面板）顯示錯誤，點擊「Retry」按鈕即可恢復；如果是全螢幕錯誤頁面，點擊「Reload App」重新載入應用程式。錯誤資訊已自動記錄在本機，後續回饋時可一並附上。