全部产品
Search
文档中心

云原生数据库 PolarDB:PolarSearch快速入门

更新时间:Jul 08, 2026

PolarSearch是PolarDB提供的一种分布式搜索服务,支持全文检索与向量检索,其架构基于OpenSearch(兼容Elasticsearch生态)并与PolarDB数据库紧密集成。PolarSearch让您通过简单操作就能满足一站式的数据检索需求。

重要

本文PolarSearch使用指南需要您对ElasticSearch或OpenSearch有一定了解。更多信息,请参见OpenSearch Documentation

适用范围

集群配置要求

  • 产品版本:企业版。

  • 系列:集群版。

  • 数据库引擎:MySQL 8.0.1、MySQL 8.0.2。

    说明

    以上数据库引擎版本要求均无小版本要求。更多信息,请参见查询版本号

支持地域与可用区

PolarSearch支持的可用区如下:

地域

可用区

华东1(杭州)

可用区I、可用区J、可用区K

华东2(上海)

可用区E、可用区F、可用区L、可用区N

华南1(深圳)

可用区C、可用区D、可用区F

华北2(北京)

可用区F、可用区L、可用区I、可用区K

华北3(张家口)

可用区B

华北6(乌兰察布)

可用区B、可用区C

中国(香港)

可用区B、可用区D

新加坡

可用区A、可用区B

日本(东京)

可用区B、可用区C

韩国(首尔)

可用区A、可用区B

德国(法兰克福)

可用区A

美国(硅谷)

可用区B

菲律宾

可用区A

说明

若您有其他可用区需求,请提交工单与我们联系。

费用说明

PolarSearch通过独立的搜索节点支持搜索功能,并收取费用。搜索节点按照普通计算节点计费。同时,搜索节点中的索引与数据将占用一定的存储空间,因此也会产生相应的存储空间费用

添加PolarSearch搜索节点

  • 符合适用范围的已有集群,添加搜索节点。

    1. 登录PolarDB控制台,在左侧导航栏单击集群列表,选择集群所在地域,找到目标集群。

    2. 单击目标集群ID,进入集群基本信息页。

    3. 数据库节点区域,单击增删节点

      image

    4. 增删节点向导对话框,选择新增搜索节点。

创建搜索节点账号

设置管理员账号

说明
  • 添加的账号是数据库的普通权限账号。

  • 添加的普通权限账号为PolarSearch功能的管理员权限账号。

  1. 登录PolarDB控制台,在左侧导航栏单击集群列表,选择集群所在地域,找到目标集群。

  2. 单击目标集群ID,进入集群基本信息页。

  3. 数据库节点区域,将鼠标悬浮在搜索节点,单击设置连接数据库账号

    image

  4. 在对话框中可以选择已有的数据库普通账号或创建新普通账号,并输入账号密码。

    image

    重要

    数据库账号名字不能是数据库密码的字符子串(不区分大小写)。例如search_test的数据库账号,密码不能是SEARCH_test@123,但可以是SEARCHtest@123SEARCH@_test

设置普通账号

普通账户可以按照索引维度控制账号能访问的索引范围。常用有两种账户权限设置方式,分别是Dashboard白屏化设置和REST API设置。

Dashboard白屏化设置

说明

需要账号拥有security_rest_api_access角色,否则不显示Security页面。

  1. 新建用户

    1. 单击左侧导航栏,进入Management > Security页面,并选择Internal users,单击Create internal userimage

    2. 在创建用户页面,输入用户名和密码创建用户。例如,创建一个账号密码为USER@test123的用户testuser,然后单击Create完成创建。image

  2. 新建角色

    1. 单击左侧导航栏,进入页面,并选择Roles,单击Create roleimage

    2. 角色权限主要包括集群权限和索引权限,权限的设定可以通过操作组进行添加。索引权限配置在Index处可以设置具体的索引名字或者通过*通配符适配某一类名字的索引,在Index permissions选择索引的具体权限,如只读、读写等。

      示例:创建一个拥有全部集群权限(unlimited相当于全部权限)以及以indextest作为前缀的所有索引的索引只读权限的角色onlyreadroleimage.png

  3. 角色映射用户

    1. 单击左侧导航栏,进入页面,并选择Roles,单击目标角色。

    2. Mapped users页签中添加用户映射。一个用户可以被多个角色映射,并同时拥有这些角色的权限。

      示例:将onlyreadrole的角色与testuser用户进行映射,testuser用户获得onlyreadrole角色所拥有的权限。image.png

REST API设置

