> ## Documentation Index
> Fetch the complete documentation index at: https://ngquct-fix-mongodb-insert-empty-field-name.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Assistant
> Built-in AI for SQL: chat with tool calling, inline suggestions, and review, explain, optimize, and fix-error across 14 providers
One provider is active at a time and answers every AI request in the app, from the chat panel to the ghost text in the editor. Switch it and all of them switch with it. Keys are yours and live in the macOS Keychain, so every request bills to your own account with that provider.
## Configure a provider
Open **Settings > AI** (`Cmd+,`). **Enable AI Features** at the top gates the whole tab; turning it off also hides the per-connection AI policy in the connection form.
Click **Add Provider…** and pick a type. **Add Custom Provider…** at the bottom takes any OpenAI-compatible endpoint.
Paste the API base from the server's own documentation, version segment included: `https://api.openai.com/v1`, `https://api.z.ai/api/paas/v4`, `http://localhost:1234/v1`. Under the field is the URL a request resolves to. A full chat completions URL works as well and is used as it stands.
Paste an API key, or sign in for GitHub Copilot, ChatGPT, Cursor, and xAI. Leave the key empty for a Custom provider whose server checks none, such as a self-hosted vLLM or LM Studio with authentication off.
Type a model name or pick one from the fetched list, then click **Test Connection**.
The **Active Provider** picker decides which one handles requests. Setting it to **None** leaves any open conversation readable but read-only, with a **Settings…** button under it. Where a model supports reasoning effort, its detail sheet adds a picker for it and replies render their thinking in a collapsible **Reasoning** block.
With no preference, start with Claude or OpenAI on an API key: both take a key, tools, and images with no further setup. The others each come with something to know.
| Provider | Sign-in | Worth knowing |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub Copilot | GitHub device flow | Runs its own tool loop, so the tool call limit never applies |
| ChatGPT | Your ChatGPT account, on the Codex quota from Plus, Pro, Business, and Enterprise plans. **Import from Codex CLI** reuses an existing login | Unofficial interface, may change |
| Cursor | API key, or **Sign in with Cursor** with the Cursor CLI installed | Runs as an agent, not a chat-completions endpoint, so it cannot call TablePro's tools: Edit and Agent modes run no queries through it |
| xAI | API key, or **Sign in with xAI** on a SuperGrok or X Premium+ subscription | Sign-in opens a Grok Build consent screen and is unofficial. Presets: Grok 4.5, Grok 4.3 |
| Ollama, llama.cpp, MLX | None. Start the server first | Presets fill in `http://localhost:11434` for Ollama and `http://localhost:8080` for `llama-server` and `mlx_lm.server`. Start `llama-server` with `--jinja` for tool calling |
| Claude Agent | Claude Code's `claude` command, no key | Bills against a Claude subscription, with tradeoffs |
### Claude Agent
Install Claude Code, run `claude /login` in Terminal, then pick Opus, Sonnet, or Haiku. Replies bill against your Claude subscription instead of an API key. The provider answers from your schema when the MCP server is on in **Settings > Integrations**, and falls back to plain chat when it is off.
The `claude` tool runs headless here. Claude Code is built for you to use directly rather than as a backend for other apps, so this path can break with any Claude Code release. Your subscription is governed by Anthropic's [Consumer Terms](https://www.anthropic.com/legal/consumer-terms) and [Usage Policy](https://www.anthropic.com/legal/aup), which TablePro cannot grant rights under. Replies also count against the limits you share with claude.ai and your own Claude Code sessions, so running out here stops your work there. For a metered path on commercial terms, add the **Claude** provider with an API key.
## Chat
Press `Cmd+Option+A`, or choose **View > Show Assistant**, to open the assistant in the window's [trailing pane](/features/connection-window#the-trailing-pane). It shares that pane with the inspector, and the two-segment picker at the leading end of the pane's header moves between them. Over an open inspector the shortcut swaps rather than closes; over an open assistant it closes the pane.
Whichever segment you pick is remembered for that connection, and only a segment you pick counts: opening the pane for a row you clicked, with **Auto-show inspector on row select** on, leaves a pane you left on the assistant alone. The assistant has no toolbar button of its own: the pane toggle opens the column and the picker chooses what it draws.
With AI features off in **Settings > AI**, the command is dimmed and the picker is gone, so the pane holds the inspector alone. In [Agent mode](/features/agent-mode) the command is dimmed too, because the conversation is the window's content column there; **View > Focus > Focus Assistant** (`Ctrl+Cmd+Option+A`) puts the insertion point in its composer.
Type a question and press Return. Code blocks carry **Copy** and **Insert**, and Insert fills the current query tab when it is empty and opens a new one otherwise. A token count sits under each response, a failed one offers **Retry**, a finished one **Regenerate**, and **Stop Generating** cancels a reply mid-stream.
Conversations save themselves and take their title from your first message. The ellipsis menu at the trailing end of the pane's header holds **New Conversation**, **Conversation History** with the current conversation ticked, and **Clear Recents**, which asks before it deletes every one of them. **File > Session** carries the same three, so they work with the pane closed and in [Agent mode](/features/agent-mode). Editing a message you already sent puts its text and attachments back in the composer and drops that turn and everything after it.
Paste or drag images into the composer on any provider that takes them, which is all of them except GitHub Copilot, Cursor, ChatGPT, and Claude Agent. A drop that carries files the composer cannot read attaches the rest and says how many it kept.
The focused composer carries a colored highlight. Right-click it and turn **Highlight When Focused** off for the standard macOS focus ring instead. The choice is app-wide and survives restarts. Reduce Transparency and Increase Contrast, both under **System Settings > Accessibility > Display**, also replace the highlight with the focus ring.
### Chat modes
The mode picker in the composer footer controls which tools the AI can call. It is an app-level setting that survives restarts, and a fresh install starts in **Ask**.
| Mode | Tools available | When to use |
| --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **Ask** | Read-only schema lookups: `list_connections`, `get_connection_status`, `list_databases`, `list_schemas`, `list_tables`, `describe_table`, `get_table_ddl`. | Questions, exploration, drafting queries you run yourself. |
| **Edit** | All Ask tools, plus `execute_query` for `SELECT`, `INSERT`, `UPDATE`, `DELETE`. Destructive DDL (`DROP`, `TRUNCATE`, `ALTER…DROP`) stays blocked. | Letting the AI run the queries it proposes. |
| **Agent** | All tools, plus `confirm_destructive_operation` for destructive DDL. Runs tools in a loop. | Multi-step migrations and schema changes. |
Mode and [Safe Mode](/features/safe-mode) are independent gates. Agent mode does not bypass Safe Mode.
### Tool calling
In Edit and Agent modes each tool call appears as a card in the reply. Read-only tools run immediately. Write tools wait for **Run**, for **Always for this connection** (which whitelists that one tool on that one connection and syncs with it over iCloud), or for **Cancel**, which hands the model an error result and lets it carry on.
Safe Mode **Silent** auto-approves write tools and **Read-Only** auto-denies them. Destructive operations are the exception: `confirm_destructive_operation` always needs a click, Silent does not auto-approve it, **Always for this connection** is refused for it, and the model must pass the verbatim phrase `I understand this is irreversible`.
Every provider except Cursor can call tools. Claude Agent reaches them through the MCP server, so that has to be on, and local models depend on the model.
A reply pauses after 25 tool calls, keeps everything it has done, and offers **Continue** for a fresh budget or **Adjust Limit** to change the number, 5 to 200, under **Agent** in **Settings > AI**. Every call is another request with the schema attached, so a higher limit costs tokens.
### Attach context with `@`
Type `@` in the composer to open a picker at the caret: **Schema**, a specific **Table**, **Current Query**, **Query Results**, or a **Saved Query** ([favorites](/features/favorites)). Return or Tab inserts, Escape dismisses. The `@` button in the footer offers the same list minus saved queries. A saved query chip resolves at send time, so the AI sees its current SQL.
### Slash commands
Type `/` for **`/review`**, **`/explain`**, **`/optimize`**, and **`/fix`**, or **`/help`** for the list. The first three act on the text typed after the command, or on the whole query tab when there is none, and attach the same table structure as the menu actions. **`/fix`** sends the tab's last failed statement with its error. Add your own under **Settings > AI > Custom Slash Commands**: a template substitutes `{{query}}`, `{{schema}}`, `{{database}}`, and `{{body}}`, the text typed after the command, at send time. A custom command with a built-in's name runs only from the command menu.
### Model picker
The cpu icon beside the mode picker lists every configured provider and its models. A pick there overrides the active provider for this chat panel until you change it, across turns.
### The whole window
A long job reads badly in a 270pt pane. [Agent mode](/features/agent-mode) (`Cmd+Option+Shift+A`) gives the same session the whole window: the sessions on this connection, the conversation, and a pane holding the SQL it proposed and the rows it read. It is one conversation shown two ways, so switching does not start another.
## Review, explain, optimize, and fix
Put the cursor in a statement, or select the part you want, then pick an action. Each one sends what **Run** would run, never the whole tab, and opens a new conversation. While the assistant is still replying or waiting on your approval, the action opens a new session instead, and the busy one keeps running under **File > Session > Recent Sessions**.
| Action | Where to find it | What comes back |
| -------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| **Review with AI** | **Review** in the query bar, **Query > Review with AI** (`Cmd+Option+Shift+L`), the editor's context menu | Findings ranked by severity, each with its fix |
| **Explain with AI** | **Query > Explain with AI** (`Cmd+L`), the context menu, the menu beside **Review** | What the statement does, step by step |
| **Optimize with AI** | **Query > Optimize with AI** (`Cmd+Option+L`), the context menu, the menu beside **Review** | A rewrite or an index to add, with the reason |
| **Fix with AI** | The error banner after a query fails | The failed statement, corrected against its error |
Start with **Review with AI** when you are unsure what to ask: it checks correctness, cost and safety in one pass, and says so when the statement is fine.
The request carries the structure of the tables the statement names, read from the tab's own database and schema: columns and types, keys, indexes with their predicates, foreign keys, and estimated row counts. Up to 12 tables go, in the order the statement names them. The chip above your message lists them; hover it to see any table that could not be read or was not found. If the tab already shows an EXPLAIN plan for the same statement, the plan goes too. Building this reads only the database's catalog: your statement never runs, and no rows are sent. Turn off **Include database schema** in **Settings > AI** to send the statement alone.
With no provider set up the actions are dimmed. With AI turned off, or on a connection whose AI policy is **Never**, they are hidden.
The reply comes back as a walkthrough. Optimize and Fix diff your statement against the rewritten one, switchable between **Unified** and **Split**; Review and Explain anchor their steps to the statement as it stands. Each numbered step carries a one-line reason and a tag (**Critical**, **Change**, or **Context**), expands to the lines it refers to, and offers **Jump to lines** and **Ask about this change**, which keeps a follow-up anchored to that step. **Apply to Editor** replaces the statement you sent after you confirm. If you edited that statement since, the suggestion opens as a new query instead. A model that answers in prose renders as a normal message.
## Per-connection AI rules
Pin plain-text context to a connection so the AI sees it every turn: open the connection's edit form and pick **AI Rules** in the sidebar. Use it for what the schema cannot show, like `Always filter orders by deleted_at IS NULL` or `Never select users.ssn`. The text joins the system prompt and syncs with the connection over iCloud.
## Inline suggestions
Turn on **Enable inline suggestions while typing** in the AI tab; it is off by default. Pause typing and the active provider suggests a completion as ghost text at the cursor. `Tab` accepts, `Escape` dismisses, and typing anything else dismisses it too.
The pause is the **Debounce** setting beside the toggle: 500 ms by default, adjustable from 100 to 3,000 ms in 50 ms steps. With Copilot active the suggestions come from Copilot's inline-completion model; every other provider serves them through chat completions.
Suggestions follow the connection's AI policy, read again at every pause, so a policy you change in the connection form applies from the next one. **Always Allow** suggests right away. On **Ask Each Time**, suggestions start once you click **Allow** in the chat's **Allow AI Access** prompt for that connection, and stop when the connection disconnects. A **Never** connection gets no suggestions, and with Copilot active its editor text is not sent to Copilot either.
## What leaves your Mac
Every message carries a system prompt built from **Settings > AI > Context**, so these settings decide what the provider sees on every turn, not only the first.
| Setting | Default | What it sends |
| ----------------------- | ------- | --------------------------------------------------------------- |
| Include database schema | On | Columns and foreign keys for up to **Max schema tables** tables |
| Include current query | On | The editor's text, truncated at 2,000 characters |
| Include query results | Off | The rows in the results grid |
| Max schema tables | 20 | |
Ollama, llama.cpp, and MLX run on your own machine, so nothing reaches a third party. Every other provider is a network call to that vendor under the terms of your account with them.
Per connection, the **Advanced** pane of the connection form sets an AI policy: **Use Default**, **Always Allow**, **Ask Each Time**, or **Never**. The app-wide default is **Ask Each Time**: the chat asks before its first message on a connection, and one **Allow** covers every chat and the inline suggestions on that connection until it disconnects. **Never** also blocks external AI tool calls against that connection. External clients such as Raycast and Claude Desktop reach the same tools through the [External API](/external-api), bounded by the connection's **External Clients** level and the token's scope.