パッケージの許可要件 Amazon S3 へのパッケージのアップロードパッケージのインポートと関連付けパッケージとの併用 OpenSearch パッケージの更新辞書の手動インデックス更新パッケージの関連付け解除と削除

Amazon OpenSearch サービスのカスタムパッケージ

Amazon OpenSearch Service では、ストップワードやシノニムなどのカスタム辞書ファイルをアップロードできます。また、ドメインに関連付けることができるパッケージ済みのオプションプラグインもいくつか用意されています。これら両方のタイプのファイルの総称は、パッケージです。

辞書ファイルを使用すると、頻度の高い特定の単語を無視したり、「フローズンカスタード」、「ジェラート」、「アイスクリーム」 OpenSearch などの用語を同等のものとして扱うように指示したりして、検索結果を改善できます。また、日本語 (kuromoji) 分析プラグインなどのステミングを改善することもできます。

オプションプラグインはドメインに追加機能を提供できます。例えば、Amazon Personalize プラグインを使用して、パーソナライズされた検索結果を得ることができます。オプションプラグインは ZIP-PLUGIN パッケージタイプを使用します。オプションのプラグインについての詳細は、「Amazon OpenSearch サービスのエンジンバージョン別のプラグイン」を参照してください。

パッケージの許可要件

管理者権限のないユーザーがパッケージを管理するには、特定の AWS Identity and Access Management (IAM) アクションが必要です。

es:CreatePackage- OpenSearch サービスリージョンにパッケージを作成
es:DeletePackage- OpenSearch サービスリージョンからパッケージを削除
es:AssociatePackage - パッケージをドメインに関連付ける
es:DissociatePackage - ドメインからパッケージの関連付けを解除する

カスタムパッケージが存在する Amazon S3 バケットパスまたはオブジェクトに対する許可も必要です。

ドメインアクセスポリシー内ではなく、IAM 内のすべての許可を付与します。詳細については、「Amazon OpenSearch サービスの Identity and Access Management」を参照してください。

Amazon S3 へのパッケージのアップロード

このセクションでは、オプションのプラグインパッケージが既にプリインストールされているため、カスタム辞書パッケージをアップアップロードする方法について説明します。カスタム辞書をドメインに関連付ける前に、Amazon S3 バケットにアップロードする必要があります。手順については、Amazon Simple Storage Service ユーザーガイドの「オブジェクトのアップロード」を参照してください。サポートされているプラグインをアップロードする必要はありません。

辞書に機密情報が含まれている場合は、アップロード時に S3 が管理する鍵によるサーバー側の暗号化を指定してください。 OpenSearch キーを使用して保護されている S3 上のファイルにサービスはアクセスできません。 AWS KMS

ファイルをアップロードしたら、その S3 パスを書き留めます。パスの形式は s3://bucket-name/file-path/file-name です。

テスト目的で、次のシノニムファイルを使用できます。synonyms.txt と名前を付けて保存します。


danish, croissant, pastry
ice cream, gelato, frozen custard
sneaker, tennis shoe, running shoe
basketball shoe, hightop

Hunspell 辞書など一部の辞書では、複数のファイルが使用され、ファイルシステム上に独自のディレクトリが必要になります。現時点では、 OpenSearch Service は単一ファイルのディクショナリのみをサポートしています。

パッケージのインポートと関連付け

コンソールは、カスタムディクショナリを Service にインポートする最も簡単な方法です。 OpenSearch Amazon S3 からディクショナリをインポートすると、 OpenSearch Service はパッケージの独自のコピーを保存し、そのコピーをサービスマネージドキーで AES-256 OpenSearch を使用して自動的に暗号化します。

オプションのプラグインは OpenSearch Service にあらかじめインストールされているため、自分でアップロードする必要はありませんが、プラグインをドメインに関連付ける必要があります。使用可能なプラグインは、コンソールの [パッケージ] 画面に一覧表示されます。

