このページは Cloud Translation API によって翻訳されました。

メディア検索をフィルタする

メディア検索アプリがある場合は、メタデータを使用して検索クエリをフィルタできます。このページでは、メタデータフィールドを使用して検索を特定のドキュメントセットに制限する方法について説明します。

始める前に

メディアアプリとデータストアを作成し、データを取り込んだことを確認します。詳細については、メディアデータストアを作成するとメディアアプリを作成するをご覧ください。

ドキュメントの例

以下のメディアドキュメントの例をご確認ください。このページを読む際にこれらを参照できます。

{"id":"172851","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: Creating the World of Pandora (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/172851\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"243308","schemaId":"default_schema","jsonData":"{\"title\":\"Capturing Avatar (2010)\",\"categories\":[\"Documentary\"],\"uri\":\"http://mytestdomain.movie/content/243308\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"280218","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar: The Way of Water (2022)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\"],\"uri\":\"http://mytestdomain.movie/content/280218\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}
{"id":"72998","schemaId":"default_schema","jsonData":"{\"title\":\"Avatar (2009)\",\"categories\":[\"Action\",\"Adventure\",\"Sci-Fi\",\"IMAX\"],\"uri\":\"http://mytestdomain.movie/content/72998\",\"available_time\":\"2023-01-01T00:00:00Z\",\"media_type\":\"movie\"}"}

フィルタ式の構文

検索フィルタの定義に使用するフィルタ式の構文を理解しておきます。フィルタ式の構文は、次の Extended Backus-Naur form に要約できます。

  # A single expression or multiple expressions that are joined by "AND" or "OR".
  filter = expression, { " AND " | "OR", expression };
  # Expressions can be prefixed with "-" or "NOT" to express a negation.
  expression = [ "-" | "NOT " ],
    # A parenthetical expression.
    | "(", expression, ")"
    # A simple expression applying to a text field.
    # Function "ANY" returns true if the field contains any of the literals.
    ( text_field, ":", "ANY", "(", literal, { ",", literal }, ")"
    # A simple expression applying to a numerical field. Function "IN" returns true
    # if a field value is within the range. By default, lower_bound is inclusive and
    # upper_bound is exclusive.
    | numerical_field, ":", "IN", "(", lower_bound, ",", upper_bound, ")"
    # A simple expression that applies to a numerical field and compares with a double value.
    | numerical_field, comparison, double );
    # Datetime field
    | datetime_field, comparison, literal_iso_8601_datetime_format);
  # A lower_bound is either a double or "*", which represents negative infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  lower_bound = ( double, [ "e" | "i" ] ) | "*";
  # An upper_bound is either a double or "*", which represents infinity.
  # Explicitly specify inclusive bound with the character 'i' or exclusive bound
  # with the character 'e'.
  upper_bound = ( double, [ "e" | "i" ] ) | "*";
  # Supported comparison operators.
  comparison = "<=" | "<" | ">=" | ">" | "=";
  # A literal is any double quoted string. You must escape backslash (\) and
  # quote (") characters.
  literal = double quoted string;
  text_field = text field - for example, category;
  numerical_field = numerical field - for example, score;
  datetime_field = field of datetime data type - for example available_time;
  literal_iso_8601_datetime_format = either a double quoted string representing ISO 8601 datetime or a numerical field representing microseconds from unix epoch.

メディア検索をフィルタする

メタデータを使用してメディア検索をフィルタする手順は次のとおりです。

アプリ ID を確認します。アプリ ID がすでにある場合は、次のステップに進みます。
1. Google Cloud コンソールで、[AI Applications] ページに移動します。
  
  [アプリ] に移動
2. [アプリ] ページで、アプリの名前を見つけ、[ID] 列からアプリの ID を取得します。
フィルタするドキュメントフィールドを特定します。たとえば、始める前にのドキュメントでは、categories フィールドをフィルタとして使用できます。

フィルタ式では、インデックス登録可能なフィールドのみを使用できます。フィールドがインデックス登録可能かどうかを判断するには、次の操作を行います。
1. Google Cloud コンソールで、[AI アプリケーション] ページに移動し、ナビゲーションメニューで [データストア] をクリックします。
  
  [データストア] ページに移動
2. データストアの名前をクリックします。
3. [名前] 列で、データストアをクリックします。
4. [スキーマ] タブをクリックして、データストアのスキーマを表示します。フィールドの [Indexable] が次のいずれかの場合:
  - が選択された場合、そのフィールドは検索のフィルタリングに使用できる状態になります。手順 3 はスキップします。
  - が選択されていない場合は、手順 3 に沿ってフィールドのインデックス登録を有効にします。
  - が使用できない場合、フィールドにインデックスを付けることはできません。
categories フィールドなどのフィールドをフィルタ可能にするには、次の操作を行います。
1. Google Cloud コンソールで、[AI アプリケーション] ページに移動し、ナビゲーションメニューで [アプリ] をクリックします。
  
  [アプリ] ページに移動
2. メディア検索アプリをクリックします。
3. ナビゲーションメニューで [データ] をクリックします。
4. [スキーマ] タブをクリックします。このタブには、現在のフィールド設定が表示されます。
5. [編集] をクリックします。
6. まだ選択されていない場合は、[カテゴリ] 行の [インデックス登録可能] チェックボックスをオンにして、[保存] をクリックします。
7. スキーマの編集が反映されるまで 6 時間待ちます。6 時間経過したら、次のステップに進みます。

検索結果を取得します。

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/engines/APP_ID/servingConfigs/default_search:search" \
-d '{
"query": "QUERY",
"filter": "FILTER"
}'

