סינון חיפוש המדיה

אם יש לכם אפליקציה לחיפוש מדיה, אתם יכולים להשתמש במטא-נתונים כדי לסנן את שאילתות החיפוש. בדף הזה מוסבר איך להשתמש בשדות של מטא-נתונים כדי להגביל את החיפוש לקבוצה מסוימת של מסמכים.

לפני שמתחילים

חשוב לוודא שיצרתם אפליקציית מדיה ומאגר נתונים, והזנתם נתונים. מידע נוסף זמין במאמרים בנושא יצירת מאגר נתוני מדיה ויצירת אפליקציית מדיה.

דוגמאות למסמכים

כדאי לעיין בדוגמאות הבאות של מסמכי מדיה. תוכלו לחזור אליהם בזמן הקריאה של הדף הזה.

{"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\"}"}

תחביר של ביטוי סינון

חשוב להבין את תחביר הביטוי של המסנן שבו תשתמשו כדי להגדיר את מסנן החיפוש. תחביר ביטוי המסנן יכול להיות מסוכם על ידי הטופס המורחב של Backus–Naur הבא:

  # 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 exactly matches any of the literals.
    | text_field, ":", "ANY", "(", literal, { ",", literal }, ")"
    # A simple expression applying to any indexable field.
    # Preview: Function "EXISTS" returns true if the field is not NULL, empty, or containing the default value.
    | text_field, ":", "EXISTS"
    | numerical_field, ":", "EXISTS"
    # 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.

כדי לסנן את החיפוש במדיה באמצעות מטא-נתונים:

  1. מאתרים את מזהה האפליקציה. אם כבר יש לכם מזהה אפליקציה, דלגו לשלב הבא.

    1. נכנסים לדף AI Applications במסוף Google Cloud .

      מעבר אל 'אפליקציות'

    2. בדף אפליקציות, מאתרים את שם האפליקציה ומעתיקים את המזהה שלה מהעמודה מזהה.

  2. קובעים את השדה או השדות במסמך שרוצים לסנן. לדוגמה, כדי לסנן את המסמכים שמופיעים בקטע לפני שמתחילים, אפשר להשתמש בשדה categories.

    אפשר להשתמש בשדות שניתן ליצור להם אינדקס רק בביטויי מסננים. כדי לבדוק אם אפשר ליצור אינדקס לשדה מסוים:

    1. במסוף Google Cloud , עוברים לדף AI Applications ובתפריט הניווט לוחצים על Data Stores.

      מעבר לדף 'מאגרי נתונים'

    2. לוחצים על השם של מאגר הנתונים.

    3. בעמודה שם, לוחצים על מאגר הנתונים.

    4. לוחצים על הכרטיסייה סכימה כדי לראות את הסכימה של מאגר הנתונים. אם הערך של Indexable בשדה הוא:

      • בוחרים באפשרות , ואז השדה מוכן לסינון בחיפוש. מדלגים על שלב 3.

      • לא נבחר , ואז פועלים לפי שלב 3 כדי להפעיל את השדה להוספה לאינדקס.

      • לא זמין , אז אי אפשר להוסיף את השדה לאינדקס.

  3. כדי להגדיר שדה, כמו שדה categories, כמסנן, מבצעים את הפעולות הבאות:

    1. נכנסים לדף AI Applications במסוף Google Cloud , ובתפריט הניווט לוחצים על Apps.

      כניסה לדף האפליקציות

    2. לוחצים על אפליקציית החיפוש של המדיה.

    3. בתפריט הניווט, לוחצים על נתונים.

    4. לוחצים על הכרטיסייה סכימה. בכרטיסייה הזו מוצגות ההגדרות הנוכחיות של השדה.

    5. לוחצים על Edit.

    6. אם היא לא מסומנת, מסמנים את התיבה ניתן לאינדוקס בשורה categories ולוחצים על Save.

    7. צריך להמתין שש שעות כדי לאפשר להפצה של עריכת הסכימה. אחרי שש שעות, אפשר להמשיך לשלב הבא.

  4. מקבלים תוצאות חיפוש.

    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: מזהה הפרויקט.
    • ‫APP_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,‏ person ו-organization הם:

  • סינון לפי דירוגים: סינון לפי דירוגים ממקור נתון.

     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.5 כוכבים. הערך שבתוך הסוגריים הוא הערך של סיווג IMDB:

    "filter": "rating(imdb, aggregate_ratings.rating_score) > 2.5"

  • סינון אנשים: סינון לפי שמות של אנשים בתפקיד מסוים.

    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: השם או השמות של האנשים עם התפקיד שצוין. בפקודות curl, כמו בשלב 4, צריך להוסיף תו בריחה (escape) של לוכסן הפוך למירכאות הכפולות.

    דוגמה: המסנן הזה מגביל את החיפוש לסרטים שבהם אחד השחקנים הוא בראד פיט או קייט וינסלט.

    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: שם אחד או יותר של ארגונים עם התפקיד שצוין. בפקודות curl, כמו בשלב 4, צריך להשתמש בתו בריחה (escape) כדי לסמן את המירכאות הכפולות באמצעות התו של הלוכסן ההפוך.

    בדוגמה הזו, החיפוש מוגבל לסרטים שארגון ההפקה שלהם הוא Walt Disney Studios:

    filter: "org(producer, organizations.name): ANY(\"Walt Disney Studios\")"

מסננים לדירוגים, לאנשים ולארגונים (סכימה מותאמת אישית)

אם אתם משתמשים בסכימה בהתאמה אישית, כדאי לעיין בקטע סכימה מוגדרת מראש של Google ואז בדוגמאות שבקטע הזה. כדי שהמסננים rating,‏ person ו-organization יפעלו בסכימה מותאמת אישית, צריך להגדיר את מיפוי הנכסים בצורה נכונה. מידע על מיפוי מאפיינים זמין במאמר בנושא סכימה מותאמת אישית.

מסנן מאפיינים למיפוי
דירוג 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

דוגמה למסנן דירוגים לסכימה בהתאמה אישית

המסנן הזה מחפש סרטים שקיבלו דירוג של 5 כוכבים מ-Rotten Tomatoes:

"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.