AlloyDB から OpenSearch データにアクセスする

プレビュー版 — OpenSearch FDW

この機能は サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります 。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、 リリース ステージの説明をご覧ください。

AlloyDB の外部検索統合を使用して、OpenSearch に保存されているデータにアクセスして検索できます。この統合により、データを移動またはコピーせずに、OpenSearch インデックスを AlloyDB のリレーショナル テーブルに結合できます。

始める前に

始める前に、次のことを完了していることを確認してください。

• クラスタを作成する。

• アウトバウンド接続を有効にする プライマリ AlloyDB インスタンスで

• アクセス可能なパブリック エンドポイントを使用して OpenSearch を作成して構成する

• OpenSearch クラスタでセキュリティ プラグイン を有効にし、読み取り権限のみのユーザー を内部ユーザー データベースに作成するAlloyDB は、これらの認証情報を使用して OpenSearch クラスタにアクセスします。

OpenSearch の認証情報を Secret Manager に保存する

AlloyDB は、OpenSearch の認証情報を Secret Manager に保存して読み取ります。Secret Manager の使用方法の詳細については、 Secret Manager を使用してシークレットを作成してアクセスするをご覧ください。

AlloyDB サービス アカウントに、Secret Manager からシークレットを読み取るための Secret Manager Secret アクセサー（roles/secretmanager.secretAccessor）ロールがあることを確認します。詳細については、 Secret Manager を使用してシークレットを作成してアクセスするをご覧ください。

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 クラスタの一般公開 URL（エンドポイント）。

   • 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 クエリ

検索式には、Lucene 構文で標準 SQL を使用できます。

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。

**注:** クエリ DSL の場合、クエリ、フィルタ、並べ替えの式のみを伝播する必要があります。

ハイブリッド検索

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: この検索エントリが Reciprocal Rank Fusion（RRF）全体に与える影響。例: 0.5。

• OPENSEARCH_FD_TABLE: OpenSearch テーブルを表す外部データテーブルの名前。例: my-fd-opensearch-table。

• QUERY: OpenSearch に送信するクエリ。たとえば、"opensearch_field_name:\"cloud databases\"" は、"cloud databases" というフレーズを opensearch_field_name フィールドで検索します。

注: 検索エントリの data_type フィールドと、id_type、fusion_algorithm、include_json_output 関数パラメータは省略可能で、デフォルト値が使用されます。たとえば、融合アルゴリズムのデフォルトは RRF です。

プッシュダウンの例

クエリを効率化するため、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 シークレットに username:password の形式の文字列が含まれており、AlloyDB サービス アカウントに Secret Manager Secret アクセサー（roles/secretmanager.secretAccessor）ロールがあることを確認します。
• 接続タイムアウト: プライマリ AlloyDB インスタンスでアウトバウンド パブリック IP 接続が有効になっており、OpenSearch ファイアウォールで指定されたポートでの受信接続が許可されていることを確認します。

制限事項

AlloyDB を OpenSearch に接続する前に、次の制限事項を理解しておいてください。

• OpenSearch 統合は、PostgreSQL のメジャー バージョン 17 以降でのみ使用できます。

• AlloyDB は OpenSearch データを読み取りますが、書き込みは行いません。

• AlloyDB は、データベース データを OpenSearch に自動的にインデックス登録しません。OpenSearch インデックスへのデータの入力と、AlloyDB のデータと OpenSearch のインデックス付きデータの整合性の維持は、お客様の責任で行ってください。

• AlloyDB は、スキーマを OpenSearch と自動的に同期しません。OpenSearch インデックス スキーマが変更された場合は、対応する PostgreSQL 外部テーブルのスキーマを手動で更新する必要があります。

• geo_point などの特殊な OpenSearch 型はサポートされていません。サポートされているデータ型の完全なリストについては、 サポートされているデータ型をご覧ください。

• OpenSearch クラスタで構成された基本認証（ユーザー名とパスワード）を使用する必要があります。

次のステップ

• Elasticsearch データにアクセスする方法を学習する。
• Solr データにアクセスする方法を学習する。
• ハイブリッド ベクトル類似性検索を実行する方法を学習する。