# Query Examples

Query Examples are exposed through `QueryExampleController` (the snippet itself) and through the Data Entity / Term controllers (the linking surface). All actions are gated by the seven `QUERY_EXAMPLE_*` permissions documented under [Query Examples → Permissions (RBAC)](/features/data-modelling/query-examples.md#permissions-rbac). 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 (gated by `QUERY_EXAMPLE_DATASET_CREATE`).                                                                                                               |
| `DELETE /api/dataentities/{data_entity_id}/queryexample/{example_id}` | Detach a snippet from a dataset (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.


---

# 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/developer-guides/api-reference/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.