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.

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.

• API reference — the full Ingress / management API.