Table Query Ops

Review query risk recommendations for slow tables and confirm database improvements.

Available for self-hosted Business plan and above

Path: Admin Panel → Table Query Ops

Use Table Query Ops when views, filters, relations, or searches on a large table become slow. A background analyzer watches the query workload and turns what it observes into recommendations. The page lists them so instance administrators can review the evidence, analyze a specific table in more depth, and confirm any database change.

The counters above the list summarize the current picture: observation windows, requests, slow queries, timeouts, open and accepted recommendations, running and failed tasks, and how many search access paths are ready or degraded.

Review Recommendations

The page opens on Recommendations, ordered by priority. The analyzer weighs the risk of a query against how heavily the table is used, so the entries most worth acting on come first.

Search by table, Base, or Space ID to filter across all recommendations; any other text filters what is already on screen. The status and risk filters narrow the list further.

Each entry names the space, base, and table it belongs to. Expand a row to read the evidence behind the recommendation, the system decision, and the SQL diagnostics:

Section	What it tells you
Trigger	Where the recommendation came from: observed query traffic, a saved view configuration, or a relation field configuration. A saved-view trigger means no slow query was observed yet; the configuration alone is what raised the risk.
Access path	How often this table was reached by sequential scan versus index scan.
Reasons	Readable causes such as a large table, no useful index on the filter or sort fields, expensive sorting, or observed timeouts.
Query shape	The specific fields being filtered and sorted, with the kind of match each one uses.
Proposed index	The fields the recommendation would index, and why.

Deep analysis opens the analysis workspace with that table already filled in.

Two more tabs sit beside it:

Tab	What it shows
Hot tables	The busiest tables, with requests, slow queries, timeouts, and longest query duration.
Tasks	Remediation tasks Teable created, with status, attempts, worker, and the last error.

A banner appears above the list when a configuration problem is holding the process up: search access paths are configured while the runtime flag is off, some tables have a stale or rebuild-pending access path and their search has silently fallen back to the slower ILIKE scan, or the oldest queued task has waited long enough to suggest no worker is consuming it. Fix what the banner reports before acting on the recommendations below it.

Read the Decision Badge

Each recommendation carries the latest decision the system made about it:

Badge	Meaning
Needs manual confirmation	Only an administrator can apply this one.
Shadow · would auto-run	The recommendation meets the acceptance criteria, but automatic execution is not enabled, so nothing changed.
Auto-executing / Auto-executed	Automatic execution accepted the recommendation and applied it.
Post-verify failed · backing off	An automatic change did not pass verification. Teable waits longer before trying that table again.
Cooling down	The same scope was changed recently, so the system is holding off.
On hold / Auto-execution not applied	The plan evidence or the table size did not meet the bar for automatic execution.

By default Teable only records decisions and creates recommendation and task records; it does not change your database on its own. Automatic execution is opt-in through V2_TABLE_QUERY_OPS_AUTO_ACCEPT=auto, and even then it applies only to small tables whose execution plan shows a clear cost improvement. Everything else waits for an administrator.

Add the Proposed Index

When a recommendation proposes an index you agree with, click Add index on the row. Confirming accepts the recommendation and runs CREATE INDEX CONCURRENTLY on the underlying PostgreSQL table; if plan validation was skipped, Teable still builds the index from the recommended fields. The dialog repeats the evidence so you can check it one last time.

For a table estimated at 50,000 rows or more, the dialog asks you to confirm that a maintenance window is in place before the button becomes available. A concurrent build on a large table takes time and adds load while it runs.

Teable then reports either Index created or Recommendation accepted and queued. In the second case, follow the task under Tasks. If the recommendation has no executable physical column behind it, Add index stays disabled and says so; use the analysis workspace to look further instead.

Run a Deep Analysis

Open Analysis workspace to analyze a scope on demand, for example when a user reports a slow table that has no recommendation yet.

Analysis type	Use it for
Queries & indexes	Find query risks and possible index improvements.
Substring search	Check whether a substring search access path could speed up contains searches without changing their matching behavior.

Choose Table, Base, or Space, enter the corresponding ID, and select an analysis type. Start with Table when you already know which table is slow.

Click Generate query report or Generate search report. The report summarizes detected risks and recommended next actions. For a search report, EXPLAIN sample search is optional. Add a sample to check result compatibility, query plans, and repeated query timing for the proposed substring search access path. Teable does not save the sample value.

The query report does not change the database. Applying a substring search recommendation requires an EXPLAIN sample search and administrator confirmation.

For a large table, review the impact and schedule any confirmed change for a suitable maintenance window.