ניהול סכימות של מפתחות שורות

תצוגה מקדימה

השימוש במוצר או בתכונה כפוף לתנאי השימוש במוצרים בגרסת טרום-GA, בחלק "תנאים כלליים לשירות" של התנאים הספציפיים לשירות. השימוש בתכונות ובמוצרים בגרסת טרום-GA הוא "כפי שהם" (As is), ויכול להיות שהתמיכה בהם תהיה מוגבלת. מידע נוסף זמין בקטע תיאור שלבי ההשקה.

מפתחות שורות מובְנים מאפשרים לכם לגשת לנתוני Bigtable באמצעות מפתחות מרובי חלקים, בדומה למפתחות מורכבים במסדי נתונים רלציוניים. הגדרה של מפתחות שורות מובנים בטבלה מאפשרת גישה לחלקים ספציפיים של מפתחות השורות באמצעות GoogleSQL לשאילתות Bigtable.

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

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

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

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

`phone#india#pke5preri2eru#8923695`

בסכימת מפתח השורה, יכול להיות שתזהו את # כתו המפריד ותגדירו את פלחי מפתח השורה כך:

פלח של מפתח שורה	סוג	קידוד
סוג המכשיר (טלפון)	מחרוזת	UTF-8
מדינה (הודו)	מחרוזת	UTF-8
מזהה יצרן (pke5preri2eru)	מחרוזת	UTF-8
מספר סידורי (8923695)	BYTES	ערכים גולמיים

ההרשאות הנדרשות

ההרשאות שאתם צריכים תלויות בפעולה שאתם רוצים לבצע.

כדי לקבל את ההרשאות האלה, צריך לבקש מהאדמין להקצות לכם תפקיד בטבלה שכולל את ההרשאות:

• הצגת סכימת מפתח שורה: bigtable.tables.get
• יוצרים סכימה של מפתח שורה: bigtable.tables.update
• מחיקת סכימת מפתח שורה: bigtable.tables.update

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

יצירה של סכימת מפתח שורה

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

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

gcloud

כדי להגדיר סכימה של מפתח שורה באמצעות ה-CLI של gcloud, משתמשים בפקודה gcloud beta bigtable tables update עם קובץ YAML או JSON שמגדיר את הסכימה.

gcloud beta bigtable tables update TABLE_ID \
  --instance=INSTANCE_ID \
  --row-key-schema-definition-file=ROW_KEY_SCHEMA_DEFINITION_FILE \
  --row-key-schema-pre-encoded-bytes

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

• ‫TABLE_ID: המזהה הייחודי של הטבלה שרוצים לעדכן
• ‫INSTANCE_ID: המזהה של המופע שבו נמצא הטבלה
• ‫ROW_KEY_SCHEMA_DEFINITION_FILE: הנתיב לקובץ YAML או JSON שמגדיר את הסכימה של מפתח השורה. דוגמאות לאופן שבו הקבצים האלה צריכים להיראות מופיעות במאמר דוגמאות לקובצי סכימה.

כברירת מחדל, קידוד Base64 מוחל על כל השדות הבינאריים בקובץ YAML או JSON, כמו encoding.delimitedBytes.delimiter עבור התו שמפריד בין מפתחות השורות. הדגל --row-key-schema-pre-encoded-bytes מציין ל-Bigtable ששדות בינאריים מקודדים בקובץ ואין לקודד אותם שוב.

המשך

משתמשים בפונקציה UpdateTableWithRowKeySchema כדי ליצור סכימת מפתח שורה לטבלה.

func (ac *AdminClient) UpdateTableWithRowKeySchema(ctx context.Context, tableID
string, rowKeySchema StructType) error

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

rks := StructType{
Fields: []StructField{
    {FieldName: "key1", FieldType: Int64Type{Encoding: Int64OrderedCodeBytesEncoding{}}},
    {FieldName: "key2", FieldType: StringType{Encoding: StringUtf8BytesEncoding{}}},
  },
  Encoding: StructDelimitedBytesEncoding{Delimiter: []byte{'#'}}}

