שאילתות על נתוני protobuf

במסמך הזה מפורטות דוגמאות למבני שאילתות נפוצים לקריאה ולשליחת שאילתות של נתונים בפורמט מאגר אחסון לפרוטוקולים (protobuf) שמאוחסנים ב-Bigtable.

לפני שקוראים את הדף הזה, כדאי להכיר את המושגים הבאים:

• יצירה וניהול של סכימות protobuf
• GoogleSQL for Bigtable

נתונים לדוגמה

בדוגמאות הבאות נעשה שימוש בMusic טבלה שמאחסנת מידע על אלבומים ואומנים. הנתונים מאוחסנים במשפחת עמודות בשם album_details, עם מסווג עמודות album. המסווג של העמודה מכיל הודעות protobuf.

סכימת ה-protobuf מוגדרת בקובצי ה-proto הבאים:

• artist.proto:

  syntax = "proto3";
  
  package package_name;
  
  message Artist {
   string name = 1;
  }
  

• album.proto:

  syntax = "proto3";
  
  package package_name;
  
  import "artist.proto";
  
  message Album {
   string title = 1;
   Artist artist = 2;
   int32 release_year = 3;
  }
  

כתוצאה מכך, Bigtable יוצר חבילת סכימה לטבלה הזו שמכילה את קבוצת תיאורי הקבצים של ה-protobuf להגדרות ה-protobuf האלה:

file {
  name: "artist.proto"
  package: "package_name"
  message_type {
    name: "Artist"
    field {
      name: "name"
      number: 1
      label: LABEL_OPTIONAL
      type: TYPE_STRING
      json_name: "name"
    }
  }
  syntax: "proto3"
}
file {
  name: "album.proto"
  package: "package_name"
  dependency: "artist.proto"
  message_type {
    name: "Album"
    field {
      name: "title"
      number: 1
      label: LABEL_OPTIONAL
      type: TYPE_STRING
      json_name: "title"
    }
    field {
      name: "artist"
      number: 2
      label: LABEL_OPTIONAL
      type: TYPE_MESSAGE
      type_name: ".package_name.Artist"
      json_name: "artist"
    }
    field {
      name: "release_year"
      number: 3
      label: LABEL_OPTIONAL
      type: TYPE_INT32
      json_name: "releaseYear"
    }
  }
  syntax: "proto3"
}

שאילתות לדוגמה

בדוגמאות הבאות מוסבר איך להריץ שאילתות על נתוני protobuf באמצעות GoogleSQL עבור Bigtable וטבלאות חיצוניות של BigQuery.

העברה של עמודה להודעת protobuf

אפשר להשתמש באופרטור CAST כדי לפרש ערך BYTES כהודעת protobuf. כדי לעשות זאת, צריך לציין את השם המלא של הודעת ה-protobuf בפורמט הבא: SCHEMA_BUNDLE_ID.FULLY_QUALIFIED_MESSAGE_NAME.

מחליפים את מה שכתוב בשדות הבאים:

• ‫SCHEMA_BUNDLE_ID: המזהה הייחודי שהקציתם לחבילת הסכימה כשנוצרה.
• ‫FULLY_QUALIFIED_MESSAGE_NAME: השם המלא של ההודעה, שחייב לכלול את שם החבילה שמוגדר בקובץ ה-proto, לדוגמה package_name.message_name.

בדוגמה הבאה של שאילתה, העמודה album מומרת להודעת protobuf‏ Album. ההודעה הזו מוגדרת בחבילה package_name והיא חלק מחבילת סכימות בשם bundle_name:

SELECT
  CAST(album_details['album'] AS bundle_name.package_name.Album).title
FROM
  Music;

גישה לשדות מקוננים

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

השאילתה הבאה מאחזרת את שם האומן מההודעה Artist שמוטמעת בהודעה Album:

SELECT
  CAST(album_details['album'] AS bundle_name.package_name.Album).artist.name
FROM
  Music;

סינון לפי שדות protobuf

אפשר להשתמש בפסקה WHERE כדי לסנן שורות על סמך הערכים של שדות בהודעת protobuf.

השאילתה הבאה בוחרת את כל האלבומים של האומן Dana A.:

SELECT
  *
