Skip to main content

OpenSearch 9200 常用 REST API

OpenSearch（與 Elasticsearch 相容）預設透過 HTTP :9200 提供 REST API。以下以本機 http://localhost:9200 為例，整理日常開發最常用的端點。

若叢集啟用安全外掛，請在 curl 加上 -u admin:password 或對應的 Bearer token。

快速對照​

分類MethodPath用途
連線檢查GET/確認服務與版本
叢集健康GET/_cluster/healthgreen / yellow / red
節點列表GET/_cat/nodes看有哪些 node
Index 列表GET/_cat/indices列出 index 與 health
建立 IndexPUT/{index}建 index + mapping
查 MappingGET/{index}/_mapping看欄位型別
寫入文件PUT/POST/{index}/_doc/{id}單筆 index
讀取文件GET/{index}/_doc/{id}依 _id 取文件
刪除文件DELETE/{index}/_doc/{id}刪單筆
搜尋GET/POST/{index}/_search查詢
批次POST/_bulk大量寫入／刪除
依條件刪POST/{index}/_delete_by_query條件刪除

1. 連線與叢集資訊​

根路徑（版本、叢集名）​

curl "http://localhost:9200/?pretty"

回傳大致包含 cluster_name、version.number、tagline。

叢集健康​

curl "http://localhost:9200/_cluster/health?pretty"

常用 query：

參數說明
pretty美化 JSON
level=indices細到每個 index
wait_for_status=green等到指定狀態再回傳

單節點常見 yellow 的原因與處理，見 OpenSearch 單節點、Replica 與 Cluster Health。

叢集設定​

# 讀取
curl "http://localhost:9200/_cluster/settings?pretty"

# 暫態調整（重啟後消失）
curl -X PUT "http://localhost:9200/_cluster/settings" \
  -H 'Content-Type: application/json' \
  -d '{
    "transient": {
      "cluster.routing.allocation.enable": "all"
    }
  }'

2. Cat API（人讀友善表格）​