搜索节点可通过API实现完整的访问控制,请参见社区文档OpenSearch API

  1. 新建用户

    curl -X PUT "http://<endpoint>:<port>/_plugins/_security/api/internalusers/<new_user>" \
      --user "<user_name>:<passwd>" \
      -H "Content-Type: application/json" \
      -d '{
        "password": "<new_password>",
        "backend_roles": [],
        "attributes": {}
      }'

    示例:创建一个账号密码为USER@test123的用户testuser

    curl -X PUT "http://<endpoint>:<port>/_plugins/_security/api/internalusers/testuser" \
      --user "<user_name>:<passwd>" \
      -H "Content-Type: application/json" \
      -d '{
        "password": "USER@test123",
        "backend_roles": [],
        "attributes": {}
      }'
  2. 新建角色

    curl -X PUT "http://<endpoint>:<port>/_plugins/_security/api/roles/<role_name>" \
      --user "<user_name>:<passwd>" \
      -H "Content-Type: application/json" \
      -d '{
        "cluster_permissions": ["*"],
        "index_permissions": [
          {
            "index_patterns": ["*"],
            "allowed_actions": ["*"]
          }
        ]
      }'
    • index_patterns:对应需要设置的索引名字,可以通过*通配符批量设置索引。

    • allowed_actions:对应具体的权限,如readwrite等。

    示例:创建一个具有全部集群权限以及以indextest作为前缀的所有索引的只读权限角色onlyreadrole

    curl -X PUT "http://<endpoint>:<port>/_plugins/_security/api/roles/onlyreadrole" \
      --user "<user_name>:<passwd>" \
      -H "Content-Type: application/json" \
      -d '{
        "cluster_permissions": ["*"],
        "index_permissions": [
          {
            "index_patterns": ["indextest*"],
            "allowed_actions": ["read"]
          }
        ]
      }'
  3. 映射角色

    curl -X PUT "http://<endpoint>:<port>/_plugins/_security/api/rolesmapping/<role_name>" \
      --user "<user_name>:<passwd>" \
      -H "Content-Type: application/json" \
      -d '{
        "backend_roles": [],
        "hosts": [],
        "users": ["<new_user>"]
      }'

    示例:将onlyreadrole的角色与testuser用户进行映射,testuser用户获得onlyreadrole角色所拥有的权限。

    curl -X PUT "http://<endpoint>:<port>/_plugins/_security/api/rolesmapping/onlyreadrole" \
      --user "<user_name>:<passwd>" \
      -H "Content-Type: application/json" \
      -d '{
        "backend_roles": [],
        "hosts": [],
        "users": ["testuser"]
      }'

获取连接地址

搜索地址

数据库节点区域,将鼠标悬浮在搜索节点,根据您的实际使用的环境,获取对应的私网或公网地址。

image

Dashboard地址

数据库节点区域,将鼠标悬浮在搜索节点,根据您的实际使用的环境,获取对应的Dashboard私网或公网地址。image

登录PolarSearch

通过搜索地址访问

若您偏向于使用API进行管理索引与数据,则可以通过API来访问PolarSearch。此处以ECS实例为例:

  1. 设置集群白名单:请根据您ECS实例所属网络添加对应的IP地址至PolarDB MySQL版集群白名单中。

    说明
    • ECS实例与PolarDB MySQL版集群在同一专有网络VPC下,请填写ECS实例的私网IP。

    • ECS实例与PolarDB MySQL版集群不在同一专有网络VPC下,请填写ECS实例的公网IP。

  2. 连接PolarSearch:执行如下命令,如果返回集群信息,说明集群可服务。其中,<endpoint>:<port>需替换PolarSearch的搜索地址<user_name>:<passwd>为PolarSearch的管理员账号

    curl http://<endpoint>:<port>/ -u <user_name>:<passwd>

通过Dashboard访问

若您想通过白屏方式操作PolarSearch,则可以通过Dashboard(控制台)来访问PolarSearch。此处以本地环境中浏览器为例:

  1. 设置集群白名单:请根据您本地环境的IP地址至PolarDB MySQL版集群白名单中。

  2. 在浏览器中登录PolarSearch控制台:

    1. 在浏览器地址栏输入http://<endpoint>:<port>后回车。其中,<endpoint>:<port>需替换PolarSearch的Dashboard公网地址

    2. 在控制台登录页面,输入PolarSearch的管理员账号,即可登录Kibana兼容的PolarSearch控制台。

操作示例

说明
  • 本例全部在ECS实例中通过命令行完成。

  • PolarSearch完全兼容OpenSearch 2.19.0版本的SDK或REST API,其他版本可能存在兼容性问题。更多信息,请参见OpenSearch

