יצירה ורישום של סכימה

סכימה של Google Cloud Search היא מבנה JSON שמגדיר אובייקטים, מאפיינים ואפשרויות לאינדוקס ולשאילתות של נתונים. מחבר התוכן שלכם משתמש בסכימה הרשומה כדי לבנות את הנתונים במאגר ולבצע עליהם אינדוקס.

כדי ליצור סכימה, צריך לספק אובייקט סכימה בפורמט JSON ל-API. לפני שמבצעים אינדוקס של נתונים, צריך לרשום סכימה לכל מאגר.

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

יצירה של סכימה

כדי ליצור סכימה של Cloud Search:

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

זיהוי התנהגות משתמשים צפויה

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

כדי להתאים את הסכימה להתנהגות המשתמשים:

הערכה של שאילתות מגוונות ממשתמשים שונים.
מזהים מערכי נתונים לוגיים, או אובייקטים, כמו "סרט".
זיהוי מאפיינים (תכונות) כמו שם או תאריך פרסום.
צריך לציין ערכים תקינים למאפיינים, כמו 'שודדי התיבה'.
לקבוע את הצרכים של המיון והדירוג, כמו סדר כרונולוגי או דירוג של קהל.
זיהוי מאפייני הקשר, כמו תפקיד, כדי לשפר את ההצעות להשלמה אוטומטית.
מפרטים את האובייקטים, המאפיינים וערכי הדוגמה. אפשר להשתמש ברשימה הזו כדי להגדיר אפשרויות לאופרטורים.

אתחול מקור הנתונים

מקור נתונים מייצג נתונים ממאגרים שעברו אינדוקס ואוחסנו ב-Google Cloud. אפשר לעיין במאמר בנושא ניהול מקורות נתונים של צד שלישי. כשמשתמש לוחץ על תוצאה, Cloud Search מפנה אותו לפריט באמצעות כתובת ה-URL מבקשת ההוספה לאינדקס.

הגדרת האובייקטים

אובייקט הוא היחידה הבסיסית של סכימה. מבנים לוגיים כמו 'סרט' או 'אדם' הם אובייקטים. לכל אובייקט יש מאפיינים כמו שם, משך או כותרת.

ציור של קשרים בין ישויות בסכימה — **איור 1.** סכימה לדוגמה עם שני אובייקטים ואובייקט משנה.

סכימה היא רשימה של הגדרות אובייקטים בתג objectDefinitions.

{
  "objectDefinitions": [
    { "name": "movie" },
    { "name": "person" }
  ]
}

צריך להשתמש בשמות ייחודיים לכל אובייקט, כמו movie. שירות הסכימה משתמש בשמות האלה כמפתחות. ObjectDefinition

הגדרת מאפייני אובייקט

מגדירים מאפיינים כמו שם ותאריך פרסום בקטע propertyDefinitions. משתמשים בתווית options כדי לציין freshnessOptions (דירוג) ובתווית displayOptions כדי לציין (תוויות בממשק המשתמש).

{
  "objectDefinitions": [{
    "name": "movie",
    "propertyDefinitions": [
      {
        "name": "movieTitle",
        "isReturnable": true,
        "textPropertyOptions": {
          "retrievalImportance": { "importance": "HIGHEST" },
          "operatorOptions": { "operatorName": "title" }
        },
        "displayOptions": { "displayLabel": "Title" }
      },
      {
        "name": "releaseDate",
        "isReturnable": true,
        "isSortable": true,
        "datePropertyOptions": {
          "operatorOptions": {
            "operatorName": "released",
            "lessThanOperatorName": "releasedbefore",
            "greaterThanOperatorName": "releasedafter"
          }
        }
      }
    ]
  }]
}

‫PropertyDefinition כולל:

מחרוזת name.
אפשרויות שלא תלויות בסוג (למשל, isReturnable).
סוג ואפשרויות ספציפיות לסוג (לדוגמה, textPropertyOptions).
operatorOptions לאופרטורים של חיפוש.
displayOptions לתוויות בממשק המשתמש.

אפשר להשתמש בשמות מאפיינים שוב באובייקטים שונים. לדוגמה, movieTitle יכול להופיע גם באובייקט movie וגם בפילמוגרפיה של אובייקט person.

הוספת אפשרויות שלא תלויות בסוג

‫PropertyDefinition כולל אפשרויות בוליאניות להגדרת פונקציונליות החיפוש של נכס, ללא קשר לסוג שלו. ברירת המחדל של האפשרויות האלה היא false, וצריך להגדיר אותן ל-true כדי להשתמש בהן.