err := c.UpdateTableWithRowKeySchema(context.Background(), "my-table", rks)

מחיקה של סכימת מפתח שורה

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

gcloud

כדי למחוק את סכימת מפתח השורה של טבלה, משתמשים בפקודה gcloud beta bigtable tables update עם הדגל --clear-row-key-schema.

  gcloud beta bigtable tables update TABLE_NAME \
    --instance=INSTANCE_ID \
    --clear-row-key-schema

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

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

המשך

השתמש בפונקציה UpdateTableRemoveRowKeySchema כדי לנקות את סכימת מפתח השורה עבור טבלה:

func (ac *AdminClient) UpdateTableRemoveRowKeySchema(ctx context.Context,
tableID string) error

שינוי סכימת מפתח שורה

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

הצגת סכימת מפתח שורה

gcloud

כדי לראות את הסכימה של מפתח השורה, משתמשים בפקודה gcloud beta bigtable tables describe:

  gcloud bigtable tables describe TABLE_NAME \
    --instance=INSTANCE_ID

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

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

התגובה במסוף אמורה להיראות כך: אם לטבלה אין סכימת מפתח שורה, התגובה לא כוללת את הקטע rowKeySchema.

columnFamilies:
  cf: {}
createTime: '2025-05-28T17:25:39.433058Z'
granularity: MILLIS
name: projects/<project>/instances/<instance>/tables/<table>
rowKeySchema:
  encoding:
    delimitedBytes:
      delimiter: Iw==
  fields:
  - fieldName: <field_name_1>
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: <field_name_2>
    type:
      intType:
        encoding:
          bigEndianBytes: {}
  - fieldName: <field_name_3>
    type:
      timestampType:
        encoding:
          unixMicrosInt64: {
              encoding: {
                  orderedCodeBytes: {}
              }
          }
updateTime: '2025-05-28T17:25:39.433058Z'

המשך

השדה RowKeySchema זמין כחלק מהאובייקט TableInfo, ואפשר לאחזר אותו באמצעות השיטה .TableInfo().

type TableInfo struct {
  ...
  RowKeySchema          *StructType
}

func (ac *AdminClient) TableInfo(ctx context.Context, table string) (*TableInfo, error)

שאילתות של מפתחות שורות מובנים

כדי לשלוח שאילתות לעמודות במפתחות שורות מובְנים, צריך להשתמש ב-SQL. השיטה ReadRows של Bigtable Data API מתעלמת מסכימת מפתח שורה כשהיא קוראת מטבלה.

דוגמאות לשאילתות שבוחרות מפתחות שורות מובנים מופיעות במאמר שאילתות של מפתחות שורות מובנים.

רשימה של ספריות לקוח של Bigtable שתומכות בשאילתות SQL, כולל דוגמאות קוד, מופיעה במאמר שימוש ב-SQL עם ספריית לקוח של Bigtable.

קבצים של סכימות לדוגמה

כשיוצרים סכימה של מפתח שורה באמצעות ה-CLI של gcloud, אפשר להגדיר את מפתחות השורה המובנים באמצעות קובץ YAML או קובץ JSON.

YAML

fields:
  - fieldName: "user_id"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "purchase_date"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
  - fieldName: "order_number"
    type:
      stringType:
        encoding:
          utf8Bytes: {}
encoding:
  delimitedBytes:
    delimiter: "Iw=="

JSON

{
  "fields": [
    {
      "fieldName": "user_id",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "purchase_date",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    },
    {
      "fieldName": "order_number",
      "type": {
        "stringType": {
          "encoding": {
            "utf8Bytes": {}
          }
        }
      }
    }
  ],
  "encoding": {
    "delimitedBytes": {
      "delimiter": "Iw=="
    }
  }
}

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

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