获取匹配查询条件的文档数量，不返回实际的文档内容。
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": { ... },
"min_score": 1.0,
"terminate_after": 1000
}
示例 #
获取所有文档数量 #
GET /my_index/_count
响应示例：
{
"count": 1000,
"_shards": {
"total": 5,
"successful": 5,
"skipped": 0,
"failed": 0
}
}
使用查询字符串 #
GET /my_index/_count?q=status:published
使用查询 DSL #
POST /my_index/_count
{
"query": {
"term": {
"status": "published"
}
}
}
布尔查询 #
POST /my_index/_count
{
"query": {
"bool": {
"must": [
{ "match": { "title": "search" } }
],
"filter": [
{ "term": { "status": "active" } },
{ "range": { "created_at": { "gte": "2026-01-01" } } }
]
}
}
}
范围查询 #
POST /products/_count
{
"query": {
"range": {
"price": {
"gte": 10,
"lte": 100
}
}
}
}
多索引计数 #
GET /index1,index2/_count
使用通配符 #
GET /logs-*/_count
{
"query": {
"term": {
"level": "ERROR"
}
}
}
设置最小分数 #
POST /my_index/_count
{
"min_score": 2.0,
"query": {
"match": {
"title": "important"
}
}
}
限制计算数量 #
POST /my_index/_count
{
"terminate_after": 100,
"query": {
"match_all": {}
}
}
响应示例：
{
"count": 100,
"terminated_early": true,
"_shards": { ... }
}
使用路由 #
GET /my_index/_count?routing=user1
设置超时 #
GET /my_index/_count?timeout=5s
宽松模式 #
GET /my_index/_count?lenient=true
响应字段说明 #
| 字段 | 描述 |
|---|---|
count | 匹配的文档总数 |
terminated_early | 是否提前终止（使用 terminate_after 时） |
_shards.total | 总分片数 |
_shards.successful | 成功的分片数 |
_shards.failed | 失败的分片数 |
_shards.skipped | 跳过的分片数 |
使用场景 #
场景 1：统计文档数量 #
GET /logs/_count
{
"query": {
"term": { "level": "ERROR" }
}
}
场景 2：监控数据量 #
GET /metrics-*/_count
{
"query": {
"range": {
"@timestamp": {
"gte": "now-1d"
}
}
}
}
场景 3：条件统计 #
POST /orders/_count
{
"query": {
"bool": {
"must": [
{ "term": { "status": "completed" } }
],
"filter": [
{ "range": { "total": { "gte": 100 } } }
]
}
}
}
场景 4：快速计数 #
# 使用查询字符串快速计数
GET /my_index/_count?q=title:easysearch
计数精度 #
| track_total_hits 设置 | 说明 |
|---|---|
true（默认） | 精确计数，最多 10,000 |
false | 优化性能，可能不精确 |
| 整数 N | 精确到 10,000，之后优化 |
对于大型索引，考虑使用聚合来获取精确计数：
{
"size": 0,
"aggs": {
"total_count": {
"cardinality": {
"script": {
"source": "doc['_id'].value"
}
}
}
}
}
错误处理 #
索引不存在 #
{
"error": {
"type": "index_not_found_exception",
"reason": "no such index [my_index]"
},
"status": 404
}
查询语法错误 #
GET /my_index/_count?q=title:[to
响应（lenient=false）：
{
"error": {
"type": "search_parse_exception"
},
"status": 400
}
性能考虑 #
| 操作 | 性能影响 |
|---|---|
terminate_after | 显著提高性能，提前终止 |
| 简单查询 | 较快 |
| 复杂布尔查询 | 较慢 |
| 大范围查询 | 较慢 |
注意事项 #
- 精确计数限制：默认最多准确计数到 10,000
- 大索引：使用聚合获取精确计数
- 实时性：计数是近实时的
- 类型已弃用：有类型的 API 已被弃用
