טעינת נתונים מייצוא מ-Datastore

‫BigQuery תומך בטעינת נתונים מייצוא של Datastore שנוצר באמצעות שירות הייבוא והייצוא המנוהל של Datastore. אתם יכולים להשתמש בשירות המנוהל לייבוא ולייצוא כדי לייצא ישויות Datastore לקטגוריה של Cloud Storage. אחר כך תוכלו לטעון את קובץ הייצוא ל-BigQuery כטבלה.

מידע על יצירת קובץ ייצוא של Datastore זמין במאמר ייצוא וייבוא של ישויות במסמכי התיעוד של Datastore. מידע על תזמון ייצוא זמין במאמר תזמון ייצוא.

אפשר לקבוע אילו מאפיינים ייטענו ב-BigQuery על ידי הגדרת המאפיין projectionFields ב-API או באמצעות הדגל --projection_fields בכלי שורת הפקודה של BigQuery.

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

כשמעלים נתונים מ-Cloud Storage לטבלה ב-BigQuery, מערך הנתונים שמכיל את הטבלה צריך להיות באותו אזור או באותו אזור רב-אזורי כמו קטגוריה של Cloud Storage.

מגבלות

כשאתם טוענים נתונים ל-BigQuery מייצוא של Datastore, חשוב לשים לב להגבלות הבאות:

  • אי אפשר להשתמש בתו כללי ב-URI של Cloud Storage כשמציינים קובץ ייצוא של Datastore.
  • כשמטעינים נתונים מייצוא של Datastore, אפשר לציין רק URI אחד של Cloud Storage.
  • אי אפשר לצרף נתונים שיוצאו מ-Datastore לטבלה קיימת עם סכימה מוגדרת.
  • כדי שייצוא של Datastore ייטען בצורה תקינה, יש לוודא שלישויות בנתוני הייצוא יש סכימה עקבית עם פחות מ-10,000 שמות מאפיינים ייחודיים.
  • אי אפשר לטעון ל-BigQuery נתונים שמיוצאים בלי לציין מסנן ישויות. בקשת הייצוא צריכה לכלול לפחות שם סוג אחד במסנן הישות.
  • הגודל המקסימלי של שדה בייצוא של Datastore הוא 64KB. כשמעלים ייצוא של Datastore, כל שדה שגודלו גדול מ-64KB נחתך.

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

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

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

כדי לטעון נתונים ל-BigQuery, אתם צריכים הרשאות IAM להרצת משימת טעינה ולטעינת נתונים לטבלאות ולמחיצות ב-BigQuery. אם אתם טוענים נתונים מ-Cloud Storage, אתם צריכים גם הרשאות IAM כדי לגשת לקטגוריה שמכילה את הנתונים.

הרשאות לטעינת נתונים ל-BigQuery

כדי לטעון נתונים לטבלה או למחיצה חדשה ב-BigQuery, או כדי לצרף נתונים לטבלה או למחיצה קיימת או להחליף אותם, אתם צריכים את הרשאות ה-IAM הבאות:

  • bigquery.tables.create
  • bigquery.tables.updateData
  • bigquery.tables.update
  • bigquery.jobs.create

כל אחד מהתפקידים הבאים שמוגדרים מראש ב-IAM כולל את ההרשאות שנדרשות לטעינת נתונים לטבלה או למחיצה ב-BigQuery:

  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • ‫roles/bigquery.admin (כולל את ההרשאה bigquery.jobs.create)
  • ‫bigquery.user (כולל את ההרשאה bigquery.jobs.create)
  • ‫bigquery.jobUser (כולל את ההרשאה bigquery.jobs.create)

בנוסף, אם יש לכם הרשאה של bigquery.datasets.create, אתם יכולים ליצור ולעדכן טבלאות באמצעות משימת טעינה במערכי הנתונים שאתם יוצרים.

במאמר תפקידים והרשאות מוגדרים מראש יש מידע נוסף על תפקידים והרשאות ב-IAM ב-BigQuery.

הרשאות לטעינת נתונים מ-Cloud Storage

כדי לקבל את ההרשאות שדרושות לטעינת נתונים מקטגוריה של Cloud Storage, צריך לבקש מהאדמין להקצות לכם את תפקיד ה-IAM אדמין לניהול אחסון (roles/storage.admin) בקטגוריה. להסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

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

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