Amazon OpenSearch サービスコンソールで、[パッケージ] を選択します。
[パッケージのインポート] を選択します。
カスタム辞書にわかりやすい名前を付けます。
ファイルへの S3 パスを指定し、[送信] を選択します。
[パッケージ] 画面に戻ります。
パッケージのステータスが [使用可能] の場合は、パッケージを選択します。オプションのプラグインは自動的に [使用可能] になります。
[ドメインへの関連付け] を選択します。
ドメインを選択し、[関連付け] を選択します。
ナビゲーションペインで、ドメインを選択し、[パッケージ] タブに進みます。
パッケージがカスタム辞書の場合、パッケージが [使用可能] になったら ID を書き留めておきます。analyzers/id OpenSearchへのリクエストのファイルパスとして使用します。

または、SDK AWS CLI、または設定 API を使用してパッケージをインポートし、関連付けることもできます。詳細については、「AWS CLI コマンドリファレンス」と「Amazon OpenSearch サービス API リファレンス」を参照してください。

パッケージとの併用 OpenSearch

このセクションでは、カスタム辞書とオプションプラグインの両タイプのパッケージの使用方法について説明します。

カスタム辞書の使用

ファイルをドメインに関連付けた後は、トークナイザやトークンフィルターの作成時に、synonyms_path、stopwords_path、user_dictionary などのパラメータで使用できます。正確なパラメータは、オブジェクトによって異なります。synonyms_path と stopwords_path はいくつかのオブジェクトでサポートされますが、user_dictionary は kuromoji プラグイン専用です。

IK (中国語) 分析プラグインの場合、カスタム辞書ファイルをカスタムパッケージとしてアップロードしてドメインに関連付けることができます。アップロードしたカスタム辞書ファイルはプラグインによって自動的にピックアップされます。user_dictionary パラメータは必要ありません。ファイルがシノニムファイルの場合は、synonyms_path パラメータを使用します。

次の例では、シノニムファイルを新しいインデックスに追加します。


PUT my-index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "my_analyzer": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["my_filter"]
          }
        },
        "filter": {
          "my_filter": {
            "type": "synonym",
            "synonyms_path": "analyzers/F111111111",
            "updateable": true
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "standard",
        "search_analyzer": "my_analyzer"
      }
    }
  }
}

このリクエストは、標準トークナイザとシノニムトークンフィルターを使用するインデックスのカスタムアナライザーを作成します。

トークナイザは、いくつかのルールのセットに基づいて、文字のストリームをトークン (通常は単語) に分割します。最も単純な例は、空白文字に遭遇するたびに、先行する文字をトークンに分割する空白トークナイザです。より複雑な例は標準トークナイザです。これは、一連の文法ベースのルールを使用して多くの言語で動作します。
トークンフィルターは、トークンの追加、変更、削除を行います。たとえば、シノニムトークンフィルターは、シノニムリストで単語が見つかったときにトークンを追加します。ストップトークンフィルターは、ストップワードリスト内の単語を検出すると、トークンを削除します。

また、このリクエストはマッピングにテキストフィールド (description) を追加し、 OpenSearch 新しいアナライザーを検索アナライザーとして使用するように指示します。インデックスアナライザーとして、まだ標準アナライザーが使用されていることがわかります。

最後に、トークンフィルターの行 "updateable": true をメモします。このフィールドは検索アナライザーにのみ適用され、インデックスアナライザーには適用されず、後で検索アナライザーを更新したい場合に不可欠です。

テスト目的のために、インデックスにいくつかのドキュメントを追加します。


POST _bulk
{ "index": { "_index": "my-index", "_id": "1" } }
{ "description": "ice cream" }
{ "index": { "_index": "my-index", "_id": "2" } }
{ "description": "croissant" }
{ "index": { "_index": "my-index", "_id": "3" } }
{ "description": "tennis shoe" }
{ "index": { "_index": "my-index", "_id": "4" } }
{ "description": "hightop" }

次に、シノニムを使用して検索します。


GET my-index/_search
{
  "query": {
    "match": {
      "description": "gelato"
    }
  }
}

この場合、 OpenSearch 次の応答が返されます。


{
  "hits": {
    "total": {
      "value": 1,
      "relation": "eq"
    },
    "max_score": 0.99463606,
    "hits": [{
      "_index": "my-index",
      "_type": "_doc",
      "_id": "1",
      "_score": 0.99463606,
      "_source": {
        "description": "ice cream"
      }
    }]
  }
}

ヒント

