このページでは、コンテナ デプロイオプションを使用する AlloyDB Omni バージョン 16.8.0 について説明します。別のデプロイオプションを選択してください。

Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

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

ドキュメントのバージョンを選択してください。

AlloyDB Omni で外部データラッパー（FDW）と外部テーブルを作成すると、Elasticsearch に保存されているデータにアクセスして検索できます。

始める前に

始める前に、次のことを行ってください。

コンテナを使用して AlloyDB Omni をインストールする。
デプロイして、本番環境で Elasticsearch を実行します。
AlloyDB Omni が Elasticsearch クラスタへのアクセスに使用できる読み取り専用の個人/ユーザー API キーを作成します。

サービスアカウントを作成する

AlloyDB Omni では、Secret Manager の認証と使用に Google Cloud 権限を持つサービスアカウントが必要です。AlloyDB Omni は、Secret Manager を使用して Elasticsearch API キーを保存します。

AlloyDB Omni のサービスアカウントをまだ作成していない場合は、次の手順で作成します。

Google Cloudを使用してサービスアカウントを作成します。このサービスアカウントに Secret Manager へのアクセス権を付与するには、AlloyDB AI を構成するをご覧ください。
JSON 形式でサービスアカウントキーを作成し、private-key.json ファイルに保存してダウンロードします。

注: サービスアカウントキーが正しく管理されていない場合は、セキュリティリスクが発生します。秘密鍵のセキュリティと、サービスアカウントキーを管理するためのベストプラクティスで説明されているその他の操作は、ユーザーの責任で実施してください。サービスアカウントキーを作成できない場合は、組織でサービスアカウントキーの作成が無効になっている可能性があります。詳細については、デフォルトで安全な組織リソースの管理をご覧ください。
外部ソースからサービスアカウントキーを取得した場合は、使用前に検証する必要があります。詳細については、外部ソースの認証情報のセキュリティ要件をご覧ください。
作成したサービスアカウントキーを KEY_PATH にコピーします。鍵のパスは、AlloyDB Omni コンテナを実行するユーザーがアクセスして所有できるホスト上のパスである必要があります。

Elasticsearch API キーを Secret Manager に保存する

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

AlloyDB Omni サービスアカウントにシークレットの読み取り権限を付与してください。詳細については、シークレットへのアクセスを管理するをご覧ください。

AlloyDB Omni 用に AlloyDB AI を構成する

AlloyDB Omni 用に AlloyDB AI を構成するには、AlloyDB Omni 用に AlloyDB AI を構成するをご覧ください。最初のステップはスキップしてください。

external_search_fdw 拡張機能を有効にして構成する

Elasticsearch との統合を開始するには、次の手順に沿って external_search_fdw AlloyDB Omni 拡張機能を有効にして構成します。

external_search_fdw 拡張機能を有効にします。
```
CREATE EXTENSION external_search_fdw;
```
外部データサーバーを介して Elasticsearch クラスタへのアクセスを構成します。
```
CREATE SERVER ELASTICSEARCH_SERVER_NAME
FOREIGN DATA WRAPPER external_search_fdw
OPTIONS (server 'ELASTICSEARCH_SERVER_HOST_PORT',
         search_provider 'elastic',
         auth_mode 'secret_manager',
         auth_method 'AUTH_METHOD',
         secret_path 'SECRET_PATH',
         max_deadline_ms 'MAX_DEADLINE',
         pagination_num_results 'PAGINATION_NUM_RESULTS',
         pagination_context_timeout_ms 'PAGINATION_CONTEXT_TIMEOUT');
```
次の変数を置き換えます。
- ELASTICSEARCH_SERVER_NAME: 外部データサーバーの名前。例: my-elasticsearch-server
- ELASTICSEARCH_SERVER_HOST_PORT: Elasticsearch クラスタの一般公開 URL。例: https://node1.elastic.test.com:9200
- AUTH_METHOD: 使用する認証のタイプ。次のいずれかを選択できます。
  - ApiKey: Elasticsearch の個人用/ユーザー API キー。
  - Basic: Elasticsearch のユーザー名とパスワード。
