# Query Examples

**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](/features/data-modelling.md) 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.](/files/Gxw6Wt7fG12YwN5yMOrd)

* **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](/configuration-and-deployment/enable-security/authorization/roles.md)):

| 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](/developer-guides/api-reference/query-examples.md) — 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](/configuration-and-deployment/enable-security/authentication/s2s.md).

## 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](/features/data-modelling.md) — parent section; pairs Query Examples with Relationships.
* [Relationships](/features/data-modelling/relationships.md) — the other Data Modelling sub-surface.
* [Authorization → Roles](/configuration-and-deployment/enable-security/authorization/roles.md) — wire the seven `QUERY_EXAMPLE_*` permissions onto your roles.
* [API reference](/developer-guides/api-reference.md) — the full Ingress / management API.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.opendatadiscovery.org/features/data-modelling/query-examples.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.