辞書ファイルは、そのサイズに比例して Java ヒープ領域を使用します。たとえば、2 GiB の辞書ファイルは、ノード上で 2 GiB のヒープ領域を消費する可能性があります。大きなファイルを使用する場合は、収容に十分なヒープ領域がノードにあることを確認してください。JVMMemoryPressure メトリクスをモニタリングし、必要に応じてクラスターをスケーリングします。

オプションプラグインの使用

OpenSearch このサービスでは、 OpenSearch あらかじめインストールされているオプションのプラグインをドメインに関連付けて使用することができます。 OpenSearch オプションのプラグインパッケージは特定のバージョンと互換性があり、そのバージョンのドメインにのみ関連付けることができます。ドメインで利用可能なパッケージのリストには、そのドメインバージョンと互換性のある、サポートされているすべてのプラグインが含まれています。プラグインをドメインに関連付けると、ドメインへのインストールプロセスが開始されます。そうすれば、 OpenSearch Service にリクエストを送信する際にプラグインを参照して使用できるようになります。

プラグインの関連付けと解除には、ブルー/グリーンデプロイが必要です。詳細については、「通常は blue/green デプロイの原因となる変更」を参照してください。

オプションのプラグインには、言語アナライザーやカスタマイズされた検索結果が含まれます。例えば、Amazon Personalize Search Ranking プラグインは、機械学習を使用してお客様の検索結果をパーソナライズします。このプラグインについて詳しくは、「 OpenSearchからの検索結果のカスタマイズ」を参照してください。サポートされているすべてのプラグインのリストについては、「Amazon OpenSearch サービスのエンジンバージョン別のプラグイン」を参照してください。

Sudachi プラグイン

Sudachi プラグインの場合、ディクショナリファイルを再関連付けしても、すぐにドメインには反映されません。設定変更やその他の更新の一環として、次のブルー/グリーンデプロイがドメインで実行されると、辞書が更新されます。あるいは、更新されたデータを含む新しいパッケージを作成し、この新しいパッケージを使用して新しいインデックスを作成し、既存のインデックスを新しいインデックスに再インデックスしてから、古いインデックスを削除することもできます。インデックスの再作成方法を使用する場合は、トラフィックが中断されないようにインデックスエイリアスを使用してください。

さらに、Sudachi プラグインは API オペレーションでアップロードできるバイナリ Sudachi 辞書のみをサポートします。CreatePackageビルド済みのシステムディクショナリの詳細およびユーザーディクショナリのコンパイルプロセスについては、Sudachi のドキュメントを参照してください。

次の例は、Sudachi トークナイザでシステムディクショナリとユーザーディクショナリを使用する方法を示しています。これらのディクショナリは、タイプ TXT-DICTIONARY のカスタムパッケージとしてアップロードし、追加設定でパッケージ ID を指定する必要があります。


PUT sudachi_sample
{
  "settings": {
    "index": {
      "analysis": {
        "tokenizer": {
          "sudachi_tokenizer": {
            "type": "sudachi_tokenizer",
            "additional_settings": "{\"systemDict\": \"<system-dictionary-package-id>\",\"userDict\": [\"<user-dictionary-package-id>\"]}"
        }
        },
        "analyzer": {
          "sudachi_analyzer": {
            "filter": ["my_searchfilter"],
            "tokenizer": "sudachi_tokenizer",
            "type": "custom"
          }
        },
        "filter":{
          "my_searchfilter": {
            "type": "sudachi_split",
            "mode": "search"
          }
        }
      }
    }
  }
}

パッケージの更新

オプションのプラグインパッケージはすでに更新されているため、このセクションではカスタム辞書パッケージの更新方法についてのみ説明します。Amazon S3 に新しいバージョンの辞書をアップロードしても、Amazon OpenSearch Service のパッケージは自動的に更新されません。 OpenSearch サービスはファイルの独自のコピーを保存するため、新しいバージョンを S3 にアップロードする場合は、手動で更新する必要があります。

関連付けられた各ドメインはそのファイルの独自のコピーも保存します。検索動作を予測可能に保つために、ドメインは明示的に更新されるまで、現在のパッケージバージョンを引き続き使用します。カスタムパッケージを更新するには、Service でファイルを変更し Amazon S3 Control、 OpenSearch Service でパッケージを更新してから、更新を適用します。

