API reference

Overview

The Search engine is fully compatible with the OpenSearch REST API. Applications interact with the search engine over standard HTTP requests.

• Request format:

  <HTTP method> http://<Search engine endpoint>:<port>/<path>

• Common request headers:

  Content-Type: application/json
  Authorization: Basic <base64-encoded username:password>

• Common parameters:

  Parameter	Description
  pretty	Returns formatted JSON output.
  format=yaml	Returns the response in YAML format.
  human=true	Returns human-readable values (for example, "1.5gb" instead of a byte count).

Cluster API

# Cluster health
GET _cluster/health
GET _cluster/health/<index>

# Cluster state, stats, and settings
GET _cluster/state
GET _cluster/stats
GET _cluster/settings?include_defaults=true

# Update persistent settings
PUT _cluster/settings
{ "persistent": { "action.auto_create_index": "true" } }

# Node information
GET _cat/nodes?v
GET _nodes
GET _nodes/<node_id>
GET _nodes/stats

CAT API

The CAT API returns compact, tabular text output that is suitable for terminal viewing.

# List indexes
GET _cat/indices?v&s=index

# Shard distribution
GET _cat/shards?v&s=index

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

# Templates
GET _cat/templates?v

# Aliases
GET _cat/aliases?v

# Thread pool status
GET _cat/thread_pool?v&h=node_name,name,active,queue,rejected

# Pending tasks
GET _cat/pending_tasks?v

# Cluster health
GET _cat/health?v

Index API

# Create an index
PUT /<index>
{
  "settings": { "number_of_shards": 3, "number_of_replicas": 1 },
  "mappings": { "properties": { "field1": {"type":"text"}, "field2": {"type":"keyword"} } }
}

# Delete an index
DELETE /<index>
DELETE /<index1>,<index2>

# View index / mapping / settings / stats
GET /<index>
# Mapping only
GET /<index>/_mapping
# Settings only
GET /<index>/_settings
# Index stats
GET /<index>/_stats

# Update index settings
PUT /<index>/_settings
{ "number_of_replicas": 2, "refresh_interval": "5s" }

# Add mapping fields
PUT /<index>/_mapping
{ "properties": { "new_field": { "type": "keyword" } } }

# Open or close an index
POST /<index>/_close
POST /<index>/_open

# Add an alias
POST _aliases
{ "actions": [ { "add":    { "index": "my-index", "alias": "my-alias" } } ] }
# Remove an alias
POST _aliases
{ "actions": [ { "remove": { "index": "my-index", "alias": "my-alias" } } ] }

# Create or update a template
PUT _index_template/<template_name> { "index_patterns": ["logs-*"], "priority": 100, "template": { } }
# View a template
GET _index_template/<template_name>
# Delete a template
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

Document API

# Write a document (with a specific ID)
PUT  /<index>/_doc/<id>
# Write a document (auto-generated ID)
POST /<index>/_doc

# Get a document
GET /<index>/_doc/<id>
# Get only the _source
GET /<index>/_source/<id>
# Multi-get
POST /_mget
{ "docs": [ { "_index": "my-index", "_id": "1" }, { "_index": "my-index", "_id": "2" } ] }

# Partial update
POST /<index>/_update/<id>
{ "doc": { "field1": "new_value" } }

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

# Delete
DELETE /<index>/_doc/<id>

# Bulk (_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" } }

# Update by query
POST /<index>/_update_by_query
{ "query": { "term": { "status": "old" } }, "script": { "source": "ctx._source.status = 'archived'" } }
# Delete by query
POST /<index>/_delete_by_query
{ "query": { "term": { "status": "expired" } } }

Search API

# Basic search
POST /<index>/_search
{
  "query":   { "match": { "content": "search keyword" } },
  "from":    0,
  "size":    10,
  "sort":    [ { "created_at": "desc" } ],
  "_source": [ "title", "content", "created_at" ],
  "highlight": { "fields": { "content": {} } }
}

# Multi-index search
POST /index1,index2/_search
POST /logs-*/_search

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

# Document count
POST /<index>/_count
{ "query": { "match": { "status": "active" } } }

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

# Open scroll
POST /<index>/_search?scroll=5m
{ "size": 1000, "query": { "match_all": {} } }
# Continue scroll
POST /_search/scroll
{ "scroll": "5m", "scroll_id": "<scroll_id>" }
# Clear scroll
DELETE /_search/scroll
{ "scroll_id": "<scroll_id>" }

Aggregation API

Aggregations are performed by passing the aggs parameter to the _search API. Supported types:

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

ISM (Index State Management) API

# Create or update a policy
PUT    _plugins/_ism/policies/<policy_name>
# View a policy
GET    _plugins/_ism/policies/<policy_name>
# Delete a policy
DELETE _plugins/_ism/policies/<policy_name>
# List all policies
GET    _plugins/_ism/policies

# Apply a policy to an index
POST _plugins/_ism/add/<index>
{ "policy_id": "<policy_name>" }
# Remove a policy
POST _plugins/_ism/remove/<index>
# Show the ISM status of an index
GET  _plugins/_ism/explain/<index>

Analyzer and task management API

# Test the effect of an analyzer
POST /_analyze
{ "analyzer": "ik_max_word", "text": "PolarDB-X distributed database" }
# Test the analyzer of a specific field in an index
POST /<index>/_analyze
{ "field": "content", "text": "test tokenization" }

# List in-progress tasks
GET   _tasks
GET   _tasks?detailed=true
# View a specific task
GET   _tasks/<task_id>
# Cancel a task
POST  _tasks/<task_id>/_cancel

Error code reference