כדי לטעון נתונים מקטגוריה של Cloud Storage, נדרשות ההרשאות הבאות:

  • storage.buckets.get
  • storage.objects.get
  • storage.objects.list (required if you are using a URI wildcard)

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

טעינת נתונים של שירות הייצוא של Datastore

כדי לטעון נתונים מקובץ מטא-נתונים של ייצוא מ-Datastore:

המסוף

  1. במסוף Google Cloud , עוברים לדף BigQuery.

    כניסה לדף BigQuery

  2. בחלונית הימנית, לוחצים על כלי הניתוחים.
  3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
  4. בקטע פרטי מערך הנתונים, לוחצים על יצירת טבלה.
  5. בחלונית Create table, מציינים את הפרטים הבאים:
    1. בקטע מקור, בוחרים באפשרות Google Cloud Storage ברשימה יצירת טבלה מ. לאחר מכן, מבצעים את הפעולות הבאות:
      1. בוחרים קובץ מתוך הקטגוריה של Cloud Storage או מזינים את ה-URI של Cloud Storage. אי אפשר לכלול כמה כתובות URI במסוף Google Cloud , אבל אפשר להשתמש בתווים כלליים לחיפוש. הקטגוריה של Cloud Storage צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה.
        ה-URI של קובץ הייצוא של Datastore צריך להסתיים ב-KIND_NAME.export_metadata או ב-export[NUM].export_metadata. לדוגמה, ב-default_namespace_kind_Book.export_metadata,‏ Book הוא שם הסוג ו-default_namespace_kind_Book הוא שם הקובץ שנוצר על ידי Datastore. בוחרים קובץ מקור כדי ליצור טבלה ב-BigQuery
      2. בקטע File format (פורמט קובץ), בוחרים באפשרות Cloud Datastore Backup (גיבוי של Cloud Datastore).
    2. בקטע יעד, מציינים את הפרטים הבאים:
      1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
      2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
      3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
    3. בקטע Schema (סכימה), לא צריך לבצע פעולה כלשהי. הסכמה נגזרת מייצוא של Datastore.
    4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות.
    5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
      • בקטע העדפות כתיבה, משאירים את האפשרות כתיבה אם ריק מסומנת. האפשרות הזו יוצרת טבלה חדשה וטוענת לתוכה את הנתונים.
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
        • מידע על האפשרויות הזמינות מופיע במאמר אפשרויות של Datastore.
    6. לוחצים על יצירת טבלה.

BQ

משתמשים בפקודה bq load עם source_format שמוגדר ל-DATASTORE_BACKUP. מציינים את הדגל --location ומגדירים את הערך למיקום.

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

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

  • ‫LOCATION: המיקום שלכם. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • ‫DATASET: מערך הנתונים שמכיל את הטבלה שאליה טוענים את הנתונים.
  • ‫TABLE: הטבלה שאליה טוענים את הנתונים. אם הטבלה לא קיימת, היא נוצרת.
  • ‫PATH_TO_SOURCE: ה-URI של Cloud Storage.

לדוגמה, הפקודה הבאה טוענת את קובץ הייצוא של Datastore‏ gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata לטבלה בשם book_data. ‫mybucket ו-mydataset נוצרו במיקום US שכולל מספר אזורים.

bq --location=US load \
--source_format=DATASTORE_BACKUP \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

כדי לטעון נתוני ייצוא של Datastore באמצעות API, צריך להגדיר את המאפיינים הבאים.

  1. יוצרים משימת טעינה שמפנה לנתוני המקור ב-Cloud Storage.

  2. מציינים את המיקום במאפיין location בקטע jobReference של משאב המשרה.

  3. כתובות ה-URI של המקור חייבות להיות מוגדרות במלואן, בפורמט gs://[BUCKET]/[OBJECT]. שם הקובץ (האובייקט) חייב להסתיים ב-[KIND_NAME].export_metadata. מותר להשתמש רק ב-URI אחד לייצוא של Datastore, ואי אפשר להשתמש בתו כללי.

  4. מגדירים את פורמט הנתונים באמצעות הנכס JobConfigurationLoad.sourceFormat עם הערך DATASTORE_BACKUP.