OpenSearch サービスコンソールで [パッケージ] を選択します。
パッケージを選択し、[更新] を選択します。
ファイルへの S3 パスを指定し、[パッケージの更新] を選択します。
[パッケージ] 画面に戻ります。
パッケージのステータスが [使用可能] に変わったら、それを選択します。次に、関連付けられたドメインを 1 つ以上選択し、[更新の適用] を選択し、確定します。関連付けステータスが [アクティブ] に変わるまで待ちます。
次の手順は、インデックスの設定方法によって異なります。
- ドメインが Elasticsearch 7.8 OpenSearch 以降を実行していて、updateable フィールドが true に設定された検索アナライザーのみを使用している場合は、それ以上の操作は必要ありません。 OpenSearch サービスは _plugins/_refresh_search_analyzers API を使用してインデックスを自動的に更新します。
- ドメインで Elasticsearch 7.7 以前を実行している場合、インデックスアナライザーを使用している場合、またはフィールドを使用していない場合は、を参照してください。updateable 辞書の手動インデックス更新

コンソールは最も単純な方法ですが、、SDK AWS CLI、または設定 API を使用してサービスパッケージを更新することもできます。 OpenSearch 詳細については、「AWS CLI コマンドリファレンス」と「Amazon OpenSearch サービス API リファレンス」を参照してください。

コンソールでパッケージを手動で更新する代わりに、SDK を使用して更新プロセスを自動化できます。次のサンプル Python スクリプトは、新しいパッケージファイルを Amazon S3 にアップロードし、 OpenSearch Service 内のパッケージを更新し、新しいパッケージを指定されたドメインに適用します。更新が成功したことを確認したら、 OpenSearch新しいシノニムが適用されたことを示すサンプル呼び出しを行います。

host、region、file_name、bucket_name、s3_key、package_id、domain_name、および query の値を指定する必要があります。


from requests_aws4auth import AWS4Auth
import boto3
import requests
import time
import json
import sys

host = ''  # The OpenSearch domain endpoint with https:// and a trailing slash. For example, https://my-test-domain.us-east-1.es.amazonaws.com/
region = ''  # For example, us-east-1
file_name = ''  # The path to the file to upload
bucket_name = ''  # The name of the S3 bucket to upload to
s3_key = ''  # The name of the S3 key (file name) to upload to
package_id = ''  # The unique identifier of the OpenSearch package to update
domain_name = ''  # The domain to associate the package with
query = ''  # A test query to confirm the package has been successfully updated

service = 'es'
credentials = boto3.Session().get_credentials()
client = boto3.client('opensearch')
awsauth = AWS4Auth(credentials.access_key, credentials.secret_key,
                   region, service, session_token=credentials.token)


def upload_to_s3(file_name, bucket_name, s3_key):
    """Uploads file to S3"""
    s3 = boto3.client('s3')
    try:
        s3.upload_file(file_name, bucket_name, s3_key)
        print('Upload successful')
        return True
    except FileNotFoundError:
        sys.exit('File not found. Make sure you specified the correct file path.')


def update_package(package_id, bucket_name, s3_key):
    """Updates the package in OpenSearch Service"""
    print(package_id, bucket_name, s3_key)
    response = client.update_package(
        PackageID=package_id,
        PackageSource={
            'S3BucketName': bucket_name,
            'S3Key': s3_key
        }
    )
    print(response)


def associate_package(package_id, domain_name):
    """Associates the package to the domain"""
    response = client.associate_package(
        PackageID=package_id, DomainName=domain_name)
    print(response)
    print('Associating...')


def wait_for_update(domain_name, package_id):
    """Waits for the package to be updated"""
    response = client.list_packages_for_domain(DomainName=domain_name)
    package_details = response['DomainPackageDetailsList']
    for package in package_details:
        if package['PackageID'] == package_id:
            status = package['DomainPackageStatus']
            if status == 'ACTIVE':
                print('Association successful.')
                return
            elif status == 'ASSOCIATION_FAILED':
                sys.exit('Association failed. Please try again.')
            else:
                time.sleep(10)  # Wait 10 seconds before rechecking the status
                wait_for_update(domain_name, package_id)


