API 参考

概述

智能搜索（Search引擎）完全兼容 OpenSearch REST API，应用程序通过标准 HTTP 请求与搜索引擎交互。

• 请求格式：

  <HTTP方法> http://<Search引擎地址>:<port>/<路径>

• 通用请求头：

  Content-Type: application/json
  Authorization: Basic <base64编码的用户名:密码>

• 通用参数：

  参数	说明
  pretty	返回格式化的 JSON 输出
  format=yaml	以 YAML 格式返回
  human=true	返回人类可读的值（如 “1.5gb” 替代字节数）

集群 API

# 集群健康
GET _cluster/health
GET _cluster/health/<index>

# 集群状态/统计/设置
GET _cluster/state
GET _cluster/stats
GET _cluster/settings?include_defaults=true

# 修改持久设置
PUT _cluster/settings
{ "persistent": { "action.auto_create_index": "true" } }

# 节点信息
GET _cat/nodes?v
GET _nodes
GET _nodes/<node_id>
GET _nodes/stats

CAT API

CAT API 提供简洁的文本表格输出，适合终端查看。

# 索引列表
GET _cat/indices?v&s=index

# 分片分布
GET _cat/shards?v&s=index

# 节点列表
GET _cat/nodes?v&h=name,role,heap.percent,ram.percent,cpu,disk.used_percent

# 模板列表
GET _cat/templates?v

# 别名列表
GET _cat/aliases?v

# 线程池状态
GET _cat/thread_pool?v&h=node_name,name,active,queue,rejected

# 挂起任务
GET _cat/pending_tasks?v

# 集群健康
GET _cat/health?v

索引 API

# 创建索引
PUT /<index>
{
  "settings": { "number_of_shards": 3, "number_of_replicas": 1 },
  "mappings": { "properties": { "field1": {"type":"text"}, "field2": {"type":"keyword"} } }
}

# 删除索引
DELETE /<index>
DELETE /<index1>,<index2>

# 查看索引/mapping/settings/stats
GET /<index>
# 仅 mapping
GET /<index>/_mapping
# 仅 settings
GET /<index>/_settings
# 索引统计
GET /<index>/_stats

# 修改索引设置
PUT /<index>/_settings
{ "number_of_replicas": 2, "refresh_interval": "5s" }

# 新增 mapping 字段
PUT /<index>/_mapping
{ "properties": { "new_field": { "type": "keyword" } } }

# 开关索引
POST /<index>/_close
POST /<index>/_open

# 添加别名
POST _aliases
{ "actions": [ { "add":    { "index": "my-index", "alias": "my-alias" } } ] }
# 删除别名
POST _aliases
{ "actions": [ { "remove": { "index": "my-index", "alias": "my-alias" } } ] }

# 创建/更新模板
PUT _index_template/<template_name> { "index_patterns": ["logs-*"], "priority": 100, "template": { } }
# 查看模板
GET _index_template/<template_name>
# 删除模板
DELETE _index_template/<template_name>

# Reindex
POST _reindex
{ "source": { "index": "source-index" }, "dest": { "index": "dest-index" } }

# Refresh / Flush / Forcemerge
POST /<index>/_refresh
POST /<index>/_flush
POST /<index>/_forcemerge?max_num_segments=1

文档 API

# 写入文档（指定 ID）
PUT  /<index>/_doc/<id>
# 写入文档（自动生成 ID）
POST /<index>/_doc

# 获取文档
GET /<index>/_doc/<id>
# 仅获取 _source
GET /<index>/_source/<id>
# 批量获取
POST /_mget
{ "docs": [ { "_index": "my-index", "_id": "1" }, { "_index": "my-index", "_id": "2" } ] }

# 部分更新
POST /<index>/_update/<id>
{ "doc": { "field1": "new_value" } }

# 脚本更新
POST /<index>/_update/<id>
{ "script": { "source": "ctx._source.counter += params.count", "params": { "count": 1 } } }

# 删除
DELETE /<index>/_doc/<id>

# 批量(_bulk)
POST /_bulk
{ "index":  { "_index": "my-index", "_id": "1" } }
{ "field1": "value1" }
{ "update": { "_index": "my-index", "_id": "2" } }
{ "doc":    { "field1": "updated" } }
{ "delete": { "_index": "my-index", "_id": "3" } }

# 按查询更新
POST /<index>/_update_by_query
{ "query": { "term": { "status": "old" } }, "script": { "source": "ctx._source.status = 'archived'" } }
# 按查询删除
POST /<index>/_delete_by_query
{ "query": { "term": { "status": "expired" } } }

搜索 API

# 基础搜索
POST /<index>/_search
{
  "query":   { "match": { "content": "搜索关键词" } },
  "from":    0,
  "size":    10,
  "sort":    [ { "created_at": "desc" } ],
  "_source": [ "title", "content", "created_at" ],
  "highlight": { "fields": { "content": {} } }
}

# 多索引搜索
POST /index1,index2/_search
POST /logs-*/_search

# Multi Search
POST /_msearch
{"index": "index1"}
{"query": {"match": {"title": "搜索1"}}}
{"index": "index2"}
{"query": {"match": {"title": "搜索2"}}}

# 文档计数
POST /<index>/_count
{ "query": { "match": { "status": "active" } } }

# KNN 向量搜索
POST /<index>/_search
{
  "size": 10,
  "query": {
    "knn": {
      "<vector_field>": {
        "vector": [0.1, 0.2],
        "k":      10,
        "filter": { "term": { "category": "tech" } }
      }
    }
  }
}

# 开启 scroll
POST /<index>/_search?scroll=5m
{ "size": 1000, "query": { "match_all": {} } }
# 继续获取
POST /_search/scroll
{ "scroll": "5m", "scroll_id": "<scroll_id>" }
# 清除 scroll
DELETE /_search/scroll
{ "scroll_id": "<scroll_id>" }

聚合 API

聚合通过 _search API 的 aggs 参数使用。支持类型：

POST /<index>/_search
{
  "size": 0,
  "aggs": {
    "my_agg": {
      "<agg_type>": { ... }
    }
  }
}

ISM（索引状态管理） API

# 创建/更新策略
PUT    _plugins/_ism/policies/<policy_name>
# 查看策略
GET    _plugins/_ism/policies/<policy_name>
# 删除策略
DELETE _plugins/_ism/policies/<policy_name>
# 查看所有策略
GET    _plugins/_ism/policies

# 为索引应用策略
POST _plugins/_ism/add/<index>
{ "policy_id": "<policy_name>" }
# 移除策略
POST _plugins/_ism/remove/<index>
# 查看索引的 ISM 状态
GET  _plugins/_ism/explain/<index>

分析器与任务管理 API

# 测试分析器效果
POST /_analyze
{ "analyzer": "ik_max_word", "text": "PolarDB-X分布式数据库" }
# 测试索引的特定字段分析器
POST /<index>/_analyze
{ "field": "content", "text": "测试分词效果" }

# 查看进行中的任务v
GET   _tasks
GET   _tasks?detailed=true
# 查看特定任务
GET   _tasks/<task_id>
# 取消任务
POST  _tasks/<task_id>/_cancel

错误码参考