---
title: "文档计数"
date: 2026-02-10
lastmod: 2026-02-10
description: "获取匹配查询条件的文档数量"
tags: ["搜索", "计数", "查询"]
summary: "获取匹配查询条件的文档数量，不返回实际的文档内容。
API #  GET /_count POST /_count GET /{index}/_count POST /{index}/_count API 的作用 #  该 API 用于获取匹配查询条件的文档数量。
Count API vs Search API #     API 返回内容 性能     /_count 只返回文档数量 更快   /_search 返回文档数量 + 文档内容 较慢    Count API 的优势 #   更快：不获取文档内容，只计算数量 更少带宽：响应更小 更少内存：不需要存储和返回文档  API 的参数 #  路由参数 #     参数 类型 是否必填 描述     {index} 字符串 否 索引名称。支持：单个索引、逗号分隔的多个索引、通配符表达式、_all（所有索引）    Query String 参数 #     参数 类型 是否必填 默认值 描述     q 字符串 否 - Lucene 查询语法查询字符串   df 字符串 否 - 默认字段名   analyzer 字符串 否 - 查询使用的分析器   analyze_wildcard 布尔值 否 false 是否分析通配符   lenient 布尔值 否 false 是否忽略查询解析错误   default_operator 字符串 否 OR 默认操作符：OR、AND   routing 字符串 否 - 路由值   preference 字符串 否 - 分片偏好设置   min_score 浮点数 否 - 最小分数阈值   terminate_after 整数 否 0 在达到指定数量的文档后终止查询   timeout 时间值 否 - 查询超时时间    请求体参数（POST） #  { "query": { ."
---


获取匹配查询条件的文档数量，不返回实际的文档内容。

## API

```
GET /_count
POST /_count
GET /{index}/_count
POST /{index}/_count
```

## API 的作用

该 API 用于获取匹配查询条件的文档数量。

### Count API vs Search API

| API | 返回内容 | 性能 |
|-----|----------|------|
| `/_count` | 只返回文档数量 | 更快 |
| `/_search` | 返回文档数量 + 文档内容 | 较慢 |

### Count API 的优势

- **更快**：不获取文档内容，只计算数量
- **更少带宽**：响应更小
- **更少内存**：不需要存储和返回文档

## API 的参数

### 路由参数

| 参数 | 类型 | 是否必填 | 描述 |
|------|------|----------|------|
| `{index}` | 字符串 | 否 | 索引名称。支持：单个索引、逗号分隔的多个索引、通配符表达式、`_all`（所有索引） |

### Query String 参数

| 参数 | 类型 | 是否必填 | 默认值 | 描述 |
|------|------|----------|--------|------|
| `q` | 字符串 | 否 | - | Lucene 查询语法查询字符串 |
| `df` | 字符串 | 否 | - | 默认字段名 |
| `analyzer` | 字符串 | 否 | - | 查询使用的分析器 |
| `analyze_wildcard` | 布尔值 | 否 | false | 是否分析通配符 |
| `lenient` | 布尔值 | 否 | false | 是否忽略查询解析错误 |
| `default_operator` | 字符串 | 否 | OR | 默认操作符：`OR`、`AND` |
| `routing` | 字符串 | 否 | - | 路由值 |
| `preference` | 字符串 | 否 | - | 分片偏好设置 |
| `min_score` | 浮点数 | 否 | - | 最小分数阈值 |
| `terminate_after` | 整数 | 否 | 0 | 在达到指定数量的文档后终止查询 |
| `timeout` | 时间值 | 否 | - | 查询超时时间 |

### 请求体参数（POST）

```json
{
  "query": { ... },
  "min_score": 1.0,
  "terminate_after": 1000
}
```

## 示例

### 获取所有文档数量

```bash
GET /my_index/_count
```

**响应示例：**

```json
{
  "count": 1000,
  "_shards": {
    "total": 5,
    "successful": 5,
    "skipped": 0,
    "failed": 0
  }
}
```

### 使用查询字符串

```bash
GET /my_index/_count?q=status:published
```