_cat/* 回傳文字表格，適合在終端機快速查看。建議加 ?v（顯示欄位標題）。

# 所有 index
curl "http://localhost:9200/_cat/indices?v"

# 節點
curl "http://localhost:9200/_cat/nodes?v"

# 分片配置
curl "http://localhost:9200/_cat/shards?v"

# 別名
curl "http://localhost:9200/_cat/aliases?v"

# 健康摘要
curl "http://localhost:9200/_cat/health?v"

常用額外參數：?v&s=index:asc（排序）、?h=index,health,docs.count（只顯示指定欄位）。

3. Index 管理​

建立 Index（含 mapping / settings）​

curl -X PUT "http://localhost:9200/documents" \
  -H 'Content-Type: application/json' \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 0
    },
    "mappings": {
      "properties": {
        "filename": { "type": "text" },
        "content": { "type": "text" },
        "source": { "type": "keyword" },
        "indexed_at": { "type": "date" }
      }
    }
  }'

text / keyword 差異見 Mapping：text 與 keyword。

是否存在​

curl -I "http://localhost:9200/documents"
# 200 → 存在；404 → 不存在

查 Mapping / Settings​

curl "http://localhost:9200/documents/_mapping?pretty"
curl "http://localhost:9200/documents/_settings?pretty"

更新 Settings（例如關閉 replica）​

curl -X PUT "http://localhost:9200/documents/_settings" \
  -H 'Content-Type: application/json' \
  -d '{
    "index": {
      "number_of_replicas": 0
    }
  }'

刪除 Index​

curl -X DELETE "http://localhost:9200/documents"

Mapping 欄位型別通常不能就地變更；改型別需刪除重建 index。

Alias​

# 建立別名
curl -X POST "http://localhost:9200/_aliases" \
  -H 'Content-Type: application/json' \
  -d '{
    "actions": [
      { "add": { "index": "documents-v1", "alias": "documents" } }
    ]
  }'

# 查別名
curl "http://localhost:9200/_alias/documents?pretty"

4. 文件 CRUD​

寫入 / 覆寫（指定 _id）​

curl -X PUT "http://localhost:9200/documents/_doc/1" \
  -H 'Content-Type: application/json' \
  -d '{
    "filename": "manual.pdf",
    "content": "Install the battery pack carefully",
    "source": "thortron_one",
    "indexed_at": "2026-07-21T00:00:00Z"
  }'

自動產生 _id​

curl -X POST "http://localhost:9200/documents/_doc" \
  -H 'Content-Type: application/json' \
  -d '{
    "filename": "guide.pdf",
    "content": "Safety instructions",
    "source": "thortron_one"
  }'

讀取​

curl "http://localhost:9200/documents/_doc/1?pretty"

部分更新（_update）​

curl -X POST "http://localhost:9200/documents/_update/1" \
  -H 'Content-Type: application/json' \
  -d '{
    "doc": {
      "filename": "manual-rev2.pdf"
    }
  }'

刪除單筆​

curl -X DELETE "http://localhost:9200/documents/_doc/1"

依條件刪除（_delete_by_query）​

curl -X POST "http://localhost:9200/documents/_delete_by_query" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "term": { "source": "thortron_one" }
    }
  }'

簡易 query string​

curl "http://localhost:9200/documents/_search?q=battery&pretty"

JSON body（推薦）​

curl -X POST "http://localhost:9200/documents/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "from": 0,
    "size": 10,
    "query": {
      "multi_match": {
        "query": "battery pack",
        "fields": ["content", "filename"]
      }
    }
  }'

常用 query 類型​

Query用途
match單欄全文搜尋
multi_match多欄全文搜尋
term / termskeyword 精確比對
boolmust / should / filter / must_not 組合
range數值、日期範圍
match_all取全部（搭配 size）

bool + filter 範例：

curl -X POST "http://localhost:9200/documents/_search?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "bool": {
        "must": [
          { "match": { "content": "battery" } }
        ],
        "filter": [
          { "term": { "source": "thortron_one" } }
        ]
      }
    }
  }'

Count​

curl -X POST "http://localhost:9200/documents/_count?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": { "match": { "content": "battery" } }
  }'

6. Bulk API（批次寫入）​

_bulk 使用 NDJSON（每行一個 JSON，不可 pretty-print）。

curl -X POST "http://localhost:9200/_bulk" \
  -H 'Content-Type: application/x-ndjson' \
  --data-binary $'
{ "index": { "_index": "documents", "_id": "1" } }
{ "filename": "a.pdf", "content": "page one", "source": "thortron_one" }
{ "index": { "_index": "documents", "_id": "2" } }
{ "filename": "b.pdf", "content": "page two", "source": "thortron_one" }
{ "delete": { "_index": "documents", "_id": "3" } }
'

常見 action：index、create、update、delete。

7. 分析與除錯​

Analyze（看分詞結果）​

curl -X POST "http://localhost:9200/_analyze?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "analyzer": "standard",
    "text": "Install the battery pack carefully"
  }'

對已存在的 index 欄位：

curl -X POST "http://localhost:9200/documents/_analyze?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "field": "content",
    "text": "Install the battery pack carefully"
  }'

Explain（為何某文件命中／分數）​

curl -X POST "http://localhost:9200/documents/_explain/1?pretty" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "match": { "content": "battery" }
    }
  }'

8. 重新整理與任務​

Refresh（讓剛寫入的資料立刻可搜）​

curl -X POST "http://localhost:9200/documents/_refresh"

開發時可在 index 時加 ?refresh=true；正式環境避免每次寫入都 refresh。

查看進行中的任務​

curl "http://localhost:9200/_tasks?pretty"

實務小結​

情境常用 API
剛開 Docker，確認活著GET /、GET /_cluster/health
看 index 狀態GET /_cat/indices?v
建 mapping、寫資料PUT /{index}、PUT /{index}/_doc/{id}、POST /_bulk
全文搜尋POST /{index}/_search（multi_match / bool）
清測試資料POST /{index}/_delete_by_query 或 DELETE /{index}
排查分詞POST /_analyze

相關筆記：