快速入門 - PolarDB

本文介紹如何快速上手 PolarDB-X智能搜尋（Search引擎），從建立執行個體、配置訪問憑證、到執行第一次全文檢索索引和向量檢索。

說明

智能搜尋（Search引擎）目前處於邀測階段，邀測期間不進行任何計費。若您有相關需求，請提交工單與我們聯絡。
本文智能搜尋（Search引擎）快速入門需要您對Elasticsearch或OpenSearch有一定瞭解。更多資訊，請參見OpenSearch Documentation。

步驟一：建立智能搜尋執行個體

登入PolarDB分布式版控制台，
進入Search引擎執行個體列表頁面。
在頁面左上方選擇地區。
單擊创建新实例按鈕，在購買/建立頁面選擇規格系列、節點規格與節點數量，確認配置並提交。
提交建立後，執行個體狀態依次經過 创建中 → 运行中，通常 5-10 分鐘完成初始化。

步驟二：配置訪問憑證

在執行個體列表中單擊实例ID/名称，進入執行個體詳情頁。
切換到 访问配置 標籤頁，完成以下配置：
- 白名单：單擊 新增白名单分组，將您的業務環境IP地址加入白名單。
- 账号管理：單擊 新建账号，建立用於 REST API 認證的使用者名稱和密碼。
  說明
  帳號密碼長度為8～32個字元，且必須包含至少一個大寫字母、一個小寫字母、一個數字和一個特殊字元。同時，密碼不得包含連續字元（例如123、abc）或常見的弱模式。
- 连接信息：擷取 内网地址 / 公网地址 及對應連接埠。如需公網訪問，單擊 立即开通 開通公網。

詳細操作步驟，請參見叢集管理-串連與訪問。

步驟三：驗證串連

將用戶端 IP 加入白名單後，使用 curl 驗證串連：

curl -XGET "http://<Search引擎地址>:<port>" \
  -u "<使用者名稱>:<密碼>"

返回樣本：

{
  "name": "52901553",
  "cluster_name": "search-cluster-pxs-bjrf5gxxx",
  "cluster_uuid": "6pwOq28yS4Smtxxx",
  "version": {
    "distribution": "opensearch",
    "number": "3.6.0-SNAPSHOT",
    "build_type": "tar",
    "lucene_version": "10.4.0"
  },
  "tagline": "The OpenSearch Project: https://opensearch.org/"
}

步驟四：建立第一個索引

建立一個包含標題和內容欄位的搜尋索引：

curl -XPUT "http://<Search引擎地址>:<port>/my-first-index" \
  -u "<使用者名稱>:<密碼>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "number_of_shards": 1,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "title":        { "type": "text", "analyzer": "ik_max_word" },
        "content":      { "type": "text", "analyzer": "ik_max_word" },
        "category":     { "type": "keyword" },
        "publish_date": { "type": "date" }
      }
    }
  }'

步驟五：寫入測試資料

使用 _bulk API 批量寫入幾條測試資料：

curl -XPOST "http://<Search引擎地址>:<port>/my-first-index/_bulk" \
  -u "<使用者名稱>:<密碼>" \
  -H "Content-Type: application/json" \
  -d '
{"index": {"_id": "1"}}
{"title": "PolarDB-X 分散式資料庫介紹", "content": "PolarDB-X 是一款雲原生分散式資料庫,支援高並發、高可用的線上交易處理。", "category": "資料庫", "publish_date": "2025-01-15"}
{"index": {"_id": "2"}}
{"title": "OpenSearch 全文檢索索引入門", "content": "OpenSearch 提供強大的全文檢索索引能力,支援中文分詞和多種查詢文法。", "category": "搜尋", "publish_date": "2025-02-20"}
{"index": {"_id": "3"}}
{"title": "向量檢索與 AI 應用", "content": "向量檢索通過計算向量之間的距離實現語義相似性搜尋,廣泛應用於 RAG 和推薦系統。", "category": "AI", "publish_date": "2025-03-10"}
'

步驟六：執行全文檢索索引

搜尋包含“分散式資料庫”的文檔：

curl -XPOST "http://<Search引擎地址>:<port>/my-first-index/_search" \
  -u "<使用者名稱>:<密碼>" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "content": "分散式資料庫"
      }
    },
    "highlight": {
      "fields": {
        "content": {}
      }
    }
  }'

步驟七：（可選）向量檢索樣本

建立一個支援向量檢索的索引：

curl -XPUT "http://<Search引擎地址>:<port>/my-vector-index" \
  -u "<使用者名稱>:<密碼>" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "index.knn": true,
      "number_of_shards": 1,
      "number_of_replicas": 1
    },
    "mappings": {
      "properties": {
        "title":     { "type": "text" },
        "embedding": {
          "type": "knn_vector",
          "dimension": 4,
          "method": {
            "engine": "faiss",
            "name": "hnsw",
            "space_type": "l2"
          }
        }
      }
    }
  }'

寫入向量資料並執行 KNN 查詢：

curl -XPOST "http://<Search引擎地址>:<port>/my-vector-index/_bulk" \
  -u "<使用者名稱>:<密碼>" \
  -H "Content-Type: application/json" \
  -d '
{"index": {"_id": "1"}}
{"title": "資料庫技術", "embedding": [1.0, 2.0, 3.0, 4.0]}
{"index": {"_id": "2"}}
{"title": "搜尋引擎", "embedding": [2.0, 3.0, 4.0, 5.0]}
{"index": {"_id": "3"}}
{"title": "機器學習", "embedding": [5.0, 6.0, 7.0, 8.0]}
'

curl -XPOST "http://<Search引擎地址>:<port>/my-vector-index/_search" \
  -u "<使用者名稱>:<密碼>" \
  -H "Content-Type: application/json" \
  -d '{
    "size": 2,
    "query": {
      "knn": {
        "embedding": {
          "vector": [1.5, 2.5, 3.5, 4.5],
          "k": 2
        }
      }
    }
  }'

清理測試資料

如果不再需要測試索引，可以刪除：

curl -XDELETE "http://<Search引擎地址>:<port>/my-first-index" -u "<使用者名稱>:<密碼>"
curl -XDELETE "http://<Search引擎地址>:<port>/my-vector-index" -u "<使用者名稱>:<密碼>"