- SECRET_PATH: Elasticsearch 認証情報への Secret Manager パス。例: projects/123456789012/secrets/apikey/versions/1123456789012 は、 Google Cloud プロジェクト ID を表します。
- （省略可）MAX_DEADLINE: AlloyDB Omni が Elasticsearch からのレスポンスを待つ最大時間（ミリ秒単位）。この値は、AlloyDB Omni インスタンスと Elasticsearch インスタンスのロケーションに基づいて設定します。デフォルト値は 10000 です。
- （省略可）PAGINATION_NUM_RESULTS: Elasticsearch からバッチごとに取得される結果の最大数。より多くの結果がリクエストされた場合、AlloyDB Omni はこのサイズの複数のバッチで結果を取得します。デフォルト値は 32 です。
- （省略可）PAGINATION_CONTEXT_TIMEOUT: Elasticsearch がページネーションリクエストコンテキストをアクティブに保つ時間（ミリ秒単位）。デフォルト値は 30000 です。
Elasticsearch サーバーの PostgreSQL ユーザーマッピングを定義します。PostgreSQL FDW が機能するには、このユーザーマッピングが必要です。AlloyDB Omni は、REST 認証ヘッダーを使用して認証します。
```
CREATE USER MAPPING FOR CURRENT_USER
       SERVER ELASTICSEARCH_SERVER_NAME;
```
外部データテーブルを使用して、Elasticsearch データのスキーマを構成します。
```
CREATE FOREIGN TABLE ELASTICSEARCH_FD_TABLE(
    metadata external_search_fdw_schema.OpaqueMetadata,
    ELASTICSEARCH_FIELDS)
       SERVER ELASTICSEARCH_SERVER_NAME
       OPTIONS(remote_table_name 'ELASTICSEARCH_INDEX_NAME');
```
次の新しい変数を置き換えます。
- ELASTICSEARCH_FD_TABLE: Elasticsearch テーブルを表す外部データテーブルの名前。例: my-fd-elasticsearch-table
- ELASTICSEARCH_FIELDS: 次の形式の Elasticsearch フィールドスキーマ定義のカンマ区切りのリスト: elasticsearch_field_name PG_DATA_TYPE。例: elasticsearch_boolean_field_name BOOLEAN, elasticsearch_double_field_name DOUBLE PRECISIONこれらのフィールドは、remote_field_name オプションが付加されていない限り、Elasticsearch のフィールド名と一致する必要があります。例: elasticsearch_foo OPTIONS (remote_field_name 'elasticsearch_FOO')
  
  AlloyDB Omni で定義できる Elasticsearch データ型の一覧については、サポートされているデータ型をご覧ください。
- ELASTICSEARCH_INDEX_NAME: Elasticsearch インデックスの名前。例: my-elasticsearch-index

サポートされるデータタイプ

AlloyDB Omni は、次の Elasticsearch データ型をサポートしています。

データ型	PostgreSQL タイプ
`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` `annotated_text` `keyword` `constant_keyword` `wildcard`	`TEXT`
`unsigned_long`	`NUMERIC`

Elasticsearch データのクエリ

AlloyDB Omni は SQL クエリを取得し、Elasticsearch REST API クエリに変換します。この変換中に、AlloyDB Omni は、SQL クエリの LIMIT など、クエリの ID を変更せずに、可能な限り多くのクエリロジックをプッシュダウンしようとします。ただし、特定の Elasticsearch フィールドをプッシュダウンしないように指定する場合や、クエリロジックをプッシュダウンできない場合があります。たとえば、LIKE などのテキスト一致演算子はプッシュダウンできません。プッシュダウンできるものとできないものの例については、プッシュダウンの例をご覧ください。

