JAVA Elasticsearch 聚合报错？Fielddata 与 doc_values 策略讲解

大家好！今天我们来聊聊在使用 Java 和 Elasticsearch 进行聚合操作时，经常遇到的一个问题，以及解决这个问题的关键：fielddata 和 doc_values。很多开发者在使用 Elasticsearch 聚合功能时，会遇到类似下面的错误：

"type": "illegal_argument_exception",
"reason": "Fielddata is disabled on text fields by default. Set fielddata=true on [your_field] in order to load fielddata in memory directly."

或者

"type": "illegal_argument_exception",
"reason": "doc_values is disabled on field [your_field]"

这些错误表明 Elasticsearch 在尝试对某个字段进行聚合操作时，无法找到对应的数据结构来高效地完成任务。那么，fielddata 和 doc_values 到底是什么？它们在聚合操作中扮演什么角色？为什么会出现这些错误？又该如何解决呢？接下来，我们将会深入探讨这些问题。

Elasticsearch 聚合的工作原理

在深入 fielddata 和 doc_values 之前，理解 Elasticsearch 聚合的工作原理至关重要。简单来说，聚合就是对数据进行分组、统计和分析的过程。 Elasticsearch 提供了丰富的聚合类型，例如：

Metric Aggregations: 计算字段的统计指标，如 min, max, avg, sum 等。
Bucket Aggregations: 将文档分组到不同的桶中，如 terms, range, date_histogram 等。
Pipeline Aggregations: 对其他聚合的结果进行处理，如 avg_bucket, sum_bucket 等。

为了高效地执行聚合操作，Elasticsearch 需要能够快速地访问和处理字段的值。这就需要特定的数据结构来支持。在 Elasticsearch 中，主要有两种数据结构用于聚合和排序：fielddata 和 doc_values。

Fielddata：内存中的倒排索引

fielddata 是一种基于内存的数据结构，用于支持对文本字段进行聚合、排序和脚本操作。传统上，倒排索引是为搜索而设计的，它将词项映射到包含这些词项的文档 ID。然而，聚合和排序需要相反的操作：需要根据文档 ID 查找字段的值。

fielddata 通过在内存中构建一个反向的倒排索引来实现这一点。它将文档 ID 映射到该文档中包含的词项列表。这种结构允许 Elasticsearch 快速地访问每个文档的字段值，从而加速聚合和排序操作。

Fielddata 的优缺点：

优点： 能够支持文本字段上的聚合和排序。
缺点： 消耗大量内存，尤其是在处理高基数（大量不同的值）的文本字段时。构建 fielddata 的过程可能会很慢，并且可能导致 JVM 垃圾回收压力增大。

何时使用 Fielddata？

fielddata 主要用于以下情况：

需要对 text 类型的字段进行聚合或排序。
性能不是首要考虑因素，或者数据量较小，内存足够。
需要使用脚本来访问字段值。

如何启用 Fielddata？

默认情况下，fielddata 在 text 类型的字段上是禁用的。要启用 fielddata，需要在字段映射中设置 fielddata=true。

示例：启用 Fielddata

假设我们有一个名为 products 的索引，其中包含一个 description 字段，其类型为 text。要启用 description 字段的 fielddata，可以执行以下操作：

PUT products/_mapping
{
  "properties": {
    "description": {
      "type": "text",
      "fielddata": true
    }
  }
}

注意事项：

启用 fielddata 之前，请务必评估其对内存的影响。可以使用 Elasticsearch 的 Field Data Stats API 来监控 fielddata 的使用情况。

GET /_stats/fielddata

Java 代码示例：

import org.elasticsearch.action.admin.indices.mapping.put.PutMappingRequest;
import org.elasticsearch.client.RequestOptions;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.common.xcontent.XContentBuilder;
import org.elasticsearch.common.xcontent.XContentFactory;
import java.io.IOException;

public class FielddataExample {

    public static void enableFielddata(RestHighLevelClient client, String indexName, String fieldName) throws IOException {
        PutMappingRequest request = new PutMappingRequest(indexName);

        XContentBuilder builder = XContentFactory.jsonBuilder();
        builder.startObject();
        {
            builder.startObject("properties");
            {
                builder.startObject(fieldName);
                {
                    builder.field("type", "text");
                    builder.field("fielddata", true);
                }
                builder.endObject();
            }
            builder.endObject();
        }
        builder.endObject();

        request.source(builder);

        client.indices().putMapping(request, RequestOptions.DEFAULT);
    }

