从 AlloyDB 访问 OpenSearch 数据

您可以使用 AlloyDB 中的外部搜索集成来访问和搜索存储在 OpenSearch 中的数据。借助此集成，您可以将 OpenSearch 索引与 AlloyDB 中的关系表联接，而无需移动或复制数据。

准备工作

在开始之前，请确保您已完成以下操作：

在 Secret Manager 中存储 OpenSearch 凭据

AlloyDB 会从 Secret Manager 中存储和读取您的 OpenSearch 凭据。如需详细了解如何使用 Secret Manager，请参阅 使用 Secret Manager 创建和访问 Secret。

确保您的 AlloyDB 服务帐号具有 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色，以便从 Secret Manager 中读取 Secret。如需了解详情，请参阅 使用 Secret Manager 创建和访问 Secret。

启用和配置 external_search_fdw 扩展程序

如需开始与 OpenSearch 集成，请通过外部数据服务器配置对 OpenSearch 集群的访问权限。

  1. 启用 external_search_fdw 扩展程序。

    CREATE EXTENSION external_search_fdw;

  2. 为 OpenSearch 集群创建服务器。

    CREATE SERVER OPENSEARCH_SERVER_NAME
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS (
  server 'OPENSEARCH_SERVER_HOST_PORT',
  search_provider 'opensearch',
  auth_mode 'secret_manager',
  auth_method 'Basic',
  secret_path 'SECRET_PATH'
);

    执行以下变量替换操作：

    • OPENSEARCH_SERVER_NAME：外部数据服务器的名称。例如，opensearch。

    • OPENSEARCH_SERVER_HOST_PORT：OpenSearch 集群的面向公众的网址（端点）。

    • SECRET_PATH：OpenSearch 身份验证凭据的 Secret Manager 路径。例如，projects/123456789012/secrets/opensearch-credentials/versions/1。123456789012 表示您的 Google Cloud 项目 ID。

  3. 为 OpenSearch 服务器定义 PostgreSQL 用户映射。请注意，PostgreSQL FDW 需要此用户映射才能正常运行。AlloyDB 使用 REST 授权标头进行身份验证。

    CREATE USER MAPPING FOR CURRENT_USER
SERVER OPENSEARCH_SERVER_NAME;

  4. 将 OpenSearch 索引的架构映射到 PostgreSQL 外部表。

    CREATE FOREIGN TABLE OPENSEARCH_FD_TABLE(
    metadata external_search_fdw_schema.OpaqueMetadata,
    OPENSEARCH_FIELDS)
       SERVER OPENSEARCH_SERVER_NAME
       OPTIONS(
            remote_table_name 'OPENSEARCH_INDEX_NAME'
       );

    替换以下新变量：

    • OPENSEARCH_FD_TABLE：表示 OpenSearch 表的外部数据表的名称。例如，my-fd-opensearch-table。

    • OPENSEARCH_FIELDS：逗号分隔列表，其中每个条目使用 opensearch_field_name PG_DATA_TYPE 格式。如需查看受支持的 OpenSearch 数据类型及其对应的 PostgreSQL 类型的列表，请参阅支持的数据类型。

    • OPENSEARCH_INDEX_NAME：OpenSearch 索引的名称。例如，my-opensearch-index。

支持的数据类型

AlloyDB 支持以下 OpenSearch 数据类型：

数据类型 AlloyDB 类型
alias alias 引用的字段的 PostgreSQL 类型
binary bytea
boolean BOOLEAN

byte、

short

SMALLINT
date TIMESTAMPTZ

double、

scaled_float

DOUBLE PRECISION

float、

half_float

REAL
integer INTEGER
long BIGINT

object、

flattened

jsonb

text、

keyword、

constant_keyword、

wildcard

TEXT
unsigned_long NUMERIC

查询 OpenSearch 数据

AlloyDB 接受 SQL 查询，并将其转换为 OpenSearch REST API 查询。

如需查询 OpenSearch 数据，您可以使用以下选项：

  • 标准 SQL 查询
  • 查询 DSL
  • 混合搜索

标准 SQL 查询

您可以将标准 SQL 与 Lucene 语法搭配使用作为搜索表达式。

SELECT id, body
FROM OPENSEARCH_FD_TABLE
WHERE FILTER
ORDER BY metadata <@> 'QUERY';

执行以下变量替换操作：

  • OPENSEARCH_FD_TABLE：表示 OpenSearch 表的外部数据表的名称。例如，my-fd-opensearch-table。

  • （可选）FILTER：要应用于 OpenSearch 查询的过滤条件。例如，a = 10 AND b < 105。

  • QUERY：要发送到 OpenSearch 的查询。例如，body:database。

查询 DSL

对于高级用例，请使用 OpenSearch JSON 样式的查询 DSL。

SELECT id, title
FROM OPENSEARCH_FD_TABLE
ORDER BY metadata <@> $${
  "query": {
    "bool": {
      "must": { "match": { "title": "opensearch" } },
      "filter": { "term": { "category": "software" } }
    }
  },
  "sort": [
    { "price": { "order": "desc" } }
  ]
}$$
LIMIT 1;