### 使用查询 DSL

```bash
POST /my_index/_count
{
  "query": {
    "term": {
      "status": "published"
    }
  }
}
```

### 布尔查询

```bash
POST /my_index/_count
{
  "query": {
    "bool": {
      "must": [
        { "match": { "title": "search" } }
      ],
      "filter": [
        { "term": { "status": "active" } },
        { "range": { "created_at": { "gte": "2026-01-01" } } }
      ]
    }
  }
}
```

### 范围查询

```bash
POST /products/_count
{
  "query": {
    "range": {
      "price": {
        "gte": 10,
        "lte": 100
      }
    }
  }
}
```

### 多索引计数

```bash
GET /index1,index2/_count
```

### 使用通配符

```bash
GET /logs-*/_count
{
  "query": {
    "term": {
      "level": "ERROR"
    }
  }
}
```

### 设置最小分数

```bash
POST /my_index/_count
{
  "min_score": 2.0,
  "query": {
    "match": {
      "title": "important"
    }
  }
}
```

### 限制计算数量

```bash
POST /my_index/_count
{
  "terminate_after": 100,
  "query": {
    "match_all": {}
  }
}
```

**响应示例：**

```json
{
  "count": 100,
  "terminated_early": true,
  "_shards": { ... }
}
```

### 使用路由

```bash
GET /my_index/_count?routing=user1
```

### 设置超时

```bash
GET /my_index/_count?timeout=5s
```

### 宽松模式

```bash
GET /my_index/_count?lenient=true
```

## 响应字段说明

| 字段 | 描述 |
|------|------|
| `count` | 匹配的文档总数 |
| `terminated_early` | 是否提前终止（使用 `terminate_after` 时） |
| `_shards.total` | 总分片数 |
| `_shards.successful` | 成功的分片数 |
| `_shards.failed` | 失败的分片数 |
| `_shards.skipped` | 跳过的分片数 |

## 使用场景

### 场景 1：统计文档数量

```bash
GET /logs/_count
{
  "query": {
    "term": { "level": "ERROR" }
  }
}
```

### 场景 2：监控数据量

```bash
GET /metrics-*/_count
{
  "query": {
    "range": {
      "@timestamp": {
        "gte": "now-1d"
      }
    }
  }
}
```

### 场景 3：条件统计

```bash
POST /orders/_count
{
  "query": {
    "bool": {
      "must": [
        { "term": { "status": "completed" } }
      ],
      "filter": [
        { "range": { "total": { "gte": 100 } } }
      ]
    }
  }
}
```

### 场景 4：快速计数

```bash
# 使用查询字符串快速计数
GET /my_index/_count?q=title:easysearch
```

## 计数精度

| track_total_hits 设置 | 说明 |
|---------------------|------|
| `true`（默认） | 精确计数，最多 10,000 |
| `false` | 优化性能，可能不精确 |
| 整数 N | 精确到 10,000，之后优化 |

对于大型索引，考虑使用聚合来获取精确计数：

```json
{
  "size": 0,
  "aggs": {
    "total_count": {
      "cardinality": {
        "script": {
          "source": "doc['_id'].value"
        }
      }
    }
  }
}
```

## 错误处理

### 索引不存在

```json
{
  "error": {
    "type": "index_not_found_exception",
    "reason": "no such index [my_index]"
  },
  "status": 404
}
```

### 查询语法错误

```bash
GET /my_index/_count?q=title:[to
```

**响应（lenient=false）：**

```json
{
  "error": {
    "type": "search_parse_exception"
  },
  "status": 400
}
```

## 性能考虑

| 操作 | 性能影响 |
|------|----------|
| `terminate_after` | 显著提高性能，提前终止 |
| 简单查询 | 较快 |
| 复杂布尔查询 | 较慢 |
| 大范围查询 | 较慢 |

## 注意事项

1. **精确计数限制**：默认最多准确计数到 10,000
2. **大索引**：使用聚合获取精确计数
3. **实时性**：计数是近实时的
4. **类型已弃用**：有类型的 API 已被弃用