הוספה לטבלה או החלפה של טבלה בנתוני Datastore

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

אם מנסים לצרף נתונים שיוצאו ממאגר נתונים לטבלה קיימת, מוצגת השגיאה הבאה: Cannot append a datastore backup to a table that already has a schema. Try using the WRITE_TRUNCATE write disposition to replace the existing table.

כדי להחליף טבלה קיימת בנתונים שיוצאו מ-Datastore:

המסוף

  1. במסוף Google Cloud , עוברים לדף BigQuery.

    כניסה לדף BigQuery

  2. בחלונית הימנית, לוחצים על כלי הניתוחים.
  3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
  4. בקטע פרטי מערך הנתונים, לוחצים על יצירת טבלה.
  5. בחלונית Create table, מציינים את הפרטים הבאים:
    1. בקטע מקור, בוחרים באפשרות Google Cloud Storage ברשימה יצירת טבלה מ. לאחר מכן, מבצעים את הפעולות הבאות:
      1. בוחרים קובץ מתוך הקטגוריה של Cloud Storage או מזינים את ה-URI של Cloud Storage. אי אפשר לכלול כמה כתובות URI במסוף Google Cloud , אבל אפשר להשתמש בתווים כלליים לחיפוש. הקטגוריה של Cloud Storage צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה נתונים או להחליף אותה.
        ה-URI של קובץ הייצוא של Datastore צריך להסתיים ב-KIND_NAME.export_metadata או ב-export[NUM].export_metadata. לדוגמה, ב-default_namespace_kind_Book.export_metadata,‏ Book הוא שם הסוג ו-default_namespace_kind_Book הוא שם הקובץ שנוצר על ידי Datastore. בוחרים קובץ מקור כדי ליצור טבלה ב-BigQuery
      2. בקטע File format (פורמט קובץ), בוחרים באפשרות Cloud Datastore Backup (גיבוי של Cloud Datastore).
    2. בקטע יעד, מציינים את הפרטים הבאים:
      1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
      2. בשדה Table (טבלה), מזינים את השם של הטבלה שרוצים ליצור.
      3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
    3. בקטע Schema (סכימה), לא צריך לבצע פעולה כלשהי. הסכמה נגזרת מייצוא של Datastore.
    4. אופציונלי: מציינים הגדרות של מחיצה ושל אשכול. מידע נוסף זמין במאמרים בנושא יצירת טבלאות עם חלוקה למחיצות ויצירה ושימוש בטבלאות מקובצות. אי אפשר להמיר טבלה לטבלה מחולקת או לטבלה מסודרת באשכולות על ידי הוספה או החלפה שלה. Google Cloud מסוף Google Cloud לא תומך בהוספה לטבלאות מחולקות או מקובצות או בהחלפה שלהן בעבודת טעינה.
    5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
      • בקטע Write preference (העדפת כתיבה), בוחרים באפשרות Append to table (הוספה לטבלה) או Overwrite table (החלפת הטבלה).
      • אם רוצים להתעלם מערכים בשורה שלא מופיעים בסכימה של הטבלה, בוחרים באפשרות ערכים לא ידועים.
      • בקטע הצפנה, לוחצים על מפתח בניהול הלקוח כדי להשתמש במפתח של Cloud Key Management Service. אם לא משנים את ההגדרה Google-managed key,‏ BigQuery יצפין את הנתונים באחסון.
        • מידע על האפשרויות הזמינות מופיע במאמר אפשרויות של Datastore.
    6. לוחצים על יצירת טבלה.

BQ

משתמשים בפקודה bq load עם הדגל --replace והערך source_format מוגדר ל-DATASTORE_BACKUP. מציינים את הדגל --location ומגדירים את הערך למיקום.

bq --location=LOCATION load \
--source_format=FORMAT \
--replace \
DATASET.TABLE \
PATH_TO_SOURCE

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

  • ‫LOCATION: המיקום שלכם. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
  • FORMAT: DATASTORE_BACKUP.
  • ‫DATASET: מערך הנתונים שמכיל את הטבלה שאליה טוענים את הנתונים.
  • ‫TABLE: הטבלה שמוחלפת.
  • ‫PATH_TO_SOURCE: ה-URI של Cloud Storage.

