Skip to content

CONCEPT Cited by 2 sources

Query tag filter

A query tag filter is the search-syntax primitive in a database-observability UI (or query-log search tool) that scopes results to queries or errors carrying a named tag, optionally with a specific tag value. It converts the body of per-query tags captured via SQLCommenter-style conventions into a navigable query surface.

Canonical forms

PlanetScale Query Insights canonicalises two filter shapes (Source: sources/2026-04-21-planetscale-debugging-database-errors-with-insights):

  • tag:tag_name:tag_value — equality filter. Matches queries or errors where the named tag has the specified value. Example from the post: tag:actor:alice@example.com would surface every query (and every error) originated by that actor.
  • tag:tag_name — existence filter. Matches any query or error where the named tag is present, any value. Useful for "show me all queries tagged with feature=X regardless of which user triggered them."

PlanetScale's canonical description: "Queries can be filtered by tag with the following syntax: tag:tag_name:tag_value. To show all queries that have a particular tag key present, regardless of the value, use tag:tag_name."

What it makes possible

Without a tag-filter surface, captured tags are a passive field on aggregated query stats — visible but not actionable. The filter turns them into a coordinate system for slicing the database workload:

  • Actor-scoped debugging (tag:actor:<id>) — what is this user / service / internal tool doing on the database?
  • Feature-scoped impact analysis (tag:feature:X) — what's the query load of the new feature since its rollout?
  • Tenant-scoped noisy-neighbour diagnosis (tag:tenant:Y) — is tenant Y driving the p99 tail?
  • Deploy-scoped regression hunt (tag:deploy:v2) — did queries tagged with the new deploy get slower?
  • Error-class scoped (tag:actor:X on the errors tab) — is one caller responsible for all the AlreadyExists errors? — the debugging pattern in the canonical PlanetScale post.

All of these use the same primitive — one tag-filter form — applied to a different captured key. The filter's power comes from SQLCommenter's application-captures-anything flexibility at the query-emitting layer; the filter just makes that captured data findable.

Tag-capture-threshold caveat

Insights documents one capture constraint:

"Searching queries by tag has one caveat: to associate tags, a query pattern must have had at least one query that took more than 1 second, read more than 10k rows, or resulted in an error. We find that most of the queries we want to search for have met these conditions."

The rationale is storage economics: tag-granular per-occurrence data scales with query volume; at PlanetScale scale a no-threshold policy would balloon Insights' storage budget. The chosen threshold captures the interesting tail — slow queries (> 1s), heavy queries (> 10k rows read), and errors — which is also the set of queries the debugger is most likely to search for. Normal cheap-successful queries are pattern-aggregated without tag granularity.

Interacts with

Seen in

  • sources/2026-04-21-planetscale-debugging-database-errors-with-insights — Canonical disclosure. The post announces the tag-filter syntax as a general Insights capability alongside the error-tracking feature launch.
  • sources/2026-04-21-planetscale-enhanced-tagging-in-postgres-query-insights — Extension. The same tag:KEY:VALUE / tag:KEY syntax now operates across the aggregate query stream, not just the notable / error streams. Before this release, searching tag:actor:alice surfaced only notable-query occurrences (slow, heavy, or errored). After this release, the same search also returns aggregate statistics for query patterns Alice issued — including cheap / fast ones that never hit the notable threshold. The syntax is unchanged; the backing data substrate expanded from "tail-only" to *"full-workload
  • tail"*, subject to tag cardinality collapse bounds.
Last updated · 347 distilled / 1,201 read