LIMIT が pagination_num_results より大きく設定されている場合、または LIMIT が指定されていないか、プッシュダウンできない場合、AlloyDB Omni はリソースを大量に消費する可能性がある Scroll API を使用します。

Scroll API はリソースを大量に消費する可能性があるため、EXPLAIN VERBOSE を使用してクエリを調べ、どの API が使用されているかを確認することをおすすめします。Scroll API の使用を制限し、LIMIT を使用すると、パフォーマンスが向上します。

Elasticsearch データをクエリするには、次のオプションがあります。

標準 SQL クエリ
Query DSL
ハイブリッド検索

標準 SQL クエリ

標準 SQL クエリは、Elasticsearch の Lucene 構文を使用して記述できます。

標準 SQL クエリを実行するには、次のクエリ例をご覧ください。

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

次の変数を置き換えます。

ELASTICSEARCH_FD_TABLE: Elasticsearch テーブルを表す外部データテーブルの名前。例: my-fd-elasticsearch-table
（省略可）FILTER: Elasticsearch クエリに適用するフィルタ。例: AND qubits < 105
QUERY: Elasticsearch に送信するクエリ。クエリの例については、次のリストをご覧ください。
- body:quantum body:computing
- body:(quantum computing)
- body:(quantum AND computing)
- body:"quantum computing"
- body:"quantum computing" AND qubits:[* TO 105}

Query DSL

Query DSL は、高度なユースケースにおすすめの Elasticsearch のフル機能の JSON スタイルのクエリ言語です。Query DSL を使用すると、SQL クエリ構文では表現できない複雑な検索、フィルタリング、集計を実行できます。

Query DSL を使用してクエリを実行するには、次のクエリの例をご覧ください。

SELECT id, body
FROM ELASTICSEARCH_FD_TABLE
ORDER BY
  metadata <@> $${
    "query": {
      "bool": {
        "must": [
          {
            "query_string": {
              "query" : "QUERY"
            }
          }
        ],
        "filter": [
          {
            "range": { 
              "id": { 
                "lt": "10"
              }
            }
          }
        ]
      }
    },
    "sort": [
      {
        "id": {
          "order": "desc"
        }
      }
    ]
  }$$
LIMIT 1;

次の変数を置き換えます。

ELASTICSEARCH_FD_TABLE: Elasticsearch テーブルを表す外部データテーブルの名前。例: my-fd-elasticsearch-table
QUERY: Elasticsearch に送信するクエリ。例: "elasticsearch_field_name:\"quantum computing\" OR int_field:[* TO 3]"

Query DSL では、query、filter、sort の式のみを伝播する必要があります。

ハイブリッド検索

Elasticsearch データでハイブリッド検索を行うには、次の検索例をご覧ください。

SELECT *
FROM
  ai.hybrid_search(
    ARRAY[
      '{"limit": LIMIT,
        "data_type": "external_search_fdw",
        "weight": WEIGHT,
        "table_name": "ELASTICSEARCH_FD_TABLE",
        "key_column": "DOCUMENT_ID_COLUMN_NAME",
        "query_text_input": QUERY}'::jsonb],
    NULL::TEXT,
    'RRF',
    FALSE)
ORDER BY score DESC;

次の変数を置き換えます。

LIMIT: 返される結果の数。例: 3
WEIGHT: この検索エントリの Reciprocal Rank Fusion（RRF）全体に対する貢献度。例: 0.5重みを指定しない場合、重みは均等に分散されます。詳細については、ハイブリッド検索関数のパラメータをご覧ください。
ELASTICSEARCH_FD_TABLE: Elasticsearch テーブルを表す外部データテーブルの名前。例: my-fd-elasticsearch-table
DOCUMENT_ID_COLUMN_NAME: ドキュメント ID 列の名前。
QUERY: Elasticsearch に送信するクエリ。たとえば、"elasticsearch_field_name:\"quantum computing\"" は elasticsearch_field_name フィールドで「量子コンピューティング」というフレーズを検索します。サポートされているデータ型で説明されているすべてのクエリ型をクエリで使用できます。

