Frequently Asked Questions (FAQ)

18. Frequently Asked Questions (FAQ)

Why are query results limited to 500 rows on screen?

The on-screen result preview is capped at 500 rows to keep the interface responsive. If you need the full query result, use the export function to save the data to a file—export is not subject to this limit.

Why can't I query my Excel file directly?

When querying an Excel file, you must specify the sheet name. The correct syntax is:

SELECT * FROM "filename.xlsx"."SheetName"

Expand the Excel file in the sidebar to view and select the sheet name.

Why doesn't export support .json?

Lantide Data uses the .jsonl (JSON Lines) format instead of .json. JSON Lines writes one record per line, which is better suited to reading and writing large amounts of data. Just change the extension to .jsonl when exporting.

Can I run INSERT, UPDATE, or other write operations?

No. Lantide Data supports read-only queries only, including SELECT, DESCRIBE, SHOW, and PRAGMA. This protects your source data from accidental modification.

When do cached tables disappear?

Cached tables are cleared in the following cases:

• When you switch to another workspace.
• When you restart the application.

After they are cleared, just re-run the corresponding Persist tab to recreate the cached table.

What do I do about the Source Run error "single SQL statement required"?

Source Run and lineage analysis require one SQL statement per tab. Make sure the tab does not contain multiple statements separated by semicolons. If you need to combine several steps, put each step in its own tab and chain them via cached tables.

Can I query cached tables across workspaces?

No. Each workspace's cached tables are completely isolated—you cannot reference workspace B's cached tables from workspace A.

The reason is that Lantide Data's caching mechanism is built on DuckDB in-memory temp tables—each time you switch workspaces, the system first clears all temp tables from the previous workspace and then loads the new workspace's data environment. Therefore, only the current workspace's cached tables exist in memory at any one time.

If you need to share a query result across workspaces, we recommend first exporting the result to a file (for example CSV or Parquet) and then loading that file into the other workspace's data directory. Alternatively, keep all the data you need to analyze under the same workspace directory.

What is the difference between an AI-created SQL Tab and one I create manually?

There is no difference. An AI-created SQL Tab is exactly the same as one you create manually—they are the same Persist Tabs, stored in the workspace, and their query results are materialized into cached tables the same way. You can keep editing an AI-created Tab manually, re-run it, or use Source Run to chain upstream and downstream dependencies.

Can the AI modify or delete my source data files?

No. All of the AI Agent's operations are read-only—it can only run SELECT-type queries and cannot modify your source data through statements such as INSERT, UPDATE, or DELETE. This safety restriction is enforced by the backend SQL validation layer, and the AI cannot bypass it.

Why does the PostgreSQL / MySQL connection test fail (Connection refused)?

This usually means the corresponding database service is not running locally, or the host/port is configured incorrectly (for example 127.0.0.1:5432, 127.0.0.1:3306).

Check the following in order:

1. Whether the database service is running.
2. Whether host / port / database / username / password are correct.
3. Whether the local firewall and network policy allow the connection.
4. For a remote database, whether your IP has been added to the allowlist.

The AI panel's status indicator doesn't match the actual state?

In rare cases, the Agent state computed by the frontend may not match the backend. In that case, trust the backend—the backend's State Router decides which tools the AI can use. You can try switching tabs or refreshing the page to resync the state.

The AI says it "created a Tab" but I don't see a new tab?

In most cases the sidebar workspace list updates immediately after the Agent creates a Persist tab. If the editor tab bar still does not show it, click the corresponding Persist tab in the sidebar to reopen it; if it is still missing, switch workspaces and back, or reload the page.

Why is there no * after the Agent writes SQL?

Content the Agent writes through tools is saved directly to the workspace, so the tab does not show an unsaved * marker. The * appears only after you edit manually, and closing the tab still prompts you to save or discard as usual (see §5.2).

What is the difference between validate_query and run_query in a conversation?

validate_query test-runs the SQL with LIMIT 1 and returns only success or error—it does not return data rows—which is good for exploration and trial and error. run_query runs the query and returns a preview of up to 200 rows for the Agent to analyze. If an old conversation shows the legacy tool name test_query, that is just an old record. See §12.6.

When does run_query materialize into a cached table?

The system infers this automatically—you don't need to set materialize=true every time. It generally materializes when: there is already a successful query step in the conversation (multi-step analysis), the SQL references an existing cached table, or the query is fairly complex (for example a multi-table JOIN or many CTEs). A single-table exploration query (with LIMIT and no JOIN/GROUP) usually only returns a preview and is not materialized. If the model passes materialize=false but the system determines materialization is required, it still materializes and adds warnings to the tool result to explain. See §12.6 and §7.4.

What is the difference between agent cache and persist cache?

Both can be right-clicked under Data → Cached for View SQL, SELECT 100 rows, or referenced in SQL via FROM (within the same workspace).

What do I do when View SQL shows "unavailable"?

