Skip to content

[4.6] Doc for Elasticsearch 8 #3022

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mnocon merged 8 commits into from
Feb 3, 2026
Merged

[4.6] Doc for Elasticsearch 8 #3022

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
310e262
Added doc for ES8
mnocon Jan 21, 2026
c35ecb1
Added update guide mention
mnocon Jan 22, 2026
8176d91
Fixed header
mnocon Jan 22, 2026
8197f42
Formatting fixes
mnocon Jan 22, 2026
26ac574
Apply suggestions from code review
mnocon Jan 26, 2026
af55521
Apply suggestions from code review
mnocon Jan 29, 2026
d2c07e4
Manual changes
mnocon Jan 29, 2026
34d0b28
Merge remote-tracking branch 'origin/release-4.6.27' into es-8-4.6
mnocon Feb 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/getting_started/requirements.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,7 +225,7 @@ For production setups it's recommended that you use Varnish/Fastly, Redis/Valkey
|Name|Version|
|---|---|
|Solr|7.7+, 8.11.1+ or 9.8.1+|
|Elasticsearch| 7.16.2+ |
|Elasticsearch| 7.16.2+ or 8.19+ |

If you see a "+" next to the product version, it indicates a recommended version or higher within the same major release.
For example, "1.18+" means any 1.x version equal to or higher than 1.18, but not 2.x.
Expand Down
214 changes: 158 additions & 56 deletions docs/search/search_engines/elasticsearch/configure_elasticsearch.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,40 +108,62 @@

When you configure a cluster-based connection, and the cluster consists of many nodes, you can choose strategies that govern how the cluster reacts to changing operating conditions, or how workload is distributed among the nodes.

#### Connection pool
#### Connection pool and Node pool settings

With this setting you decide how a list of hosts that form a cluster is managed.
The list of active hosts tends to change in time, due to different reasons, such as connectivity issues, host malfunction, or the fact that you add new hosts to the cluster to increase its performance.
By default, the `StaticNoPingConnectionPool` setting is used.
The way you configure cluster node management depends on which Elasticsearch version you're using.

You can change the default setting with the following key:
=== "Elasticsearch 7"

``` yaml
<connection_name>:
# ...
connection_pool: Elasticsearch\ConnectionPool\<connection_pool_name>
```
With this setting you decide how a list of hosts that form a cluster is managed.
The list of active hosts tends to change in time, due to different reasons, such as connectivity issues, host malfunction, or the fact that you add new hosts to the cluster to increase its performance.
By default, the `StaticNoPingConnectionPool` setting is used.

You can change the default setting with the following key:

``` yaml
<connection_name>:
# ...
connection_pool: Elasticsearch\ConnectionPool\<connection_pool_name>
```

When the cluster consists of many hosts, the `connection_selector` setting decides what strategy is used to pick a node to send query requests to.
By default, the `RoundRobinSelector` setting is used.

For more information and a list of available choices, see [Connection pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connection_pool.html).
If you prefer a different strategy, or have created your own, custom strategy, you can change the default setting with the following key:

!!! tip "Load tests recommendation"
``` yaml
<connection_name>:
# ...
connection_selector: Elasticsearch\ConnectionPool\Selectors\<selector_name>
```

If you change the connection pool setting, it's recommended that you to perform load tests to check whether the change doesn't negatively impact the performance of your environment.
For more information and a list of available choices, see [Connection pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connection_pool.html) and [Selectors](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/selectors.html).

#### Connection selector
!!! tip "Load tests recommendation"

When the cluster consists of many hosts, the `connection_selector` setting decides what strategy is used to pick a node to send query requests to.
By default, the `RoundRobinSelector` setting is used.
If you change the connection pool setting, it's recommended that you perform load tests to check whether the change doesn't negatively impact the performance of your environment.

If you prefer a different strategy, or have created your own, custom strategy, you can change the default setting with the following key:
=== "Elasticsearch 8"

``` yaml
<connection_name>:
# ...
connection_selector: Elasticsearch\ConnectionPool\Selectors\<selector_name>
```
With these settings you decide how nodes in the cluster are selected and how failed nodes are resurrected.
The node pool manages the list of active nodes, which can change over time due to connectivity issues, host malfunction, or when you add new nodes to the cluster to increase performance.

By default, Elasticsearch uses the `SimpleNodePool` algorithm with `RoundRobin` selector and `NoResurrect` strategy.

You can customize the node pool behavior with the following settings:

``` yaml
<connection_name>:
# ...
node_pool_selector: Elastic\Transport\NodePool\Selector\RoundRobin
node_pool_resurrect: Elastic\Transport\NodePool\Resurrect\NoResurrect
```

For more information and a list of available choices, see [Node pool](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/node_pool.html).

!!! tip "Load tests recommendation"

For more information and a list of available choices, see [Selectors](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/selectors.html).
If you change the node pool settings, it's recommended that you perform load tests to check whether the change doesn't negatively impact the performance of your environment.