    public static void main(String[] args) throws IOException {
        // Replace with your Elasticsearch client initialization
        RestHighLevelClient client = new RestHighLevelClient(
                // ... your client configuration
        );

        String indexName = "products";
        String fieldName = "description";

        enableFielddata(client, indexName, fieldName);

        client.close();
    }
}

Doc_values：磁盘上的列式存储

doc_values 是一种基于磁盘的列式存储结构，用于支持对结构化数据进行聚合、排序和脚本操作。与 fielddata 不同，doc_values 在索引时构建，并存储在磁盘上。这使得 doc_values 能够处理大量数据，而不会对内存造成过大的压力。

Doc_values 的优缺点：

优点： 节省内存，能够处理大量数据。
缺点： 只能用于结构化数据类型（如 keyword, numeric, date, boolean 等）。对文本字段无效。访问速度比 fielddata 慢，因为需要从磁盘读取数据。

何时使用 Doc_values？

doc_values 是聚合和排序的首选数据结构，尤其是在以下情况下：

需要对结构化数据类型进行聚合或排序。
数据量很大，内存有限。
性能要求较高。

如何启用 Doc_values？

默认情况下，doc_values 在所有支持的字段类型上都是启用的。要禁用 doc_values，需要在字段映射中设置 doc_values=false。

示例：禁用 Doc_values

PUT products/_mapping
{
  "properties": {
    "price": {
      "type": "double",
      "doc_values": false
    }
  }
}

注意事项：

禁用 doc_values 会阻止对该字段进行聚合和排序。除非有充分的理由，否则不建议禁用 doc_values。

Java 代码示例：

import org.elasticsearch.action.admin.indices.mapping.put.PutMappingRequest;
import org.elasticsearch.client.RequestOptions;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.common.xcontent.XContentBuilder;
import org.elasticsearch.common.xcontent.XContentFactory;

import java.io.IOException;

public class DocValuesExample {

    public static void disableDocValues(RestHighLevelClient client, String indexName, String fieldName) throws IOException {
        PutMappingRequest request = new PutMappingRequest(indexName);

        XContentBuilder builder = XContentFactory.jsonBuilder();
        builder.startObject();
        {
            builder.startObject("properties");
            {
                builder.startObject(fieldName);
                {
                    builder.field("type", "double");
                    builder.field("doc_values", false);
                }
                builder.endObject();
            }
            builder.endObject();
        }
        builder.endObject();

        request.source(builder);

        client.indices().putMapping(request, RequestOptions.DEFAULT);
    }

    public static void main(String[] args) throws IOException {
        // Replace with your Elasticsearch client initialization
        RestHighLevelClient client = new RestHighLevelClient(
                // ... your client configuration
        );

        String indexName = "products";
        String fieldName = "price";

        disableDocValues(client, indexName, fieldName);

        client.close();
    }
}

解决聚合报错：选择合适的策略

现在我们回到最初的问题：如何解决聚合报错？答案在于选择合适的策略：

对于 text 类型的字段：
- 如果需要聚合或排序，并且数据量较小，内存足够： 启用 fielddata。
- 如果需要聚合或排序，但数据量很大，内存有限： 考虑使用 keyword 类型的字段，或者使用 text 字段的多字段特性，创建一个 keyword 类型的子字段。
```
PUT products/_mapping
{
  "properties": {
    "description": {
      "type": "text",
      "fields": {
        "keyword": {
          "type": "keyword",
          "ignore_above": 256 // 限制 keyword 字段的最大长度
        }
      }
    }
  }
}
```
然后，对 description.keyword 字段进行聚合。
对于其他类型的字段：
- 确保 doc_values 是启用的。 如果由于某种原因禁用了 doc_values，请重新启用它。
- 检查字段类型是否正确。 例如，如果需要对数字字段进行聚合，确保该字段的类型是 integer, long, float 或 double。

常见错误场景和解决方案：