This means the system cannot restore that cache's SQL from the cache registry, the conversation ledger, or the result manager (common with old caches, metadata lost after a restart, or an expired result_id). You can delete the cache and let the Agent re-run it, or for a persist cache use Open Tab / Run to get the SQL again from the tab.

Which browsers do HTML Reports support?

An HTML Report opens in the system's default browser. The generated HTML is a standard web page and supports all modern browsers (Chrome, Firefox, Safari, Edge). Presentation mode + CDN needs to load reveal.js over the network; Chart.js interactive charts (Standard + CDN) need to load Chart.js over the network. With CDN off, the output is fully offline HTML that can be viewed without a network (without Chart.js).

What does the number in the Context Usage ring mean?

The ring shows the current conversation's token usage as a share of the model's context window. A tooltip value such as 42.3% · 18.5K / 43.7K context used means 18.5K tokens have been used out of a 43.7K-token model context window, consuming 42.3%. The higher the ratio, the less space remains—if it approaches 100%, we recommend starting a new conversation for the best reply quality.

What if I accidentally switched workspaces while the AI was responding?

While the AI is generating, operations such as switching workspaces, creating / switching conversations, or Fork first pop up a confirmation dialog. If you cancel, the operation does not run and the AI keeps generating; if you confirm, the current generation is interrupted, but the reply completed so far is kept in the conversation history.

Collapsing the AI panel or switching to Export does not interrupt generation; while the Agent keeps running in the background, the Astroid icon on the right pulses and shows a green dot (see §12.2).

What do I do about high memory usage?

Click the memory bar icon (MemoryStick) in the top-right of the title bar to open the Memory Dashboard. There you can: delete unneeded cached tables one by one, lower "Max In-Memory Results" so extra results spill to disk automatically, or click Emergency Clean to free all reclaimable memory at once. See Chapter 17 for details.

Do the AI's analysis tools require installing extra packages?

No. The statistical analysis tools (t-test, regression, forecasting, etc.) are all built into the AI Agent, and you do not need to install any extra packages. The AI confirms with you before using an analysis tool—you just need to agree.

Agent Memory is on, so why does the Agent seem not to remember my business rules?

First confirm that Enabled is on in the dialog, and that the piece of knowledge has been applied from Queued Knowledge to the User or Project knowledge file—items in the queue that are not yet approved are not injected into the model. Turning off Automatic suggestions only stops background extraction after conversations; it does not disable injection of approved knowledge. You can also open the Agent Memory tab to view or manually edit the knowledge files directly.

I applied knowledge on a card, so why can't I find it in Queued Knowledge?

Queued Knowledge shows only pending items that have not yet been processed. After a successful apply, the item is removed from the queue—this is expected behavior. Check the Agent Memory tab: for a User apply → select User Knowledge on the left; for a Project apply → select the corresponding project's Project Knowledge on the left (it will not appear under User Knowledge). At the moment of applying, an English toast should explain the write location.

I clicked Project apply, but the knowledge doesn't seem to have been written in?

Common causes: (1) the item was previously Dismissed or already applied, and clicking it again does not rewrite (it shows Already dismissed / Already saved); (2) you are looking for the Project-applied content in User Knowledge—check the project's Project Knowledge file instead; (3) with no focused project and no project specified on the suggestion, you need to Pick project manually.

After reopening the app, a tool call shows "Tool execution interrupted"?

New versions restore completed tool results and knowledge proposal card state from the conversation history. For old conversations created before the upgrade that still behave abnormally, a developer can run backend/scripts/migrate_tool_call_ids.py locally against chat_sessions (dry-run first, then add --apply once confirmed; back up your data before running).

Will Agent Memory knowledge be seen by the AI provider?

When Agent Memory's Enabled is on and the relevant content has been injected as knowledge: yes. That knowledge is sent as part of the system prompt to the LLM service you configured (Ollama / OpenAI / Custom), with the same privacy protection as other context information. If you use a local model (Ollama), the data does not leave your computer. If the master switch is off, no such knowledge is injected into the model by the memory feature.

I manually edited user_knowledge.md—will the AI notice immediately?

Yes. The system detects changes using the file modification time (mtime), and the next AI conversation automatically re-reads the latest content without restarting the application.

My knowledge base is too large, and it still exceeds the cap after reorganizing?

When reorganizing, the LLM tries to merge similar entries and compress descriptions. If the knowledge really is extensive and non-duplicated, you can manually delete outdated or rarely used entries. The knowledge base's 6,000-character cap can hold roughly 30–50 structured pieces of knowledge.

What do I do when the app screen suddenly turns into an error prompt?

This is the Error Boundary mechanism, which prevents the application from going completely blank. If a local area (the editor or AI panel) shows an error, click the "Retry" button to recover; if it is a full-screen error page, click "Reload App" to reload the application. The error information is automatically logged locally and can be attached with your feedback later.