Query Examples

Operator-curated SQL / KQL / Spark snippets attached to data entities and terms — the canonical "how to use this dataset" surface.

Query Examples are operator-curated query snippets — typically SQL, but anything that reads as a "how the team uses this dataset" example — attached to one or more data entities and optionally linked to glossary terms. They turn the catalog from "what we have" into "what we have and how to use it", without forcing readers to dig into a wiki or ping the team that owns the data.

Query Examples is the first sub-surface of the Data Modelling section.

What you can do

• Author and edit snippets with a name, description, and the query body. The description doubles as a "prompt"-style explanation of intent.

• Link a snippet to one or more data entities (tables, views, files) so it shows up on the entity's detail page as one of the canonical examples.

• Link a snippet to glossary terms so terminology + canonical usage stay close to each other.

• Search the catalog of snippets with a dedicated faceted search that supports filters, the same shape as the main catalog search.

• Get search suggestions as you type — the top five matching snippet titles for a query string.

UI walkthrough

Open Data Modelling → Query Examples from the top-level navigation (/data-modelling/query-examples). The list view shows every snippet the user is allowed to read, with a search box and an "Add query example" button. The button is gated by the QUERY_EXAMPLE_CREATE permission — users without it see the list but no create entry-point.

Query Examples list page — each row carries the snippet's number, definition, query body preview, linked data entities (ORDERS, CUSTOMER, LINEITEM), and any linked glossary terms (2NF). The left-rail switches between Query Examples and Relationships, the two Data Modelling sub-surfaces.

• List page (/data-modelling/query-examples) — all snippets, with search, total count, and the create button.

• Details / edit page (/data-modelling/query-examples/{id}) — the snippet's full body, its description, and the linked data entities and terms. Edit and delete actions are gated by QUERY_EXAMPLE_UPDATE and QUERY_EXAMPLE_DELETE respectively.

• On a dataset's detail page — Query Examples linked to that dataset surface in the dataset's "Query Examples" tab; operators with QUERY_EXAMPLE_DATASET_CREATE can attach existing snippets, and QUERY_EXAMPLE_DATASET_DELETE users can detach.

• On a term's detail page — same pattern, gated by QUERY_EXAMPLE_TERM_CREATE and QUERY_EXAMPLE_TERM_DELETE.

Permissions (RBAC)

Seven permissions on the Query Example surface, all configurable on roles via the standard authorization model (see Authorization → Roles):

Permission	What it gates
QUERY_EXAMPLE_CREATE	Create a new snippet (the "Add query example" button on the list page).
QUERY_EXAMPLE_UPDATE	Edit an existing snippet.
QUERY_EXAMPLE_DELETE	Delete an existing snippet.
QUERY_EXAMPLE_DATASET_CREATE	Attach a snippet to a dataset (entity ↔ snippet link).
QUERY_EXAMPLE_DATASET_DELETE	Detach a snippet from a dataset.
QUERY_EXAMPLE_TERM_CREATE	Attach a snippet to a glossary term (term ↔ snippet link).
QUERY_EXAMPLE_TERM_DELETE	Detach a snippet from a glossary term.

API surface

The full HTTP API for Query Examples is documented at API Reference → Query Examples — 16 endpoints across three groups (CRUD, faceted search, per-entity/per-term lookup and linking), exposed by QueryExampleController and the Data Entity / Term controllers, with the seven QUERY_EXAMPLE_* permissions called out alongside the gated endpoints. To call them outside the in-app UI, authenticate with a server-to-server (S2S) API key.

Term-linking workflow

Glossary terms and Query Examples reinforce each other: a term defines what a concept is (e.g., "active customer"); a query example shows how to compute it against your real datasets. The platform supports both directions:

1. From a term's detail page, attach an existing Query Example. The term gains a "Query Examples" cluster surfacing the snippet alongside the linked datasets.

2. From a snippet's detail page, link the snippet to one or more terms. The snippet gains a "Terms" cluster.

3. The dedicated Query Example faceted search exposes a Terms facet — narrow snippets to ones that target a specific glossary term.

This closes the catalog loop: a reader landing on the term finds the canonical snippet; a reader landing on the snippet finds the term it implements.

Query Example Details Page

Opening any Query Example from the list (/data-modelling/query-examples/{id}) lands on a three-tab details page. The active tab is driven by a ?tab= URL query parameter:

Tab	URL state	What it shows
Overview	?tab=overview (or no ?tab= — default)	The snippet's definition (prompt-style description) and the query body, both rendered through the platform's Markdown renderer.
Linked Entities	?tab=linked-entities	The data entities this snippet is attached to (tables, views, files). Read-only — unlinking requires opening the linked entity's own detail page and removing the snippet from there.
Linked Terms	?tab=linked-terms	The glossary terms this snippet is linked to. Read-only with the same workflow note.

The tab strip carries small counter "hint badges" next to each tab name showing how many entries it contains.

Arbitrary ?tab= values render an empty body. The page accepts the URL parameter verbatim — it does not validate that the value is one of the three known tokens above. A typo (?tab=overiew, ?tab=linked_entities with underscore) or a future-renamed token lands the user on the page with no active tab and a blank content area — no error message, no "tab not found" placeholder. If you are deep-linking from another system, validate the token on your side before generating the URL.

