このページでは、コンテナ デプロイオプションを使用する 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を使用してサービスアカウントを作成します。このサービスアカウントに、AlloyDB AI を構成するで Secret Manager にアクセスする権限を付与します。
JSON 形式でサービスアカウントキーを作成し、private-key.json ファイルに保存してダウンロードします。

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

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

AlloyDB Omni は、Secret Manager から Elasticsearch API キーを保存して読み取ります。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 PRECISIONremote_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 クエリ
クエリ 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}

クエリ 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 フィールドで「quantum computing」というフレーズを検索します。サポートされているデータ型に記載されているすべてのクエリタイプをクエリで使用できます。

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

プッシュダウンの例

クエリをより効率的にするために、AlloyDB Omni はクエリの次の要素を Elasticsearch への API 呼び出しに直接 push down しようとします。

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

クエリ DSL

ハイブリッド検索

プッシュダウンの例

トラブルシューティング

制限事項

次のステップ

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

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