##### Number of retries

Expand All @@ -154,9 +176,12 @@
retries: null
```

Depending on the connection pool that you select, [[= product_name =]]'s reaction to reaching the maximum number of retries might differ.
Depending on the connection pool/node pool that you select, [[= product_name =]]'s reaction to reaching the maximum number of retries might differ.

For more information, see [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/set-retries.html).
For more information, see:

- Elasticsearch 7: [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/set-retries.html)
- Elasticsearch 8: [Set retries](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/set-retries.html)

## Configure Elasticsearch Cloud

Expand Down Expand Up @@ -216,33 +241,92 @@
### API key authentication

If your Elasticsearch cluster is protected by API keys, you must provide the key and secret in authentication configuration to connect [[= product_name =]] with the cluster.
With API key authentication you can define different authorization levels, such as [`create_index` or `index`](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-privileges.html#privileges-list-indices).
With API key authentication you can define different authorization levels, such as `create_index` or `index`.
Such approach proves useful if the cluster is available to the public.

For more information, see [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html).
For more information, see:

When using API key authentication, you must pass the following parameters to authenticate access to the cluster:
- Elasticsearch 7: [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-api-create-api-key.html) and [Security privileges](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/security-privileges.html#privileges-list-indices)
- Elasticsearch 8: [Create API key](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-create-api-key.html) and [Security privileges](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-privileges.html#privileges-list-indices)

``` yaml
<connection_name>:
# ...
authentication:
type: api_key
credentials: ['<api_key>', '<api_secret>']
```
=== "Elasticsearch 7"

For example:
When using API key authentication with Elasticsearch 7, you must pass the following parameters to authenticate access to the cluster:

``` yaml
ibexa_elasticsearch:
connections:
cloud:
debug: true
elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ'
authentication:
type: api_key
credentials: ['8Ek5f3IBGQlWj6v4M7zG', 'rmI6IechSnSJymWJ4LZqUw']
```
``` yaml
<connection_name>:
# ...
authentication:
type: api_key
credentials: ['<api_key>', '<api_secret>']
```

For example:

``` yaml
ibexa_elasticsearch:
connections:
cloud:
debug: true
elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ'
authentication:
type: api_key
credentials: ['8Ek5f3IBGQlWj6v4M7zG', 'rmI6IechSnSJymWJ4LZqUw']
```

=== "Elasticsearch 8"

When using API key authentication with Elasticsearch 8, you can pass either the API key and key ID pair, or the encoded API key value:
Comment thread
mnocon marked this conversation as resolved.
Outdated

**Using API key and key ID:**

``` yaml
<connection_name>:
# ...
authentication:
type: api_key
credentials: ['<api_key>', '<api_key_id>']
```

For example:

``` yaml
ibexa_elasticsearch:
connections:
cloud:
debug: true
elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ'
authentication:
type: api_key
credentials: ['ui2lp2axTNmsyakw9tvNnw', 'VuaCfGcBCdbkQm-e5aOx']
```

**Using encoded API key:**

Alternatively, pass the encoded API key value, which Elasticsearch also calls "API key credentials":

Comment thread
mnocon marked this conversation as resolved.
Outdated
``` yaml
<connection_name>:
# ...
authentication:
type: api_key
credentials: ['<api_key_encoded>']
```

For example:

``` yaml
ibexa_elasticsearch:
connections:
cloud:
debug: true
elastic_cloud_id: 'test:ZWFzdHVzMi5henVyZS5lbGFzdGljLWNsb3VkLmNvbTo5MjQzJGUwZ'
authentication:
type: api_key
credentials: ['VnVhQ2ZHY0JDZGJrUW0tZTVhT3g6dWkybHAyYXhUTm1zeWFrdzl0dk5udw==']
```

Refer to the [examples in Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/security-api-create-api-key.html#security-api-create-api-key-example) to see the difference between API key, API key id, and encoded API key.
Comment thread
mnocon marked this conversation as resolved.
Outdated

### SSL

Expand Down Expand Up @@ -292,24 +376,27 @@
verification: false
```