FROM
  Music
WHERE
  CAST(album_details['album'] AS bundle_name.package_name.Album).artist.name = 'Dana A.';

שדות מצטברים של protobuf

אפשר להשתמש בפונקציות מצטברות כמו SUM,‏ AVG,‏ MIN,‏ MAX ו-COUNT בשדות מספריים בהודעות protobuf.

השאילתה הבאה מחשבת את שנת היציאה הממוצעת של כל האלבומים בטבלה:

SELECT
  AVG(CAST(album_details['album'] AS bundle_name.package_name.Album).release_year)
FROM
  Music;

סידור לפי שדות protobuf

אפשר להשתמש בפסוקית ORDER BY כדי למיין את קבוצת התוצאות על סמך שדה בהודעת ה-protobuf.

השאילתה הבאה מאחזרת את כל האלבומים וממיינת אותם לפי שנת היציאה שלהם בסדר יורד:

SELECT
  *
FROM
  Music
ORDER BY
  CAST(album_details['album'] AS bundle_name.package_name.Album).release_year DESC;

שימוש בתצוגות

אפשר ליצור תצוגות מהותיות מתמשכות או תצוגות לוגיות שקוראות נתוני protobuf.

הפקודה הבאה יוצרת תצוגה לוגית שמחלצת את כל השדות בהודעה Album:

QUERY="SELECT _key, CAST(album_details['album'] AS bundle_name.package_name.Album).* FROM Music"

gcloud bigtable logical-views create LOGICAL_VIEW_ID \
    --instance=INSTANCE_ID \
    --query=$QUERY

מחליפים את מה שכתוב בשדות הבאים:

• ‫LOGICAL_VIEW_ID: המזהה של התצוגה הלוגית שמפנה לחבילת הסכימה.
• ‫INSTANCE_ID: המזהה של המופע שבו אתם משתמשים כדי ליצור את חבילת הסכימה.

כשמבצעים הפניה לחבילת סכימות בתצוגה, צריך למחוק את התצוגה לפני שמוחקים את החבילה. בנוסף, אל תעדכנו את חבילת הסכימה לערכת תיאור קובץ protobuf חדשה שלא תואמת לאחור לערכה הקיימת.

שימוש בטבלאות חיצוניות של BigQuery

אפשר ליצור שאילתה לגבי נתוני protobuf שמאוחסנים ב-Bigtable מ-BigQuery על ידי יצירת טבלה חיצונית. כשיוצרים את הטבלה החיצונית, מציינים את סוג העמודה כ-JSON, את הקידוד שלה כ-PROTO_BINARY ומשייכים אותה לחבילת סכימות. במהלך התהליך הזה, בייטים של הודעת protobuf מומרים לנתוני JSON מקבילים, וכך אפשר לשלוח שאילתות ישירות לשדות שלה.

הנה דוגמה לקובץ הגדרת טבלה ליצירת טבלה חיצונית ב-BigQuery מעל הטבלה Music:

{
    "sourceFormat": "BIGTABLE",
    "sourceUris": [
        "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID/tables/Music"
    ],
    "bigtableOptions": {
        "columnFamilies" : [
            {
                "familyId": "album_details",
                "columns": [
                    {
                        "qualifierString": "album",
                        "type": "JSON",
                        "encoding": "PROTO_BINARY",
                        "protoConfig": {
                            "schemaBundleId": "bundle_name",
                            "protoMessageName": "package_name.Album"
                        }
                    }
                ]
            }
        ]
    }
}

אחרי שיוצרים את הטבלה החיצונית, אפשר להריץ שאילתות על נתוני ה-protobuf כעמוד JSON ב-BigQuery.

השאילתה הבאה מאחזרת את שם כל האלבומים שיצאו בשנת 2022 מהטבלה החיצונית ב-BigQuery:

SELECT JSON_VALUE(value, '$.title') AS title
FROM
`PROJECT_ID.DATASET.TABLE_NAME` AS t,
UNNEST(t.album_details.album.cell)
WHERE INT64(JSON_EXTRACT(value, '$.releaseYear')) = 2022;

המאמרים הבאים

• מידע נוסף על שיטות מומלצות לעיצוב סכימות של protobuf