快速入门 - 云原生数据库 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 "<用户名>:<密码>"