לדוגמה, הפקודה הבאה טוענת את קובץ הייצוא של Datastore‏ gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata ומחליפה טבלה בשם book_data:

bq load --source_format=DATASTORE_BACKUP \
--replace \
mydataset.book_data \
gs://mybucket/20180228T1256/default_namespace/kind_Book/default_namespace_kind_Book.export_metadata

API

מגדירים את המאפיינים הבאים כדי לטעון נתונים מ-API.

  1. יוצרים משימת טעינה שמפנה לנתוני המקור ב-Cloud Storage.

  2. מציינים את המיקום במאפיין location בקטע jobReference של משאב המשרה.

  3. כתובות ה-URI של המקור חייבות להיות מוגדרות במלואן, בפורמט gs://[BUCKET]/[OBJECT]. שם הקובץ (האובייקט) חייב להסתיים ב-[KIND_NAME].export_metadata. מותר להשתמש רק ב-URI אחד לייצוא של Datastore, ואי אפשר להשתמש בתו כללי.

  4. מגדירים את פורמט הנתונים באמצעות הנכס JobConfigurationLoad.sourceFormat עם הערך DATASTORE_BACKUP.

  5. מגדירים את המאפיין JobConfigurationLoad.writeDisposition לערך WRITE_TRUNCATE כדי לציין את אופן הכתיבה.

אפשרויות של מאגר נתונים

כדי לשנות את האופן שבו BigQuery מנתח את נתוני הייצוא של Datastore, צריך לציין את האפשרות הבאה:

אפשרות מסוף דגל של כלי bq מאפיין BigQuery API תיאור
לא זמין --projection_fields projectionFields רשימה מופרדת בפסיקים שמציינת אילו מאפייני ישות לטעון ל-BigQuery מייצוא של Datastore. השמות של הנכסים הם תלויי-אותיות רישיות, והם חייבים להיות נכסים ברמה העליונה. אם לא מציינים נכסים, BigQuery טוען את כל הנכסים. אם מאפיין עם שם לא נמצא בייצוא של Datastore, תוחזר שגיאה לא תקינה בתוצאת העבודה. ערך ברירת המחדל הוא ''.

המרה של סוגי נתונים

‫BigQuery ממיר נתונים מכל ישות בקובצי ייצוא של Datastore לסוגי נתונים של BigQuery. בטבלה הבאה מתואר המעבר בין סוגי נתונים.

סוג הנתונים במאגר הנתונים סוג נתונים ב-BigQuery
מערך ARRAY
Blob BYTES
בוליאני BOOLEAN
תאריך ושעה TIMESTAMP
ישות מוטמעת RECORD
מספר בשיטת נקודה צפה FLOAT
נקודה גיאוגרפית

RECORD

[{"lat","DOUBLE"},
 {"long","DOUBLE"}]
מספר שלם INTEGER
מפתח RECORD
Null STRING
מחרוזת טקסט ‫STRING (הנתונים נחתכו ל-64KB)

מאפייני מפתח של Datastore

לכל ישות ב-Datastore יש מפתח ייחודי שמכיל מידע כמו מרחב השמות והנתיב. ‫BigQuery יוצר סוג נתונים RECORD למפתח, עם שדות מקוננים לכל פריט מידע, כפי שמתואר בטבלה הבאה.

מאפיין מרכזי תיאור סוג נתונים ב-BigQuery
__key__.app שם האפליקציה ב-Datastore. מחרוזת
__key__.id המזהה של הישות, או null אם הערך של __key__.name מוגדר. מספר שלם
__key__.kind סוג הישות. מחרוזת
__key__.name השם של הישות, או null אם הערך של __key__.id הוא set. מחרוזת
__key__.namespace אם אפליקציית Datastore משתמשת במרחב שמות בהתאמה אישית, מרחב השמות של הישות. אחרת, מרחב השמות שמוגדר כברירת מחדל מיוצג על ידי מחרוזת ריקה. מחרוזת
__key__.path נתיב האב הקנוני של הישות, שכולל את רצף זוגות סוג-מזהה מישות השורש ועד לישות עצמה. לדוגמה: "Country", "USA", "PostalCode", 10011, "Route", 1234. מחרוזת