QueryInsights Documentation

QueryInsights is an AI-powered SQL performance platform. It captures the queries that actually run against your databases, normalizes them into unique patterns, and generates LLM-grounded optimization recommendations at both the per-query and whole-workload level — without ever sitting in your application's request path.

These docs explain how the system is put together, the concepts you'll encounter, every configuration knob, and how to safely connect your own databases.

Where to start

• Architecture — the four services, how data flows between them, and where each piece of state lives.
• Concepts — the poller, the engine, the LLM provider, and the other building blocks, explained one at a time.
• Configuration — every environment variable and the JSON shape used to describe database instances.
• Onboarding PostgreSQL — enable pg_stat_statements and create a least-privilege, read-only user.
• Onboarding CockroachDB — grant statement-stats visibility and schema-read access with a dedicated role.

The 30-second mental model

1. Ingest — a webhook (for Trino) or a poller (for PostgreSQL / CockroachDB) picks up live queries and forwards them to the engine over gRPC.
2. Normalize — the engine strips literals so thousands of query variants collapse into a single fingerprint.
3. Understand — each pattern is paired with the real DDL of the tables it touches, so the model reasons about your schema, not a generic one.
4. Recommend — the engine produces per-query rewrites and, on a schedule, workload-wide schema and index advice.

Everything is observed from the side. There is no proxy in front of your traffic and no SDK in your application, so QueryInsights can never affect latency or availability.