---
title: "查询缓存配置"
date: 2026-01-07
lastmod: 2026-01-07
description: "控制查询缓存大小的配置项说明"
tags: ["缓存", "查询性能", "内存管理"]
summary: "配置项作用 #  indices.queries.cache.size 配置项控制查询缓存（Query Cache）的 JVM 堆内存大小。查询缓存用于缓存查询结果，提高重复查询的性能。
配置项类型 #  该配置项为动态配置，可以在运行时通过集群设置 API 进行修改。
默认值 #  10%（JVM 堆内存的 10%） 是否必需 #  可选配置项（有默认值）
配置格式 #  # 百分比格式（默认） indices.queries.cache.size: 10% # 字节格式 indices.queries.cache.size: 2gb # 混合格式 indices.queries.cache.size: 20% 配置项列表 #     配置项 默认值 说明     indices.queries.cache.size 10% 缓存大小   indices.queries.cache.count 10000 缓存条目数量   indices.queries.cache.all_segments false 是否缓存所有段    工作原理 #  查询缓存缓存查询结果，当相同的查询再次执行时直接返回缓存结果："
---


## 配置项作用

`indices.queries.cache.size` 配置项控制查询缓存（Query Cache）的 JVM 堆内存大小。查询缓存用于缓存查询结果，提高重复查询的性能。

## 配置项类型

该配置项为**动态配置**，可以在运行时通过集群设置 API 进行修改。

## 默认值

```
10%（JVM 堆内存的 10%）
```

## 是否必需

**可选配置项**（有默认值）

## 配置格式

```yaml
# 百分比格式（默认）
indices.queries.cache.size: 10%

# 字节格式
indices.queries.cache.size: 2gb

# 混合格式
indices.queries.cache.size: 20%
```

## 配置项列表

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `indices.queries.cache.size` | 10% | 缓存大小 |
| `indices.queries.cache.count` | 10000 | 缓存条目数量 |
| `indices.queries.cache.all_segments` | false | 是否缓存所有段 |

## 工作原理

查询缓存缓存查询结果，当相同的查询再次执行时直接返回缓存结果：

```
┌─────────────────────────────────────────────────────────┐
│                   查询请求                                │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
            ┌───────────┴───────────┐
            │                       │
        缓存命中              缓存未命中
            │                       │
            ▼                       ▼
    直接返回缓存          执行查询并缓存结果
```

## 使用示例

```yaml
# 默认配置
indices.queries.cache.size: 10%

# 自定义大小
indices.queries.cache.size: 4gb

# 使用百分比
indices.queries.cache.size: 15%

# 禁用缓存
indices.queries.cache.size: 0b
```

## 动态修改

```bash
# 通过 API 动态修改
PUT /_cluster/settings
{
  "transient": {
    "indices.queries.cache.size": "4gb"
  }
}
```

## 推荐设置建议

**生产环境建议**：根据查询模式和数据量设置

| 场景 | 推荐配置 | 说明 |
|-----|---------|------|
| 大量重复查询 | 15-20% | 提高缓存命中率 |
| 查询多样化 | 5-10% | 减少内存占用 |
| 大数据集 | 10-15% | 默认配置 |
| 小内存节点 | 5% 或更小 | 避免内存压力 |

## 缓存效果

**缓存命中率影响：**

| 命中率 | 性能提升 | 内存使用 |
|-------|---------|---------|
| > 80% | 显著提升 | 较高 |
| 50-80% | 明显提升 | 适中 |
| < 50% | 轻微提升 | 较低 |
| < 20% | 几乎无效 | 浪费内存 |

## 相关配置项

| 配置项 | 默认值 | 说明 |
|-------|-------|------|
| `indices.queries.cache.count` | 10000 | 缓存条目数量 |
| `indices.requests.cache.size` | 1% | 请求缓存大小 |
| `indices.queries.cache.all_segments` | false | 缓存所有段 |

## 缓存策略

查询缓存使用 LRU（最近最少使用）淘汰策略：

```
┌─────────────────────────────────────────────────────────┐
│                  LRU 淘汰策略                              │
└─────────────────────────────────────────────────────────┘
                        │
                        ▼
┌───────────────┴───────────────┐
│                               │
    新查询进入                     最少使用的查询被淘汰
    │                               │
    ▼                               ▼
[查询1] [查询2] ... [查询10000]
   ↑                           ↓
 最常用                     最少用
   ↑                           ↓
保留                          淘汰
```

## 查看缓存状态

```bash
# 查看查询缓存统计
GET /_nodes/stats/indices/query_cache?pretty

# 查看特定索引的缓存
GET /my_index/_cache/stats
```

## 常见问题

**问题 1：缓存未生效**

**可能原因：**
1. 查询使用了 `now()` 等随机函数
2. 查询条件包含随机数
3. 查询每次都不同

**解决方案：**
```json
// 避免使用随机查询
{
  "query": {
    "range": {
      "timestamp": {
        "gte": "2024-01-01",
        "lte": "2024-01-31"
      }
    }
  }
}
```

**问题 2：缓存占用内存过多**

**解决方案：**
```bash
# 减小缓存大小
PUT /_cluster/settings
{
  "transient": {
    "indices.queries.cache.size": "5%"
  }
}
```

**问题 3：缓存命中率低**

**解决方案：**
1. 优化查询使其可缓存
2. 增加缓存大小
3. 分析查询模式

## 查询缓存条件

查询结果可以被缓存的必要条件：

1. **查询完全相同**：包括查询条件、排序、聚合等
2. **索引未修改**：缓存期间索引没有数据变更
3. **使用缓存上下文**：查询使用 `request_cache=true`
4. **确定性查询**：不包含随机函数

**示例：**

```json
// 可缓存的查询
GET /my_index/_search?request_cache=true
{
  "query": {
    "term": { "status": "active" }
  }
}

// 不可缓存的查询（使用 now()）
GET /my_index/_search?request_cache=true
{
  "query": {
    "range": {
      "timestamp": {
        "gte": "now-1d"
      }
    }
  }
}
```

## 性能优化建议

**1. 启用请求缓存**

对于重复查询，启用请求缓存：

```json
GET /my_index/_search?request_cache=true
```

**2. 优化查询模式**

```json
// 优化前：每次查询不同
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "now-1h"
      }
    }
  }
}

// 优化后：使用固定时间范围
{
  "query": {
    "bool": {
      "must": [
        {
          "range": {
            "@timestamp": {
              "gte": "2024-01-01T00:00:00",
              "lte": "2024-01-01T01:00:00"
            }
          }
        },
        {
          "term": { "user": "user1" }
        }
      ]
    }
  }
}
```

## 缓存清理

缓存会在以下情况被清理：

1. **段合并**：段合并时缓存失效
2. **索引更新**：文档被修改后相关缓存失效
3. **手动清理**：通过 API 清理

```bash
# 清理特定索引的缓存
POST /my_index/_cache/clear

# 清理所有索引的缓存
POST /_cache/clear
```

## 监控建议

```bash
# 监控缓存统计
GET /_nodes/stats/indices/query_cache?pretty

# 查看 hit/miss 比率
GET /_cat/nodeattrs?v&h=name,*.query_cache*
```

## 注意事项

1. **动态更新**：此配置为动态配置，可在线修改
2. **内存占用**：缓存占用 JVM 堆内存
3. **命中率监控**：建议监控缓存命中率以评估效果
4. **段合并**：段合并会导致缓存失效
5. **合理设置**：根据查询模式和数据特点调整