创建索引

搜索节点中的索引,相当于关系型数据库中的表,可使用Elasticsearch兼容的REST API创建或直接在Dashboard中执行命令,示例如下:

命令行

curl -XPUT "http://<endpoint>:<port>/articles" \
--user "<user_name>:<passwd>" \
-H 'Content-Type: application/json' \
-d '{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "content": {
        "type": "text"
      },
      "author": {
        "type": "keyword"
      }
    }
  }
}'

Dashboard

PUT articles
{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 1
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text"
      },
      "content": {
        "type": "text"
      },
      "author": {
        "type": "keyword"
      }
    }
  }
}

导入数据

命令行

curl -XPOST "http://<endpoint>:<port>/articles/_bulk" \
--user "<user_name>:<passwd>" \
-H 'Content-Type: application/json' \
-d '
{"index": {}}
{"title": "Introduction to PolarSearch", "content": "PolarSearch is a powerful search engine.", "author": "Allen"}
{"index": {}}
{"title": "Advanced Search Techniques", "content": "Learn how to use full-text search and filters in PolarDB.", "author": "Lang"}
{"index": {}}
{"title": "Elasticsearch vs PolarSearch", "content": "A comparison of Elasticsearch and PolarSearch features.", "author": "Zhao"}
'

Dashboard

POST articles/_bulk
{"index": {}}
{"title": "Introduction to PolarSearch", "content": "PolarSearch is a powerful search engine.", "author": "Allen"}
{"index": {}}
{"title": "Advanced Search Techniques", "content": "Learn how to use full-text search and filters in PolarDB.", "author": "Lang"}
{"index": {}}
{"title": "Elasticsearch vs PolarSearch", "content": "A comparison of Elasticsearch and PolarSearch features.", "author": "Zhao"}

执行搜索查询

数据导入完成后,可通过SDK、REST API或在Dashboard上进行全文搜索,如下所示:

命令行

curl -XGET "http://<endpoint>:<port>/articles/_search" \
--user "<user_name>:<passwd>" \
-H 'Content-Type: application/json' \
-d '
{
  "query": {
    "match": {
      "content": "PolarSearch"
    }
  }
}'

Dashboard

GET articles/_search
{
  "query": {
    "match": {
      "content": "PolarSearch"
    }
  }
}
说明

更多搜索查询语法,请参见OpenSearch

创建向量索引

命令行

curl -XPUT "http://<endpoint>:<port>/my-vector-index" \
--user "<user_name>:<passwd>" \
-H "Content-Type:application/json" \
-d '
{
  "settings": {
    "index": {
      "knn": true
    }
  },
  "mappings": {
    "properties": {
      "vector_field": {
        "type": "knn_vector",
        "dimension": 4
      },
      "metadata": {
        "type": "text"
      }
    }
  }
}
'

Dashboard

PUT my-vector-index
{
  "settings": {
    "index": {
      "knn": true
    }
  },
  "mappings": {
    "properties": {
      "vector_field": {
        "type": "knn_vector",
        "dimension": 4
      },
      "metadata": {
        "type": "text"
      }
    }
  }
}

插入向量数据

命令行

curl -XPOST "http://<endpoint>:<port>/my-vector-index/_bulk" \
--user "<user_name>:<passwd>" \
-H "Content-Type:application/json" \
-d '
{"index": {}}
{"vector_field": [0.1, 0.5, -0.3, 0.8], "metadata": "Document 1"}
{"index": {}}
{"vector_field": [-0.2, 0.7, 0.4, -0.1], "metadata": "Document 2"}
'

Dashboard

POST my-vector-index/_bulk
{"index": {}}
{"vector_field": [0.1, 0.5, -0.3, 0.8], "metadata": "Document 1"}
{"index": {}}
{"vector_field": [-0.2, 0.7, 0.4, -0.1], "metadata": "Document 2"}

向量检索

命令行

curl -XGET "http://<endpoint>:<port>/my-vector-index/_search" \
--user "<user_name>:<passwd>" \
-H "Content-Type:application/json" \
-d '
{
  "size": 2,
  "query": {
    "knn": {
      "vector_field": {
        "vector": [0.1, 0.5, -0.3, 0.8],
        "k": 2
      }
    }
  }
}
'

Dashboard

GET my-vector-index/_search
{
  "size": 2,
  "query": {
    "knn": {
      "vector_field": {
        "vector": [0.1, 0.5, -0.3, 0.8],
        "k": 2
      }
    }
  }
}