For more information, see [Elasticsearch: SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connceting.html#ssl-encryption).
For more information, see:

- Elasticsearch 7: [SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/7.x/connceting.html#ssl-encryption)
- Elasticsearch 8: [SSL Encryption](https://www.elastic.co/guide/en/elasticsearch/client/php-api/8.19/connecting.html#ssl-encryption)
Copy link
Copy Markdown
Contributor

@dabrt dabrt Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Dead link

Comment thread
mnocon marked this conversation as resolved.
Outdated

### Enable debugging

In a staging environment, you can log messages about the status of communication with Elasticsearch.
You can then use Symfony Profiler to review the logs.

By default, debugging is disabled. To enable debugging, you can toggle either of the following two settings:
By default, debugging is disabled. To enable debugging, you can use the following settings:
Comment thread
mnocon marked this conversation as resolved.
Outdated

``` yaml
<connection_name>:
# ...
debug: <true/false>
trace: <true/false>
trace: <true/false> # Elasticsearch 7 only
```

- `debug` logs basic information about a request, such as request status and time.
- `trace` logs additional information, such as steps to reproduce an exact copy of a query.
- `trace` logs additional information, such as steps to reproduce an exact copy of a query. Available only for Elasticsearch 7.

Check failure on line 399 in docs/search/search_engines/elasticsearch/configure_elasticsearch.md

View workflow job for this annotation

GitHub Actions / vale

[vale] docs/search/search_engines/elasticsearch/configure_elasticsearch.md#L399 

[Ibexa.Lists] Do not put fullstops at the end of bullets
Raw output 
{"message": "[Ibexa.Lists] Do not put fullstops at the end of bullets", "location": {"path": "docs/search/search_engines/elasticsearch/configure_elasticsearch.md", "range": {"start": {"line": 399, "column": 91}}}, "severity": "ERROR"}

!!! tip

Expand Down Expand Up @@ -370,7 +457,10 @@

- `settings` - Settings under this key control all aspects related to an index.

For more information and a list of available settings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings).
For more information and a list of available settings, see:

- Elasticsearch 7: [Index modules](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/index-modules.html#index-modules-settings)
- Elasticsearch 8: [Index modules](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/index-modules.html#index-modules-settings)

For example, you can define settings that convert text into a format that is optimized for search, like a normalizer that changes a case of all phrases in the index:

Expand All @@ -392,7 +482,10 @@

- `mappings` - Settings under this key define mapping for fields in the index.

For more information about mappings, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping.html).
For more information about mappings, see:

- Elasticsearch 7: [Mapping](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping.html)
- Elasticsearch 8: [Mapping](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/mapping.html)
Copy link
Copy Markdown
Contributor

@dabrt dabrt Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would this section need to be indented?


When you create a custom index template, with settings for your own field and document types, make sure that it contains mappings for all searchable fields that are available in [[= product_name =]].
For an example of default configuration with a list of searchable fields.
Copy link
Copy Markdown
Contributor

@dabrt dabrt Jan 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

And it seems like this paragraph does not have to be indented as it relates to the introductory one.

Expand All @@ -401,7 +494,10 @@
### Fine-tune the search results

Your search results can be adjusted by configuring additional parameters.
For a list of available mapping parameters and their usage, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping-params.html).
For a list of available mapping parameters and their usage, see:

- Elasticsearch 7: [Mapping parameters](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/mapping-params.html)
- Elasticsearch 8: [Mapping parameters](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/mapping-params.html)

For example, you can apply a mapping parameter, in this case, a normalizer, to a specific mapping under the `dynamic_templates` key:

Expand Down Expand Up @@ -487,9 +583,12 @@

#### Create config for language specific analyzer

For information about configuring an analyzer for each specific language, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html).
For information about configuring an analyzer for each specific language, see:

An adoption of the [English analyzer](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html#english-analyzer) in [[= product_name =]] configuration looks like this:
- Elasticsearch 7: [Language analyzers](https://www.elastic.co/guide/en/elasticsearch/reference/7.17/analysis-lang-analyzer.html)
- Elasticsearch 8: [Language analyzers](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/analysis-lang-analyzer.html)

An adoption of the English analyzer in [[= product_name =]] configuration looks like this:
Comment thread
mnocon marked this conversation as resolved.
Outdated

```yaml hl_lines="3-5 15-23 35 41-52 94 99"
[[= include_file('code_samples/search/custom/config/packages/elasticsearch-en.yaml') =]]
Expand Down Expand Up @@ -519,7 +618,10 @@
- ger_de
```

For more information about how Elasticsearch handles settings and mappings from multiple templates that match the same index, see [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/indices-templates-v1.html#multiple-templates-v1).
For more information about how Elasticsearch handles settings and mappings from multiple templates that match the same index, see:

- Elasticsearch 7: [Multiple templates](https://www.elastic.co/guide/en/elasticsearch/reference/7.x/indices-templates-v1.html#multiple-templates-v1)
- Elasticsearch 8: [Index templates](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/index-templates.html)

# Extend Elasticsearch

Expand Down
6 changes: 4 additions & 2 deletions docs/search/search_engines/elasticsearch/elasticsearch_overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,10 @@ As a result of having distributed architecture, Elasticsearch can analyze massiv
Instead of searching text directly, it searches and index.
Thanks to this mechanism, it's able to achieve fast response.

For a detailed description of advanced settings that you might require in a specific production environment, see the documentation provided by Elastic.
Start with the [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/setup.html) section.
For a detailed description of advanced settings that you might require in a specific production environment, see the documentation provided by Elastic:

- Elasticsearch 7: [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.7/setup.html)
- Elasticsearch 8: [Set up Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/8.19/setup.html)

**Prerequisite**

Expand Down
Loading