将 OPENSEARCH_FD_TABLE 替换为表示 OpenSearch 表的外部数据表的名称。例如，my-fd-opensearch-table。

如需对 OpenSearch 数据执行混合搜索，请将 OpenSearch 令牌搜索结果与 AlloyDB 向量搜索结果联接。

SELECT *
FROM ai.hybrid_search(
  ARRAY[
    '{"limit": LIMIT,
      "weight": WEIGHT,
      "table_name": OPENSEARCH_FD_TABLE,
      "key_column": "id",
      "query_text_input": "QUERY"}'::jsonb
  ])
ORDER BY score DESC;

执行以下变量替换操作：

  • LIMIT：要返回的结果数。例如，10。

  • WEIGHT：此搜索条目对整体倒数排序融合 (RRF) 的贡献。例如，0.5。

  • OPENSEARCH_FD_TABLE：表示 OpenSearch 表的外部数据表的名称。例如，my-fd-opensearch-table。

  • QUERY：要发送到 OpenSearch 的查询。例如，"opensearch_field_name:\"cloud databases\"" 会在 opensearch_field_name 字段中搜索短语“cloud databases”。

下推式示例

为了提高查询效率，AlloyDB 会尝试将查询的以下方面直接下推到对 OpenSearch 发出的 API 调用中：

  • SELECT 字段
  • WHERE 过滤条件
  • ORDER BY 排序
  • LIMIT

如需查看说明 AlloyDB 能够和无法下推哪些方面的示例查询，请参阅下表。

查询类型 查询示例 下推的查询元素
未过滤的查询 
SELECT id, body
FROM opensearch_table
ORDER BY metadata <@> 'body:foo' DESC
LIMIT 10;
  • SELECT 字段
  • ORDER BY ... DESC 排序
  • LIMIT
完全匹配文本 
SELECT id, body
FROM opensearch_table
WHERE body = 'foo'
LIMIT 10;
  • SELECT 字段
  • WHERE 过滤条件
  • LIMIT
单字段表达式 
SELECT id, body
FROM opensearch_table
WHERE id > 10
ORDER BY metadata <@> 'body:foo'
LIMIT 10;
  • SELECT 字段
  • WHERE 过滤条件
常量表达式 
SELECT id, body
FROM opensearch_table
WHERE id > (1+1)
LIMIT 10;
  • SELECT 字段
  • WHERE 过滤条件
  • LIMIT
包含函数的表达式 
SELECT id, body
FROM opensearch_table
WHERE id > CEIL(3.14)
LIMIT 10;
  • SELECT 字段
多字段表达式 
SELECT id, body
FROM opensearch_table
WHERE dbl_field < flt_field
LIMIT 10;
  • SELECT 字段
得分过滤 
SELECT id, body, (metadata <@> 'body:bar') AS score
FROM opensearch_table
WHERE score > 0.5
ORDER by score desc
LIMIT 10;
  • SELECT 字段
  • ORDER BY ... DESC 排序
LIKE 和类似运算符 
SELECT id, body
FROM opensearch_table
WHERE id > 10 AND body LIKE '%foo%'
LIMIT 10;
  • SELECT 字段
  • WHERE id > 10 过滤条件
原始查询 
SELECT id, body
FROM opensearch_table
WHERE id < 10
ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC
LIMIT 10;
  • SELECT 字段
  • ORDER BY ... DESC 排序

问题排查

如果您在查询 OpenSearch 集群时遇到身份验证或连接问题，请检查以下常见原因：

  • HTTP 401 或 403 身份验证错误 ：验证 Secret Manager 中的 OpenSearch Secret 是否包含格式为 username:password 的字符串，以及您的 AlloyDB 服务帐号是否具有 Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) 角色。
  • 连接超时 ：验证是否在主 AlloyDB 实例上启用了出站公共 IP 连接，以及 OpenSearch 防火墙是否允许在指定端口上建立入站连接。

限制

在将 AlloyDB 连接到 OpenSearch 之前，请了解以下限制：

  • OpenSearch 集成仅适用于 PostgreSQL 主要版本 17 及更高版本。

  • AlloyDB 会读取 OpenSearch 数据，但不会写入 OpenSearch 数据。

  • AlloyDB 不会自动将数据库数据编入 OpenSearch 索引。您负责填充 OpenSearch 索引，并负责维护 AlloyDB 中的数据与 OpenSearch 中的索引数据之间的一致性。

  • AlloyDB 不会自动将架构与 OpenSearch 同步。如果 OpenSearch 索引架构发生更改，您必须手动更新相应 PostgreSQL 外部表的架构。

  • 不支持专用 OpenSearch 类型，例如 geo_point 。如需查看受支持的数据类型的完整列表，请参阅 支持的数据类型。

  • 您必须使用在 OpenSearch 集群中配置的基本身份验证（用户名和密码）。

后续步骤