> For the complete documentation index, see [llms.txt](https://docs.opendatadiscovery.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.opendatadiscovery.org/developer-guides/api-reference/query-examples.md).

# Query Examples

Query Examples are exposed through `QueryExampleController` (the snippet itself) and through the Data Entity / Term controllers (the linking surface). The seven `QUERY_EXAMPLE_*` permissions documented under [Query Examples → Permissions (RBAC)](/features/data-modelling/query-examples.md#permissions-rbac) gate only the **mutation** endpoints (create / update / delete, and dataset / term link / unlink); the list, read, faceted-search, and per-entity / per-term lookup endpoints below carry **no SecurityRule** and **no per-owner gate**, so any authenticated user can read every snippet in the platform (its body, description, and linked entities), and none of these endpoints — reads or mutations — emit an Activity-Feed audit entry. The full read-posture and audit caveats are on the [Query Examples feature page → Known operator caveats](/features/data-modelling/query-examples.md#known-operator-caveats). For the feature description, the term-linking workflow, and the UI walkthrough, see the [Query Examples](/features/data-modelling/query-examples.md) page.

## CRUD (5 endpoints)

| Method + Path                           | Operation                                                             |
| --------------------------------------- | --------------------------------------------------------------------- |
| `GET /api/queryexample`                 | Paginated list of all snippets. Accepts `query` for free-text filter. |
| `POST /api/queryexample`                | Create a new snippet.                                                 |
| `GET /api/queryexample/{example_id}`    | Get full details.                                                     |
| `PUT /api/queryexample/{example_id}`    | Update.                                                               |
| `DELETE /api/queryexample/{example_id}` | Delete.                                                               |

## Faceted search (5 endpoints)

The same multi-step facet flow the main catalog uses — start a search to get a `search_id`, then read / update / paginate against that ID.

| Method + Path                                      | Operation                                                                                                 |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `POST /api/queryexample/search`                    | Start a search; returns the `search_id` and initial facet aggregations (operation `queryExamplesSearch`). |
| `GET /api/queryexample/search/{search_id}`         | Read the current facet values for a search.                                                               |
| `PUT /api/queryexample/search/{search_id}`         | Update facets (apply filters).                                                                            |
| `GET /api/queryexample/search/{search_id}/results` | Paginated result list for a search.                                                                       |
| `GET /api/queryexample/search/suggestions`         | Top-five matching snippet titles for a query string — used by the search-input typeahead.                 |

## Per-entity / per-term lookup and linking (6 endpoints)

Lookup is on `QueryExampleController`; linking lives on `DataEntityController` and the term API.

| Method + Path                                                         | Operation                                                                                                                                                                              |
| --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/queryexample/dataset/{data_entity_id}`                      | List all snippets attached to a dataset.                                                                                                                                               |
| `GET /api/queryexample/term/{term_id}`                                | List all snippets attached to a term.                                                                                                                                                  |
| `POST /api/dataentities/{data_entity_id}/queryexample`                | Attach a snippet to a dataset (operationId `createQueryExampleToDatasetRelationshipNew`; gated by `QUERY_EXAMPLE_DATASET_CREATE`).                                                     |
| `DELETE /api/dataentities/{data_entity_id}/queryexample/{example_id}` | Detach a snippet from a dataset (operationId `deleteQueryExampleToDatasetRelationshipNew`; gated by `QUERY_EXAMPLE_DATASET_DELETE`).                                                   |
| `POST /api/terms/{term_id}/queryexample`                              | Attach a snippet to a term (operationId `createQueryExampleToTermRelationship`; gated by `QUERY_EXAMPLE_TERM_CREATE`). The example is identified in the request body, not in the path. |
| `DELETE /api/terms/{term_id}/queryexample/{example_id}`               | Detach a snippet from a term (operationId `deleteQueryExampleToTermRelationship`; gated by `QUERY_EXAMPLE_TERM_DELETE`).                                                               |

## See also

* [API Reference hub](/developer-guides/api-reference.md) — the full per-feature index.
* [Query Examples](/features/data-modelling/query-examples.md) — feature description, RBAC permissions, term-linking workflow.