Elasticsearch API使用指南

Elasticsearch API使用指南

一、Elasticsearch API概述

Elasticsearch API是开发者与Elasticsearch集群交互的核心接口，采用RESTful设计风格，通过HTTP协议传输JSON格式数据。其核心功能覆盖索引管理、文档CRUD、搜索查询、聚合分析、集群监控等场景，支持多语言客户端（如Java、Python），也可直接通过HTTP请求原生调用。

二、基础操作：索引管理

索引是Elasticsearch中存储文档的逻辑容器，类似于数据库中的“表”。

1. 创建索引

通过PUT请求定义索引名称、分片数（number_of_shards）、副本数（number_of_replicas）及字段映射（mappings）。

PUT /products
{
  "settings": {
    "number_of_shards": 3,    # 主分片数（不可修改）
    "number_of_replicas": 1   # 副本分片数（可动态调整）
  },
  "mappings": {
    "properties": {
      "name": { "type": "text" },       # 文本类型（支持全文搜索）
      "price": { "type": "double" },    # 数值类型
      "tags": { "type": "keyword" }     # 关键词类型（精确匹配）
    }
  }
}

2. 删除索引

通过DELETE请求删除整个索引（包括所有文档）。

DELETE /products

3. 查看索引信息

通过GET请求获取索引的设置、映射及状态。

GET /products/_settings, _mappings

三、核心操作：文档CRUD

文档是Elasticsearch中的基本数据单元，以JSON格式存储。

1. 新增文档

• 指定ID：使用PUT请求，若ID已存在则覆盖。

  PUT /products/_doc/1
  {
    "name": "Elasticsearch Guide",
    "price": 45.99,
    "tags": ["search", "database"]
  }
  

• 自动生成ID：使用POST请求，适合不需要固定ID的场景。

  POST /products/_doc
  {
    "name": "Advanced Elasticsearch",
    "price": 59.99
  }
  

2. 查询文档

• 全量查询：获取索引中所有文档（仅用于测试，生产环境慎用）。

  GET /products/_search
  {
    "query": { "match_all": {} }
  }
  

• 条件查询：通过match（全文搜索）、term（精确匹配）、range（范围查询）等查询DSL筛选文档。

  GET /products/_search
  {
    "query": {
      "bool": {
        "must": [ { "match": { "name": "Elasticsearch" } } ],
        "filter": [ { "range": { "price": { "gte": 30 } } } ]
      }
    }
  }
  

3. 更新文档

• 部分更新：使用POST请求+_update端点，仅修改指定字段（高效）。

  POST /products/_update/1
  {
    "doc": { "price": 49.99 }  # 仅更新price字段
  }
  

• 全量更新：重新索引文档（覆盖原有内容，相当于先删除再新增）。

  PUT /products/_doc/1
  {
    "name": "Elasticsearch Guide（Updated）",
    "price": 49.99,
    "tags": ["search", "database", "guide"]
  }
  

4. 删除文档

通过DELETE请求删除指定ID的文档。

DELETE /products/_doc/1

四、高级操作：搜索与聚合

1. 复杂搜索（Request Body Search）

支持布尔逻辑（must/should/must_not）、模糊匹配（match_phrase）、地理位置查询等，适合复杂业务场景。

GET /logs/_search
{
  "query": {
    "bool": {
      "must": [ { "match": { "level": "ERROR" } } ],
      "filter": [ { "range": { "timestamp": { "gte": "now-1d/d" } } } ]
    }
  },
  "sort": [ { "timestamp": { "order": "desc" } } ],
  "size": 10
}

2. 聚合分析（Aggregation）

用于数据统计（如平均值、最大值）和分组（如按类别分组计数），分为指标聚合（Metrics）和桶聚合（Bucket）。

GET /products/_search
{
  "aggs": {
    "avg_price": { "avg": { "field": "price" } },  # 指标聚合：计算平均价格
    "price_ranges": { 
      "range": { 
        "field": "price", 
        "ranges": [ { "to": 50 }, { "from": 50 } ]  # 桶聚合：按价格分段
      }
    }
  }
}

3. 批量操作（Bulk API）

通过POST请求批量处理文档（插入、更新、删除），减少网络开销（建议每批次5-15MB）。

POST /products/_bulk
{ "index": { "_id": "2" } }
{ "name": "Charlie", "price": 39.99 }
{ "delete": { "_id": "1" } }  # 删除ID为1的文档

五、集群监控与管理

1. 查看集群健康状态

通过GET请求获取集群的健康状态（green/yellow/red），判断集群是否正常。

GET /_cluster/health

2. 查看节点信息

获取集群中所有节点的列表及状态（如CPU、内存使用情况）。

GET /_cat/nodes?v  # 以表格形式展示（v表示显示表头）

3. 监控字段缓存

检查字段数据缓存的占用情况，避免内存不足导致集群变慢。

GET /_cat/fielddata?v&bytes=b  # 以字节为单位展示

六、实战注意事项

1. 安全配置

新版本Elasticsearch默认启用密码认证，连接时需提供用户名（如elastic）和密码。

from elasticsearch import Elasticsearch
es = Elasticsearch(
    ["http://localhost:9200"],
    http_auth=("elastic", "your_password"),  # 替换为实际密码
    verify_certs=False  # 开发环境可关闭证书验证
)

2. 性能优化

• 内存设置：JVM堆内存至少分配6GB（不超过物理内存的50%），避免频繁GC。
• 磁盘空间：确保磁盘剩余空间超过85%，否则ES会停止写入。
• 分片数量：根据数据量调整（建议每个分片大小控制在10-50GB），避免过多或过少。

3. 内存管理

定期检查内存使用率，若超过85%可触发垃圾回收（GC）或扩容。

import psutil
import gc

def check_memory():
    memory = psutil.virtual_memory()
    if memory.percent > 85:
        print("内存快满了，进行垃圾回收...")
        gc.collect()

以上是Elasticsearch API的核心使用指南，覆盖了从基础到高级的操作场景。实际使用时，建议结合官方文档（如Elastic.co官方文档）和具体业务需求进行调整。