‫isReturnable: הערך שמוגדר הוא true אם נתוני הנכס צריכים להיות מוחזרים בתוצאות החיפוש באמצעות Query API. אפשר להשתמש במאפיינים שאי אפשר להחזיר כדי לחפש או לדרג מוצרים בלי שהם יופיעו בתוצאות.
‫isRepeatable: מגדירים את הערך true אם למאפיין יכולים להיות כמה ערכים. לדוגמה, לסרט יש תאריך יציאה אחד אבל כמה שחקנים.
‫isSortable: הערך שמוגדר הוא true אם אפשר להשתמש במאפיין למיון. הערך לא יכול להיות true אם הערך של isRepeatable הוא true או אם המאפיין נמצא באובייקט משנה שניתן לחזרה.
‫isFacetable: מוגדר כ-true אם אפשר להשתמש במאפיין ליצירת היבטים (מאפיינים שמשמשים לחידוד תוצאות החיפוש).
- הערך של isReturnable חייב להיות true.
- התכונה נתמכת רק בנכסי enum, בוליאניים וטקסט.
‫isWildcardSearchable: אם מגדירים את הערך true, המשתמשים יכולים לבצע חיפושים עם תו כללי בנכס הזה. האפשרות הזו זמינה רק במאפייני טקסט, וההתנהגות שלה תלויה בהגדרה של exactMatchWithOperator:
- אם exactMatchWithOperator הוא true: ערך הטקסט נחשב לטוקן יחיד. שאילתה כמו science-* תואמת לערך science-fiction.
- אם exactMatchWithOperator הוא false: ערך הטקסט עובר טוקניזציה. שאילתה כמו sci* או fi* תואמת ל-science-fiction, אבל science-* לא.

הגדרת סוג

מגדירים את סוג הנתונים על ידי הגדרת אובייקט האפשרויות המתאים של המאפיין (למשל, textPropertyOptions). אם אתם יודעים את כל הערכים האפשריים, השתמשו בסוגי נתונים מנומריים (enumPropertyOptions). לנכס יכול להיות רק סוג נתונים אחד.

הגדרת אפשרויות אופרטור

operatorOptions תארו איך מאפיין מתפקד כאופרטור חיפוש.

לכל operatorOptions צריך להיות operatorName (למשל, title). זה הפרמטר שהמשתמשים מקלידים בשאילתות (למשל, title:titanic). כדאי להשתמש בשמות אינטואיטיביים ולהציג אותם למשתמשים.

אפשר לשתף operatorName בין נכסים מאותו סוג. שאילתות שמשתמשות בשם הזה מאחזרות תוצאות מכל הנכסים התואמים.

מאפיינים שניתן למיין יכולים לכלול את lessThanOperatorName ואת greaterThanOperatorName בשאילתות השוואה. במאפייני טקסט אפשר להשתמש ב-exactMatchWithOperator כדי להתייחס לערך כולו כאל טוקן יחיד.

הוספת אפשרויות תצוגה

המקטע האופציונלי displayOptions מכיל displayLabel. זוהי תווית ידידותית למשתמש שמוצגת בתוצאות החיפוש.

הוספת אופרטורים לסינון הצעות

משתמשים ב-suggestionFilteringOperators[] כדי להגדיר מאפיין שמסנן הצעות להשלמה אוטומטית (למשל, סינון של הצעות לסרטים לפי הז'אנר המועדף על המשתמש). אפשר להגדיר רק מסנן אחד של הצעות.

רישום הסכימה

רושמים את הסכימה בשירות הסכימות באמצעות המזהה של מקור הנתונים. שליחת בקשת UpdateSchema:

PUT https://cloudsearch.googleapis.com/v1/indexing/{name=datasources/*}/schema

אתם יכולים להשתמש ב-validateOnly: true כדי לבדוק את הסכימה בלי לרשום אותה.

יצירת אינדקס של הנתונים

אחרי ההרשמה, מאכלסים את מקור הנתונים באמצעות קריאות ל-Index, בדרך כלל באמצעות מחבר.

דוגמה לבקשה להוספה לאינדקס:

{
  "name": "datasource/<data_source_id>/items/titanic",
  "metadata": {
    "title": "Titanic",
    "objectType": "movie"
  },
  "structuredData": {
    "object": {
      "properties": [{
        "name": "movieTitle",
        "textValues": { "values": ["Titanic"] }
      }]
    }
  },
  "itemType": "CONTENT_ITEM"
}

בדיקת הסכימה

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

שאילתה כללית: חיפוש מחרוזת (למשל, ‫titanic) כדי לראות את כל הפריטים התואמים.
שאילתת אופרטור: משתמשים באופרטור (למשל, actor:Zane) כדי להגביל את התוצאות.

התאמה של הסכימה

לעקוב אחרי משוב המשתמשים ולשנות את הסכימה בהתאם. אפשר להוסיף לאינדקס שדות חדשים או לשנות את השם של האופרטורים כדי שיהיו אינטואיטיביים יותר.

יצירת אינדקס מחדש אחרי שינוי סכימה

לא צריך ליצור אינדקס מחדש כדי שהשינויים הבאים ייכנסו לתוקף:

שמות האופרטורים.
מגבלות מספריות.
דירוג מסודר.
אפשרויות רענון או תצוגה.

צריך ליצור אינדקס מחדש בשביל:

הוספה או הסרה של נכסים או אובייקטים.
שינוי של isReturnable, isFacetable או isSortable ל-true.
סימון נכס isSuggestable.

שינויים אסורים בנכס

אסור לבצע שינויים שפוגעים באינדקס או גורמים לתוצאות לא עקביות, כולל:

שם או סוג הנתונים של הנכס.
ההגדרות של exactMatchWithOperator או retrievalImportance.

ביצוע שינוי מורכב בסכימה

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

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

‫Cloud Search מתעד פריטים שנמחקו למשך 30 יום כדי למנוע בעיות בשימוש חוזר.

מגבלות גודל

עד 10 אובייקטים ברמה העליונה.
העומק המקסימלי הוא 10 רמות.
עד 1,000 שדות לכל אובייקט (כולל שדות מקוננים).