The "Linked Terms" hint badge can understate when a snippet has many terms. The Linked Entities badge reads the total from server-side pagination (it is correct across all pages). The Linked Terms badge reads items.length on the loaded slice (it understates if the term collection is large enough to paginate). The tab body itself shows all loaded terms; only the badge digit may differ from the total.

The details page does not carry a breadcrumb back to the list — use the Data Modelling → Query Examples left-rail tab to return to the listing, or the browser Back button.

Known operator caveats

The Query Examples surface carries several behaviours that are non-obvious from the UI and the permission table alone. Each item below states what an operator might assume, what the platform actually does, and what to do today.

The seven QUERY_EXAMPLE_* permissions are wired across three different controllers. Configuring "Query Example access" in a single Policy is not enough — the gating endpoints live on three different surfaces:

When granting Query Example capability to a role, audit Policies on all three controllers. Restricting QUERY_EXAMPLE_* in one Policy scope (e.g., only the Query Example controller) leaves four of the seven permissions un-enforced on that role — operators can still attach / detach snippets from datasets or terms.

Permissions	Controller surface	Endpoints
QUERY_EXAMPLE_CREATE / _UPDATE / _DELETE	Query Example controller	POST/PUT/DELETE /api/queryexample/...
QUERY_EXAMPLE_DATASET_CREATE / _DELETE	Data Entity controller	POST/DELETE /api/dataentities/{id}/queryexample[/{example_id}]
QUERY_EXAMPLE_TERM_CREATE / _DELETE	Term controller	POST/DELETE /api/terms/{id}/queryexample[/{example_id}]

All read, search, and listing endpoints for Query Examples are open to every authenticated user — only the seven mutation permissions are RBAC-gated. The mutation operations (CREATE / UPDATE / DELETE on snippets, dataset-link CREATE / DELETE, term-link CREATE / DELETE) check the permission table above. The listing surface (GET /api/queryexample), the per-snippet read (GET /api/queryexample/{id}), the faceted search endpoints, and the per-entity / per-term lookup endpoints all fall through to the platform's catch-all "any authenticated user" rule.

Operator-visible consequence. Every authenticated user reads every Query Example in the platform — title, description, query body, linked entities, linked terms — regardless of dataset RBAC, namespace scoping, or exclude_from_search. Under auth.type=DISABLED, the same reads are anonymous. Multi-team deployments expecting per-team query-example visibility cannot enforce it through the RBAC layer today. Treat Query Example content as catalog-read-collaborative; sensitive SQL bodies (production credentials, restricted column references, internal table aliases) should not be authored here, or should be enforced at the network perimeter via reverse-proxy rules.

The Query Example Markdown render is HTML-sanitised as of 0.28.0. The definition (prompt-style description) and query (SQL body) fields are stored verbatim and rendered through the platform's shared Markdown renderer on the details page. Releases up to 0.27.x ran that renderer without an HTML-sanitisation pass, so HTML embedded in either field rendered for every viewer; 0.28.0 adds render-time sanitisation to the shared Markdown renderer, so <script>, javascript: hrefs, and other raw-HTML payloads in a Query Example body are stripped when the snippet is displayed.

Still review what you store. Sanitisation is a render-time defence, not an input filter: the raw field value is stored verbatim and is readable by every authenticated user through the open read endpoints above. Restrict QUERY_EXAMPLE_CREATE and QUERY_EXAMPLE_UPDATE to operators reviewing the source of every value they paste in, and avoid bulk-importing Query Examples from untrusted external systems.

The create / edit dialog has no client-side validation and no draft persistence. The Query Example form validates only that the definition and query fields are non-empty — there is no length cap and no content preview. Values are stored verbatim; rendered Markdown is HTML-sanitised at display time as of 0.28.0 (see the note above).

The dialog also has no dirty-form warning and no autosave: closing the dialog through Escape, an outside-click, or browser back drops the entire in-progress body silently. For a SQL snippet of moderate size this is a real loss — minutes-to-hours of work disappear without recovery. Workaround: copy the SQL body to the clipboard before closing the dialog; treat the dialog as ephemeral until the upstream handleNavigationWarning hook ships.

The definition field is a plain text input at authoring time but renders through the Markdown renderer on the details page. An author typing **bold** or ## Heading into the definition field sees plain text in the form preview but rendered Markdown on the details page. Review the rendered details page after the first save to catch formatting surprises (rendered Markdown is HTML-sanitised as of 0.28.0 — see the render-sanitisation note above).

Query Example mutations are not recorded on the Activity Feed. Creating, updating, deleting, or linking / unlinking a Query Example produces no entry on the global Activity Feed and no entry on the per-entity Activity tab. There is no platform-side audit trail for Query Example changes today — auditor queries of "who edited which snippet when" cannot be answered from platform logs. The wider audit-scope picture and the compensating controls operators can apply are documented on the Audit trail scope page; until the platform-side activity-event ships, instrument Query Example changes externally (PostgreSQL pgaudit on the query_example and query_example_* tables, or an API-gateway-level audit hook).

Where to next

• Data Modelling overview — parent section; pairs Query Examples with Relationships.

• Relationships — the other Data Modelling sub-surface.

• Authorization → Roles — wire the seven QUERY_EXAMPLE_* permissions onto your roles.

• Audit trail scope — the cross-platform list of surfaces that emit Activity-Feed events versus those that do not.

• API reference — the full Ingress / management API.