def sample_search(query):
    """Makes a sample search call to OpenSearch"""
    path = '_search'
    params = {'q': query}
    url = host + path
    response = requests.get(url, params=params, auth=awsauth)
    print('Searching for ' + '"' + query + '"')
    print(response.text)

注記

を使用してスクリプトを実行したときに「package not found」エラーが表示される場合は AWS CLI、Boto3 が ~/.aws/config で指定されているリージョン (S3 バケットがあるリージョンではない) を使用している可能性があります。aws configure を実行して正しいリージョンを指定するか、明示的にクライアントにそのリージョンを追加します。


client = boto3.client('opensearch', region_name='us-east-1')

辞書の手動インデックス更新

手動によるインデックス更新はカスタム辞書にのみ適用され、オプションのプラグインには適用されません。更新された辞書を使用するには、次の条件のいずれかを満たしている場合、インデックスを手動で更新する必要があります。

ドメインは Elasticsearch 7.7 以前を実行しています。
カスタムパッケージをインデックスアナライザーとして使用しています。
検索アナライザーとしてカスタムパッケージを使用していますが、[更新可能] フィールドは含まれていません。

新しいパッケージファイルでアナライザーを更新するには、次の 2 つのオプションがあります。

更新するインデックスを閉じて開きます。
```
POST my-index/_close
POST my-index/_open
```

インデックスを再作成します。まず、更新されたシノニムファイル (または完全に新しいファイル) を使用するインデックスを作成します。UTF-8 のみがサポートされていることに注意してください。


PUT my-new-index
{
  "settings": {
    "index": {
      "analysis": {
        "analyzer": {
          "synonym_analyzer": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["synonym_filter"]
          }
        },
        "filter": {
          "synonym_filter": {
            "type": "synonym",
            "synonyms_path": "analyzers/F222222222"
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "description": {
        "type": "text",
        "analyzer": "synonym_analyzer"
      }
    }
  }
}

次に、古いインデックスをその新しいインデックスに再作成します。


POST _reindex
{
  "source": {
    "index": "my-index"
  },
  "dest": {
    "index": "my-new-index"
  }
}

インデックスアナライザーを頻繁に更新する場合は、インデックスエイリアスを使用して、最新のインデックスへの一貫したパスを維持します。


POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "my-index",
        "alias": "latest-index"
      }
    },
    {
      "add": {
        "index": "my-new-index",
        "alias": "latest-index"
      }
    }
  ]
}

古いインデックスが必要ない場合は、削除します。


DELETE my-index

パッケージの関連付け解除と削除

カスタム辞書であれオプションのプラグインであれ、ドメインからパッケージを切り離すと、新しいインデックスを作成するときにそのパッケージを使用できなくなります。パッケージの関連付けが解除されると、そのパッケージを使用していた既存のインデックスはそのパッケージを使用できなくなります。関連付けを解除する前に、どのインデックスからもパッケージを削除する必要があります。削除しないと、関連付けの解除は失敗します。

コンソールは、パッケージをドメインから切り離し、サービスから削除する最も簡単な方法です。 OpenSearch OpenSearch サービスからパッケージを削除しても、Amazon S3 の元の場所からパッケージは削除されません。

https://aws.amazon.com にアクセスし、[コンソールにサインイン] を選択します。
[分析] で [Amazon OpenSearch サービス] を選択します。
ナビゲーションペインで、ドメインを選択し、[パッケージ] タブを選択します。
パッケージを選択して、[アクション] を選択し、[関連付け解除] を選択します。選択内容を確認します。
パッケージがリストから消えるのを待ちます。ブラウザを更新することが必要な場合があります。
パッケージを他のドメインで使用する場合は、ここで停止します。パッケージの削除を続行するには (カスタム辞書の場合)、ナビゲーションペインで [パッケージ] を選択します。
パッケージを選択し、[削除] を選択します。

または、SDK AWS CLI、または設定 API を使用してパッケージの関連付けを解除したり削除したりします。詳細については、「AWS CLI コマンドリファレンス」と「Amazon OpenSearch サービス API リファレンス」を参照してください。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

データの検索

SQL のサポート