ハイブリッド検索で使用できるパラメータの詳細については、ハイブリッド検索関数のパラメータをご覧ください。

プッシュダウンの例

クエリの効率を高めるため、AlloyDB Omni は、Elasticsearch への API 呼び出しにクエリの次の側面を直接プッシュダウンしようとします。

SELECT フィールド
WHERE 個のフィルタ
ORDER BY 並べ替え
LIMIT

AlloyDB Omni でプッシュダウンできる側面とプッシュダウンできない側面を示すクエリの例については、次の表をご覧ください。

クエリの形式	クエリの例	プッシュダウンされたクエリ要素
フィルタなしのクエリ	SELECT id, body FROM elasticsearch_table ORDER BY metadata <@> 'body:foo' DESC LIMIT 10;	`SELECT` フィールド `ORDER BY ... DESC` 並べ替え `LIMIT`
テキストの完全一致	SELECT id, body FROM elasticsearch_table WHERE body = 'foo' LIMIT 10;	`SELECT` フィールド `WHERE` 個のフィルタ `LIMIT`
単一フィールド式	SELECT id, body FROM elasticsearch_table WHERE id > 10 ORDER BY metadata <@> 'body:foo' LIMIT 10;	`SELECT` フィールド `WHERE` 個のフィルタ
定数式	SELECT id, body FROM elasticsearch_table WHERE id > (1+1) LIMIT 10;	`SELECT` フィールド `WHERE` 個のフィルタ `LIMIT`
関数を含む式	SELECT id, body FROM elasticsearch_table WHERE id > CEIL(3.14) LIMIT 10;	`SELECT` フィールド
複数フィールドの式	SELECT id, body FROM elasticsearch_table WHERE dbl_field < flt_field LIMIT 10;	`SELECT` フィールド
スコアのフィルタリング	SELECT id, body, (metadata <@> 'body:bar') AS score FROM elasticsearch_table WHERE score > 0.5 ORDER by score desc LIMIT 10;	`SELECT` フィールド `ORDER BY ... DESC` 並べ替え
`LIKE` などの演算子	SELECT id, body FROM elasticsearch_table WHERE id > 10 AND body LIKE '%foo%' LIMIT 10;	`SELECT` フィールド `WHERE id > 10` 個のフィルタ
未加工のクエリ	SELECT id, body FROM elasticsearch_table WHERE id < 10 ORDER BY metadata <@> $${"query": { "match_all": {}}}$$ DESC LIMIT 10;	`SELECT` フィールド `ORDER BY ... DESC` 並べ替え

トラブルシューティング

Elasticsearch クラスタのクエリ時に認証または接続の問題が発生した場合は、次の点を確認してください。

HTTP 401 または 403 認証エラー: Secret Manager の Elasticsearch シークレットに auth_method（ApiKey または Basic）の有効な認証情報が含まれていること、サービスアカウントに secretmanager.secretAccessor 権限があることを確認します。
接続タイムアウト: AlloyDB Omni と Elasticsearch エンドポイント間のネットワークルールとファイアウォール構成を確認します。

制限事項

AlloyDB Omni は Elasticsearch データを読み取りますが、書き込みは行いません。
AlloyDB Omni と Elasticsearch 間のデータの同期は、ユーザーが行う必要があります。
geo_point などの特殊な Elasticsearch タイプはサポートされていません。詳細については、サポートされているデータ型をご覧ください。

AlloyDB Omni から Elasticsearch データにアクセスする コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

始める前に

サービス アカウントを作成する

Elasticsearch API キーを Secret Manager に保存する

AlloyDB Omni 用に AlloyDB AI を構成する

external_search_fdw 拡張機能を有効にして構成する

サポートされるデータタイプ

Elasticsearch データのクエリ

標準 SQL クエリ

Query DSL

ハイブリッド検索

プッシュダウンの例

トラブルシューティング

制限事項

次のステップ

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

サービスアカウントを作成する