# Content queries

With content queries you can find and render specific content according to criteria that you define.

You can use queries to list or embed content items, such as:

- [children in a folder](https://doc.ibexa.co/en/latest/templating/embed_and_list_content/list_content/#list-children-with-query-type)
- related articles
- [most recent blog posts](https://doc.ibexa.co/en/latest/templating/queries_and_controllers/create_custom_query_type/index.md)
- recommended products

Content queries use the built-in Query controller which simplifies querying. For more complex cases, you can build custom [controllers](https://doc.ibexa.co/en/latest/templating/queries_and_controllers/controllers/index.md).

## Query types

The Query controller offers a set of [built-in Query types](https://doc.ibexa.co/en/latest/templating/queries_and_controllers/built-in_query_types/index.md). You can use them in the content view configuration, or in the [content query field](#content-query-field).

You can also write [custom Query types](https://doc.ibexa.co/en/latest/templating/queries_and_controllers/create_custom_query_type/index.md) for the cases that aren't covered by the built-in ones.

### Query type configuration

To use a Query type, select the Query controller (`ibexa_query`) in the [content view configuration](https://doc.ibexa.co/en/latest/templating/templates/template_configuration/index.md) and select the Query type under `params.query.query_type`:

```
folder:
    controller: ibexa_query::contentQueryAction
    template: '@ibexadesign/full/folder.html.twig'
    params:
        query:
            query_type: 'Children'
            parameters:
                content: '@=content'
            assign_results_to: items
    match:
        Identifier\ContentType: folder
```

Use one of the following Query controller methods:

- `locationQueryAction` runs a location Search
- `contentQueryAction` runs a content Search
- `contentInfoQueryAction` runs a ContentInfo search
- `pagingQueryAction` returns a `PagerFanta` object and can be used to quickly [paginate query results](#pagination)

See the [Search](https://doc.ibexa.co/en/latest/search/search/index.md) documentation page for more details about different types of search.

All Query types take the following parameters:

- `query_type` is the name of the Query type to use.
- `parameters` can include:
  - arbitrary values
  - expressions based on the `content`, `location` and `view` variables. For example, `@=location.id` is evaluated to the current Location's ID.
- `assign_results_to` declares the Twig variable that contains the search results.

Tip

Search results are a `SearchResult` object, which contains `SearchHit` objects. To get the content or Locations that are in search results, you access the `valueObject` of the `SearchHit`.

### Pagination

To paginate the results of a query, use the `pagingQueryAction` of the Query controller and assign a limit per page in `params.query.limit`:

```
            content_view:
                full:
                    folder:
                        controller: ibexa_query::pagingQueryAction
                        template: '@ibexadesign/full/folder.html.twig'
                        params:
                            query:
                                query_type: 'Children'
                                parameters:
                                    content: '@=content'
                                assign_results_to: items
                                limit: 3
                        match:
                            Identifier\ContentType: folder
```

Use the [`pagerfanta`](https://www.babdev.com/open-source/packages/pagerfanta/docs/3.x/intro) function to render pagination controls:

```
{% for item in items %}
    {{ ibexa_render(item.valueObject) }}
{% endfor %}

{{ pagerfanta(items, 'twitter_bootstrap5', {
    'routeName': 'ibexa.url.alias',
    'routeParams': {'location': location }
}) }}
```

## Content query field

The [Content query field](https://doc.ibexa.co/en/latest/content_management/field_types/field_type_reference/contentqueryfield/index.md) is a field that defines a query. The results of the query are available in the field value.

### Query type

When adding the field to a content type definition, select the Query type in the **Query type** dropdown. All Query types in the application are available, both [built-in](https://doc.ibexa.co/en/latest/templating/queries_and_controllers/built-in_query_types/index.md) and [custom ones](https://doc.ibexa.co/en/latest/templating/queries_and_controllers/create_custom_query_type/index.md).

### Returned types

Select the content type of items you want to return in the **Returned type** dropdown. To take it into account, your Query type must filter on the content type. Provide the selected content type through the `returnedType` variable:

```
contentType: '@=returnedType'
```

### Pagination

Select **Enable pagination** and set the number of items per page to paginate the results.

You can override the pagination settings from field definition by setting the `enablePagination`, `disablePagination` or `itemsPerPage` parameters when rendering the content query field:

```
{{ ibexa_render_field(content, 'query', {
    location: location|default(null), 'parameters': {
        'enablePagination': true,
        'itemsPerPage': 8
    }
}) }}
```

You can also define an offset for the results. Provide the offset in the Query type, or in parameters:

```
offset: 3
```

If pagination is disabled and an offset value is defined, the query's offset is added to the offset calculated for a page. For example, with `offset` 5 and `itemsPerPage` 10, the first page starts with 5, the second page starts with 15, and so on.

Without offset defined, pagination defines the starting number for each page. For example, with `itemsPerPage` 10, first page starts with 0, second page starts with 10, and so on.

### Parameters

The following variables are available in parameter expressions:

- `returnedType` - the identifier of the content type selected in the **Returned type** dropdown
- `content` - the current content item
- `location` - the current Location of the content item
- `mainLocation` - the main Location of the content item
- `contentInfo` - the current content item's ContentInfo

### Content view configuration

To render a content query field, in the content view configuration, use the `content_query_field` view type:

```
            content_view:
                content_query_field:
                    blog:
                        template: '@ibexadesign/content_query/blog_posts.html.twig'
                        match:
                            Identifier\ContentType: blog
                            '@Ibexa\FieldTypeQuery\ContentView\FieldDefinitionIdentifierMatcher': query
```

The identifier of the content query field must be matched by using the `'@Ibexa\FieldTypeQuery\ContentView\FieldDefinitionIdentifierMatcher'` matcher.

Query results are provided to the template in the `items` variable. See [List content](https://doc.ibexa.co/en/latest/templating/embed_and_list_content/list_content/#list-children-in-content-query-field) for an example of using the content query field.