次のように置き換えます。

PROJECT_ID: 実際のプロジェクトの ID。
APP_ID: アプリの ID。
QUERY: 検索するクエリテキスト。
FILTER: フィルタ式を使用して検索結果をフィルタリングするためのテキストフィールド。

たとえば、始める前にセクションの映画を検索し、（1）「アバター」という単語が含まれ、（2）「ドキュメンタリー」カテゴリに属する映画のみを検索結果に表示したいとします。そのためには、呼び出しに次のステートメントを含めます。

"query": "avatar",
"filter": "categories: ANY(\"Documentary\")"

詳細については、search メソッドをご覧ください。

クリックしてレスポンスの例を表示します。

前述の手順のような検索を行うと、次のようなレスポンスが返されます。レスポンスにはアバターのドキュメンタリーのみが含まれています。

{
  "results": [
    {
      "id": "243308",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/243308",
        "id": "243308",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "title": "Capturing Avatar (2010)",
          "uri": "http://mytestdomain.movie/content/243308",
          "media_type": "movie"
        }
      }
    },
    {
      "id": "172851",
      "document": {
        "name": "projects/431678329718/locations/global/collections/default_collection/dataStores/rdds3_1698205785399/branches/0/documents/172851",
        "id": "172851",
        "structData": {
          "categories": [
            "Documentary"
          ],
          "uri": "http://mytestdomain.movie/content/172851",
          "media_type": "movie",
          "title": "Avatar: Creating the World of Pandora (2010)"
        }
      }
    }
  ],
  "totalSize": 2,
  "attributionToken": "XfBcCgwIvIzJqwYQ2_qNxwMSJDY1NzEzNmY1LTAwMDAtMmFhMy05YWU3LTE0MjIzYmIwOGVkMiIFTUVESUEqII6-nRXFy_MXnIaOIsLwnhXUsp0VpovvF6OAlyKiho4i",
  "guidedSearchResult": {},
  "summary": {}
}

利用可能なドキュメントのフィルタ

検索結果で利用可能なドキュメントのみを返すようにするには、クエリにこのフィルタを含める必要があります。利用可能なドキュメントとは、available_time が過去の日付で、expire_time が指定されていないか、将来の日付に設定されているドキュメントです。

現在利用可能なドキュメントのみを返すフィルタ:

  available_time <= \"DATE_TIME\" AND expire_time > \"DATE_TIME\"

DATE_TIME は、今日の日付（2025-04-21、2025-04-21T00:00:00Z など）に置き換えます。

評価、人物、組織のフィルタ

メディアのレーティング、人物、組織のフィルタ構文は一意であり、上記のパターンには従いません。次の例とコピー可能なフィルタスニペットを使用して、評価、人物、組織のフィルタを作成します。

フィルタは、Google の事前定義スキーマを使用しているか、独自のカスタムスキーマを使用しているかによって異なります。

評価、人物、組織のフィルタ（Google 事前定義スキーマ）

