From c4e272a7f2ee4e8cb9361a5b71359149509335d9 Mon Sep 17 00:00:00 2001 From: soyuka Date: Tue, 29 Sep 2026 16:49:06 +0200 Subject: [PATCH 1/2] docs(elasticsearch): document field name mapping Fixes api-platform/core#8470 --- core/elasticsearch.md | 37 +++++++++++++++++++++++++++++++++++-- 1 file changed, 35 insertions(+), 2 deletions(-) diff --git a/core/elasticsearch.md b/core/elasticsearch.md index 89b8abaf7ba..60878d50348 100644 --- a/core/elasticsearch.md +++ b/core/elasticsearch.md @@ -327,8 +327,7 @@ class Tweet } ``` -API Platform will automatically disable write operations and snake_case document fields will -automatically be converted to camelCase object properties during serialization. +API Platform will automatically disable write operations. Keep in mind that it is your responsibility to populate your Elasticsearch index. To do so, you can use [Logstash](https://www.elastic.co/products/logstash), a custom @@ -337,6 +336,40 @@ that suits your project (such as an [ETL](https://en.wikipedia.org/wiki/Extract, You're done! The API is now ready to use. +### Mapping Field Names + +By default, API Platform does not convert Elasticsearch document field names: a `_source` field is mapped to the +object property of the same name (unless [`#[SerializedName]`](serialization.md) is used). Use camelCase field names in your +mappings, as described above. + +If your documents use snake_case field names, configure a name converter so that they are mapped to camelCase +properties. There are two options. + +To convert names for every format, set the global `name_converter` in the API Platform configuration. This also changes +the serialization of all other formats: + +```yaml +# api/config/packages/api_platform.yaml +api_platform: + name_converter: 'serializer.name_converter.camel_case_to_snake_case' +``` + +To convert names for Elasticsearch only, override the `api_platform.elasticsearch.name_converter.inner_fields` service +and pass it the converter: + +```yaml +# api/config/services.yaml +services: + api_platform.elasticsearch.name_converter.inner_fields: + class: ApiPlatform\Elasticsearch\Serializer\NameConverter\InnerFieldsNameConverter + arguments: + - '@serializer.name_converter.camel_case_to_snake_case' +``` + +> [!WARNING] +> The same name converter builds the field names used by the Elasticsearch filters and by sorting. Once a converter is +> set, a filter or sort on the `firstName` property targets the `first_name` field of the index. + ## Filtering See how to use Elasticsearch filters and how to create Elasticsearch custom filters in the From 28f2b93e652cebbb40db2e67d06d62c812f67165 Mon Sep 17 00:00:00 2001 From: soyuka Date: Wed, 30 Sep 2026 08:58:23 +0200 Subject: [PATCH 2/2] docs(elasticsearch): apply prettier --- core/elasticsearch.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/core/elasticsearch.md b/core/elasticsearch.md index 60878d50348..13df2a89410 100644 --- a/core/elasticsearch.md +++ b/core/elasticsearch.md @@ -338,24 +338,24 @@ You're done! The API is now ready to use. ### Mapping Field Names -By default, API Platform does not convert Elasticsearch document field names: a `_source` field is mapped to the -object property of the same name (unless [`#[SerializedName]`](serialization.md) is used). Use camelCase field names in your -mappings, as described above. +By default, API Platform does not convert Elasticsearch document field names: a `_source` field is +mapped to the object property of the same name (unless [`#[SerializedName]`](serialization.md) is +used). Use camelCase field names in your mappings, as described above. -If your documents use snake_case field names, configure a name converter so that they are mapped to camelCase -properties. There are two options. +If your documents use snake_case field names, configure a name converter so that they are mapped to +camelCase properties. There are two options. -To convert names for every format, set the global `name_converter` in the API Platform configuration. This also changes -the serialization of all other formats: +To convert names for every format, set the global `name_converter` in the API Platform +configuration. This also changes the serialization of all other formats: ```yaml # api/config/packages/api_platform.yaml api_platform: - name_converter: 'serializer.name_converter.camel_case_to_snake_case' + name_converter: "serializer.name_converter.camel_case_to_snake_case" ``` -To convert names for Elasticsearch only, override the `api_platform.elasticsearch.name_converter.inner_fields` service -and pass it the converter: +To convert names for Elasticsearch only, override the +`api_platform.elasticsearch.name_converter.inner_fields` service and pass it the converter: ```yaml # api/config/services.yaml @@ -363,12 +363,12 @@ services: api_platform.elasticsearch.name_converter.inner_fields: class: ApiPlatform\Elasticsearch\Serializer\NameConverter\InnerFieldsNameConverter arguments: - - '@serializer.name_converter.camel_case_to_snake_case' + - "@serializer.name_converter.camel_case_to_snake_case" ``` -> [!WARNING] -> The same name converter builds the field names used by the Elasticsearch filters and by sorting. Once a converter is -> set, a filter or sort on the `firstName` property targets the `first_name` field of the index. +> [!WARNING] The same name converter builds the field names used by the Elasticsearch filters and by +> sorting. Once a converter is set, a filter or sort on the `firstName` property targets the +> `first_name` field of the index. ## Filtering