快速入门

步骤一：创建智能搜索实例

1. 登录PolarDB分布式版控制台，

2. 进入Search引擎实例列表页面。

3. 在页面左上角选择地域。

4. 单击创建新实例按钮，在购买/创建页面选择规格系列、节点规格与节点数量，确认配置并提交。

5. 提交创建后，实例状态依次经过 创建中 → 运行中，通常 5-10 分钟完成初始化。

步骤二：配置访问凭证

1. 在实例列表中单击实例ID/名称，进入实例详情页。

2. 切换到 访问配置 标签页，完成以下配置：

   • 白名单：单击 新增白名单分组，将您的业务环境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 "<用户名>:<密码>"