評価、人物、組織のフィルタの構文と例は次のとおりです。

評価でフィルタ: 特定のソースの評価でフィルタします。
```
 rating(RATING_SOURCE, aggregate_ratings.rating_score) OPERATOR RATING_SCORE
```
次のように置き換えます。
- RATING_SOURCE: 評価のソース。事前定義されたスキーマの場合、これは aggregate_ratings.rating_source フィールドの値です。
- OPERATOR: 比較演算子（<=、<、>=、>、=）のいずれか
- RATING_SCORE: [1,5] の範囲の評価値。事前定義されたスキーマの場合、これは aggregate_ratings.rating_score フィールドの値です。
例: このフィルタは、IMDB の評価が 2 つ星半を超える映画に検索を制限します。かっこ内の値は、IMDB レーティングの値に解決されます。
```
"filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"
```
Filter people: 指定されたロールのユーザーの名前でフィルタします。
```
person(PERSONS_ROLE, persons.name): ANY NAME_STRING
```
次のように置き換えます。
- PERSONS_ROLE: 事前定義されたスキーマの場合、これは persons.role フィールドの値（director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel、custom-role）です。
- NAME_STRING: 指定されたロールを持つユーザーの名前。1 つ以上の名前を指定できます。ステップ 4 のような curl コマンドでは、二重引用符をバックスラッシュ文字でエスケープする必要があります。
例: このフィルタは、出演者のいずれかがブラッドピットまたはケイトウィンスレットである映画に検索を制限します。
```
filter: "person(actor, persons.name): ANY(\"Brad Pitt\", \"Kate Winslet\")"
```
組織をフィルタする: 特定のロールの組織名でフィルタします。
```
org(ORG_ROLE, organization.name): ANY NAME_STRING
```
次のように置き換えます。
- ORG_ROLE: 事前定義されたスキーマの場合、これは organizations.role フィールドの値（director、actor、player、team、league、editor、author、character、contributor、creator、editor、funder、producer、provider、publisher、sponsor、translator、music-by、channel、custom-role）です。
- NAME_STRING: 指定されたロールを持つ 1 つ以上の組織の名前。ステップ 4 のような curl コマンドでは、二重引用符をバックスラッシュ文字でエスケープする必要があります。
この例では、検索を制作会社が Walt Disney Studios の映画に制限しています。
```
filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"
```

評価、人物、組織のフィルタ（カスタムスキーマ）

カスタムスキーマを使用する場合は、Google の事前定義スキーマセクションと、このセクションの例を確認してください。カスタムスキーマで評価、人物、組織のフィルタを機能させるには、プロパティマッピングを正しく設定する必要があります。プロパティマッピングについては、カスタムスキーマをご覧ください。

フィルタ	マッピングするプロパティ
rating	`media_aggregated_rating` `media_aggregated_rating_score` `media_aggregated_rating_source`
人物	`media_person` `media_person_name` `media_person_role`
組織	`media_organization` `media_organization_name` `media_organization_role`

カスタムスキーマの評価フィルタの例

このフィルタは、Rotten Tomatoes で 5 つ星の評価が付いている映画を検索します。

"filter": "rating(rotten_tomatoes, custom_rating.star_score) = 5"

rotten_tomatoes は、media_aggregated_rating_source にマッピングされたフィールドの値です。custom_rating.star_score は、media_aggregated_rating.media_aggregated_rating_score キープロパティにマッピングされるフィールドです。

カスタムスキーマの組織フィルタの例

このフィルタは、音楽がロンドン交響楽団またはハリウッドスタジオシンフォニーによる映画を検索します。

"filter: org(music-by, company.id): ANY (\"London Symphony Orchestra\", \"Hollywood Studio Symphony\" )

company.id は、media_organization_name プロパティにマッピングされたフィールドの名前です。また、music-by は media_organization_role にマッピングされる会社レコードフィールドの値です。

メディア検索をフィルタする

始める前に

ドキュメントの例

フィルタ式の構文

メディア検索をフィルタする

利用可能なドキュメントのフィルタ

評価、人物、組織のフィルタ

評価、人物、組織のフィルタ（Google 事前定義スキーマ）

評価、人物、組織のフィルタ（カスタム スキーマ）

評価、人物、組織のフィルタ（カスタムスキーマ）