错误信息	字段类型	原因	解决方案
`Fielddata is disabled on text fields by default. Set fielddata=true on [your_field] in order to load fielddata in memory directly.`	`text`	默认情况下，`text` 类型的字段禁用 `fielddata`，以防止内存占用过高。	1. 如果数据量小，可以启用 `fielddata`。 2. 推荐使用 `keyword` 类型的字段，或者为 `text` 字段创建一个 `keyword` 类型的子字段。
`doc_values is disabled on field [your_field]`	其他	`doc_values` 被显式禁用。	启用 `doc_values`。
聚合结果不准确	`text`	使用 `fielddata` 进行聚合时，如果文本字段包含大量不同的词项，可能会导致结果不准确。	使用 `keyword` 类型的字段进行聚合，或者使用 `text` 字段的多字段特性。此外，确保使用合适的分析器，将文本分解为有意义的词项。
`Fielddata loading is forbidden on indices that have [index.fielddata.memory.circuit_breaker.enabled] set to true because it estimates that the amount of heap needed to load the fielddata would be greater than the limit`	`text`	Elasticsearch 的断路器阻止加载 fielddata，因为它估计加载 fielddata 所需的堆内存量将大于限制。这是为了防止 OOM 错误。	1. 优化查询，减少需要加载的 fielddata 量。 2. 增加 Elasticsearch 的堆内存大小。 3. 考虑使用 keyword 类型的字段替代 text 字段。

代码示例：聚合操作

下面是一个使用 Java 和 Elasticsearch 进行聚合操作的示例：

import org.elasticsearch.action.search.SearchRequest;
import org.elasticsearch.action.search.SearchResponse;
import org.elasticsearch.client.RequestOptions;
import org.elasticsearch.client.RestHighLevelClient;
import org.elasticsearch.index.query.QueryBuilders;
import org.elasticsearch.search.aggregations.AggregationBuilders;
import org.elasticsearch.search.aggregations.bucket.terms.Terms;
import org.elasticsearch.search.builder.SearchSourceBuilder;

import java.io.IOException;

public class AggregationExample {

    public static void main(String[] args) throws IOException {
        // Replace with your Elasticsearch client initialization
        RestHighLevelClient client = new RestHighLevelClient(
                // ... your client configuration
        );

        String indexName = "products";
        String fieldName = "category";

        SearchRequest searchRequest = new SearchRequest(indexName);
        SearchSourceBuilder searchSourceBuilder = new SearchSourceBuilder();
        searchSourceBuilder.query(QueryBuilders.matchAllQuery());
        searchSourceBuilder.aggregation(AggregationBuilders.terms("categories").field(fieldName));
        searchRequest.source(searchSourceBuilder);

        SearchResponse searchResponse = client.search(searchRequest, RequestOptions.DEFAULT);

        Terms aggregation = searchResponse.getAggregations().get("categories");

        for (Terms.Bucket bucket : aggregation.getBuckets()) {
            System.out.println("Category: " + bucket.getKeyAsString() + ", Count: " + bucket.getDocCount());
        }

        client.close();
    }
}

在这个例子中，我们对 products 索引的 category 字段进行聚合，统计每个类别的商品数量。请确保 category 字段的类型为 keyword，或者已经启用了 doc_values。

深度思考：性能优化

fielddata 和 doc_values 的选择直接影响 Elasticsearch 的性能。以下是一些性能优化建议：

避免在 text 类型的字段上启用 fielddata，除非绝对必要。
尽可能使用 keyword 类型的字段进行聚合和排序。
监控 fielddata 的使用情况，并根据需要调整内存设置。
使用缓存来减少磁盘 I/O。 Elasticsearch 提供了多种缓存机制，例如节点查询结果缓存和请求缓存。
合理设置 Elasticsearch 的堆内存大小。 堆内存过小会导致频繁的垃圾回收，影响性能。堆内存过大则会浪费资源。
优化查询语句，减少需要处理的数据量。

总结：选择策略，避免错误

理解 fielddata 和 doc_values 的作用对于解决 Elasticsearch 聚合报错至关重要。正确选择数据结构，并根据实际情况进行配置，可以有效地避免错误，提高 Elasticsearch 的性能。

使用合适的数据结构，优化查询性能

选择 fielddata 还是 doc_values 取决于字段类型和数据量。优化查询语句可以减少需要处理的数据量，从而提高性能。

持续监控和调整，确保稳定运行

监控 fielddata 的使用情况，并根据需要调整内存设置。合理设置 Elasticsearch 的堆内存大小，确保系统稳定运行。