טעינת נתונים מקובצי ייצוא של Firestore

המסוף

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

   כניסה לדף BigQuery

2. בחלונית הימנית, לוחצים על explore Explorer.
3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
4. בקטע Dataset info, לוחצים על add_box Create table.
5. בחלונית Create table, מציינים את הפרטים הבאים:
1. בקטע Source, בוחרים באפשרות Google Cloud Storage ברשימה Create table from. לאחר מכן, מבצעים את הפעולות הבאות:
   1. בוחרים קובץ מהקטגוריה של Cloud Storage או מזינים את ה-URI של Cloud Storage. אי אפשר לכלול כמה מזהי URI במסוף Google Cloud , אבל יש תמיכה בתווים כלליים לחיפוש. הקטגוריה של Cloud Storage צריכה להיות באותו מיקום כמו מערך הנתונים שמכיל את הטבלה שרוצים ליצור, להוסיף לה או להחליף אותה. ‫
      ה-URI של קובץ הייצוא של Firestore צריך להסתיים ב-KIND_COLLECTION_ID.export_metadata. לדוגמה, בנתיב default_namespace_kind_Book.export_metadata, ‏Book הוא מזהה האוסף ו-default_namespace_kind_Book הוא שם הקובץ שנוצר על ידי Firestore. אם ה-URI לא מסתיים ב-KIND_COLLECTION_ID.export_metadata, תופיע הודעת השגיאה הבאה: does not contain valid backup metadata. (קוד שגיאה: לא תקין).
   2. בשדה פורמט קובץ, בוחרים באפשרות Cloud Datastore Backup. ‫Firestore ו-Datastore משתפים את פורמט הייצוא.
2. בקטע Destination, מציינים את הפרטים הבאים:
   1. בשדה Dataset, בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
   2. בשדה Table, מזינים את שם הטבלה שרוצים ליצור.
   3. מוודאים שהשדה Table type מוגדר ל-Native table.
3. בקטע Schema, לא צריך לעשות כלום. הסכימה נגזרת מייצוא מ-Firestore.
4. אופציונלי: מציינים את הגדרות המחיצה והאשכול. מידע נוסף זמין במאמרים יצירת טבלאות מחולקות למחיצות ויצירה של טבלאות מסודרות באשכולות ושימוש בהן.
5. לוחצים על אפשרויות מתקדמות ומבצעים את הפעולות הבאות:
   • בשדה Write preference, משאירים את האפשרות Write if empty מסומנת. ‫This option creates a new table and loads your data into it.
   • אם רוצים להתעלם מערכים בשורה שלא קיימים בסכימה של הטבלה, בוחרים באפשרות Unknown values.
   • בקטע Encryption, לוחצים על Customer-managed key כדי להשתמש במפתח של Cloud Key Management Service. אם משאירים את ההגדרה Google-managed key, הנתונים מוצפנים במצב מנוחה ב-BigQuery.
6. לוחצים על Create table.

BQ

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

כדי לטעון רק שדות ספציפיים, משתמשים בדגל --projection_fields.

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

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

• ‫LOCATION: המיקום שלכם. הדגל --location הוא אופציונלי.
• FORMAT: DATASTORE_BACKUP. ‫Datastore Backup היא האפשרות הנכונה ל-Firestore. ל-Firestore ול-Datastore יש פורמט ייצוא משותף.
• ‫DATASET: קבוצת הנתונים שמכילה את הטבלה שאליה אתם טוענים נתונים.
• ‫TABLE: הטבלה שאליה אתם טוענים נתונים. אם הטבלה לא קיימת, היא נוצרת.
• ‫PATH_TO_SOURCE: ה-URI של Cloud Storage.

לדוגמה, הפקודה הבאה טוענת את קובץ הייצוא של Firestore‏ 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

כדי לטעון נתוני ייצוא של Firestore באמצעות ה-API, מגדירים את המאפיינים הבאים:

1. יוצרים הגדרת משימה ב-load שמפנה לנתוני המקור ב-Cloud Storage.

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

3. השדה sourceUris צריך להיות מלא, בפורמט gs://BUCKET/OBJECT בהגדרות של משימת הטעינה. שם הקובץ (האובייקט) חייב להסתיים ב-KIND_NAME.export_metadata. אפשר להשתמש רק ב-URI אחד לייצוא של Firestore, ואי אפשר להשתמש בתו כללי לחיפוש.

4. מציינים את פורמט הנתונים על ידי הגדרת המאפיין sourceFormat לערך DATASTORE_BACKUP בהגדרות האישיות של משימת הטעינה. ‫Datastore Backup היא האפשרות הנכונה ל-Firestore. ל-Firestore ול-Datastore יש פורמט ייצוא משותף.

5. כדי לטעון רק שדות ספציפיים, מגדירים את המאפיין projectionFields.

6. אם אתם מחליפים טבלה קיימת, ציינו את אופן הכתיבה על ידי הגדרת המאפיין writeDisposition לערך WRITE_TRUNCATE.

Python

# TODO(developer): Set table_id to the ID of the table to create.
table_id = "your-project.your_dataset.your_table_name"

# TODO(developer): Set uri to the path of the kind export metadata
uri = (
    "gs://cloud-samples-data/bigquery/us-states"
    "/2021-07-02T16:04:48_70344/all_namespaces/kind_us-states"
    "/all_namespaces_kind_us-states.export_metadata"
)

# TODO(developer): Set projection_fields to a list of document properties
#                  to import. Leave unset or set to `None` for all fields.
projection_fields = ["name", "post_abbr"]

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.DATASTORE_BACKUP,
    projection_fields=projection_fields,
)

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))