יצירת קובץ הגדרת טבלה למקור נתונים חיצוני
בדף הזה מוסבר איך ליצור קובץ הגדרת טבלה, שהוא דרישה מוקדמת ליצירת מקור נתונים חיצוני באמצעות כלי שורת הפקודה של BigQuery. כדי ליצור את מקור הנתונים החיצוני, מריצים את הפקודה bg mk --table ומשתמשים בדגל --external_table_definition כדי לציין את קובץ הגדרת הטבלה.
קובץ הגדרת טבלה מכיל את הגדרת הסכימה ומטא-נתונים של טבלה חיצונית, כמו פורמט הנתונים של הטבלה ומאפיינים קשורים. אפשר להגדיר באותו קובץ הגדרת טבלה את אותם מאפיינים שמתועדים עבור משאב ExternalDataConfiguration ב-API בארכיטקטורת REST.
אתם יכולים ליצור קובצי הגדרות של טבלאות כדי לתאר טבלה חיצונית קבועה או זמנית עבור מקורות הנתונים החיצוניים הבאים:
Cloud Storage
- ערכים מופרדים בפסיקים (CSV)
- פורמט JSON שמופרד בתו שורה חדשה
- קובצי Avro
- קובצי ייצוא מ-Datastore
- קובצי ORC
- קבצי Parquet
- קובצי ייצוא מ-Firestore
Google Drive
- ערכים מופרדים בפסיקים (CSV)
- פורמט JSON שמופרד בתו שורה חדשה
- קובצי Avro
- Google Sheets
Bigtable
לפני שמתחילים
כדי ליצור קובץ הגדרת טבלה, צריך את ה-URI של מקור הנתונים:
- למקור נתונים ב-Drive, צריך את ה-URI של Drive
- אם מקור הנתונים הוא Cloud Storage, צריך את ה-URI של Cloud Storage.
- למקור נתונים של Bigtable, צריך את ה-URI של Bigtable.
יצירת קובץ הגדרה לקובצי CSV, JSON או Google Sheets
כשיוצרים קובץ הגדרת טבלה לקובצי CSV, JSON או Google Sheets ב-Cloud Storage או ב-Drive, אפשר לציין את סכימת הטבלה בדרכים הבאות:
שימוש בדגל autodetect
אם מציינים קובץ CSV, JSON או Google Sheets בלי לכלול תיאור סכימה מוטבע או קובץ סכימה, אפשר להשתמש בדגל --autodetect כדי להגדיר את האפשרות "autodetect" לערך true בקובץ הגדרת הטבלה. כשהאפשרות 'זיהוי אוטומטי' מופעלת, BigQuery מנסה להסיק את הסכימה באופן אוטומטי. מידע נוסף זמין במאמר בנושא זיהוי אוטומטי של סכימות למקורות נתונים חיצוניים.
שימוש בזיהוי אוטומטי עם מקור נתונים ב-Cloud Storage
יוצרים קובץ הגדרת טבלה למקור נתונים ב-Cloud Storage:
משתמשים בפקודה
bq mkdefעם הדגל--autodetectכדי ליצור קובץ הגדרת טבלה. הפקודהmkdefיוצרת קובץ הגדרת טבלה בפורמט JSON. בדוגמה הבאה נוצרת הגדרה של טבלה והפלט נכתב לקובץ:/tmp/file_name.bq mkdef \ --autodetect \ --source_format=SOURCE_FORMAT \ "URI" > /tmp/FILE_NAME
מחליפים את מה שכתוב בשדות הבאים:
SOURCE_FORMAT: פורמט הקובץFILE_NAME: השם של קובץ הגדרת הטבלה
URI: ה-URI של Cloud Storageלדוגמה,
gs://mybucket/myfile.
(אופציונלי) פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. לדוגמה, הפקודה
nano /tmp/file_nameפותחת את הקובץ ב-nano. אם מקור הנתונים החיצוני הוא קובץ CSV, הוא צריך להיראות כך: ההתראה"autodetect"מוגדרת ל-true.{ "autodetect": true, "csvOptions": { "allowJaggedRows": false, "allowQuotedNewlines": false, "encoding": "UTF-8", "fieldDelimiter": ",", "quote": "\"", "skipLeadingRows": 0 }, "sourceFormat": "CSV", "sourceUris": [ "URI" ] }
(אופציונלי) עורכים באופן ידני את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כלליות כמו
maxBadRecordsו-ignoreUnknownValues. אין הגדרות שספציפיות לקובצי מקור JSON, אבל יש הגדרות שחלות על קובצי CSV ועל קובצי Google Sheets. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.
שימוש בזיהוי אוטומטי עם מקור נתונים ב-Drive
יוצרים קובץ הגדרת טבלה למקור נתונים ב-Drive:
משתמשים בפקודה
bq mkdefעם הדגל--autodetectכדי ליצור הגדרת טבלה. הפקודהmkdefיוצרת קובץ הגדרת טבלה בפורמט JSON. בדוגמה הבאה נוצרת הגדרת טבלה והפלט נכתב לקובץ:/tmp/file_name.bq mkdef \ --autodetect \ --source_format=SOURCE_FORMAT \ "URI" > /tmp/FILE_NAME
מחליפים את מה שכתוב בשדות הבאים:
SOURCE_FORMAT: פורמט הקובץFILE_NAME: השם של קובץ הגדרת הטבלה
URI: Drive URIלדוגמה,
https://drive.google.com/open?id=123ABCD123AbcD123Abcd.
פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. לדוגמה, הפקודה
nano /tmp/file_nameפותחת את הקובץ ב-nano. אם מקור הנתונים החיצוני הוא Google Sheets, הקובץ צריך להיראות כך: ההודעה"autodetect"מוגדרת ל-true.{ "autodetect": true, "sourceFormat": "GOOGLE_SHEETS", "sourceUris": [ "URI" ] }
(אופציונלי) עורכים באופן ידני את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כלליות כמו
maxBadRecordsו-ignoreUnknownValues. אין הגדרות שספציפיות לקובצי מקור JSON, אבל יש הגדרות שחלות על קובצי CSV ועל קובצי Google Sheets. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.כדי לציין גיליון מסוים או טווח תאים בקובץ Google Sheets, מוסיפים את המאפיין
rangeלאובייקטGoogleSheetsOptionsבקובץ הגדרת הטבלה. כדי לשלוח שאילתה לגיליון מסוים, מציינים את שם הגיליון. כדי להריץ שאילתה על טווח תאים, מציינים את הטווח בפורמט:sheet_name!top_left_cell_id:bottom_right_cell_id, לדוגמה,"Sheet1!A1:B20". אם לא מציינים את הפרמטרrange, המערכת משתמשת בגיליון הראשון בקובץ.
שימוש בסכימה מוטבעת
אם לא רוצים להשתמש בזיהוי אוטומטי של סכימה, אפשר ליצור קובץ הגדרת טבלה על ידי ציון הגדרת סכימה מוטבעת. כדי לספק הגדרה של סכימה מוטבעת, מפרטים את השדות ואת סוגי הנתונים בשורת הפקודה בפורמט הבא: FIELD:DATA_TYPE,FIELD:DATA_TYPE.
שימוש בסכימה מוטבעת עם מקור נתונים ב-Cloud Storage או ב-Drive
יוצרים הגדרת טבלה למקור נתונים ב-Cloud Storage או ב-Drive באמצעות הגדרת סכימה מוטבעת:
משתמשים בפקודה
bq mkdefעם הדגל--noautodetectכדי ליצור הגדרת טבלה. הפקודהmkdefיוצרת קובץ הגדרת טבלה בפורמט JSON. בדוגמה הבאה נוצרת הגדרה של טבלה והפלט נכתב לקובץ:/tmp/file_name.bq mkdef \ --noautodetect \ --source_format=SOURCE_FORMAT \ "URI" \ FIELD:DATA_TYPE,FIELD:DATA_TYPE > /tmp/FILE_NAME
מחליפים את מה שכתוב בשדות הבאים
-
SOURCE_FORMAT: פורמט קובץ המקור
URI: ה-URI של Cloud Storage או ה-URI של Driveלדוגמה,
gs://mybucket/myfileל-Cloud Storage אוhttps://drive.google.com/open?id=123ABCD123AbcD123Abcdל-Drive.
FIELD:DATA_TYPE,FIELD:DATA_TYPE: הגדרת הסכימהלדוגמה,
Name:STRING,Address:STRING, ....FILE_NAME: השם של קובץ הגדרת הטבלה
-
(אופציונלי) פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. לדוגמה, הפקודה
nano /tmp/file_nameפותחת את הקובץ ב-nano. הקובץ צריך להיראות כך. שימו לב שהאפשרות"autodetect"לא מופעלת, ופרטי הסכימה נכתבים בקובץ הגדרת הטבלה.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "NEWLINE_DELIMITED_JSON", "sourceUris": [ "URI" ] }
(אופציונלי) עורכים באופן ידני את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כלליות כמו
maxBadRecordsו-ignoreUnknownValues. אין הגדרות שספציפיות לקובצי מקור JSON, אבל יש הגדרות שחלות על קובצי CSV ועל קובצי Google Sheets. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.
שימוש בקובץ סכימת JSON
אם אתם לא רוצים להשתמש בזיהוי אוטומטי או לספק הגדרה של סכימה מוטבעת, אתם יכולים ליצור קובץ סכימת JSON ולהפנות אליו כשאתם יוצרים את קובץ הגדרת הטבלה. יוצרים את קובץ סכימת ה-JSON באופן ידני במחשב המקומי. אין תמיכה בהפניה לקובץ סכימת JSON שמאוחסן ב-Cloud Storage או ב-Drive.
שימוש בקובץ סכימה עם מקור נתונים של Cloud Storage
יוצרים הגדרת טבלה למקור נתונים ב-Cloud Storage באמצעות קובץ סכימת JSON:
משתמשים בפקודה
bq mkdefעם הדגל--noautodetectכדי ליצור הגדרת טבלה. הפקודהmkdefיוצרת קובץ הגדרת טבלה בפורמט JSON. בדוגמה הבאה נוצרת הגדרה של טבלה והפלט נכתב לקובץ:/tmp/file_name.bq mkdef \ --noautodetect \ --source_format=SOURCE_FORMAT \ "URI" \ PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
מחליפים את מה שכתוב בשדות הבאים:
SOURCE_FORMAT: פורמט הקובץFILE_NAME: השם של קובץ הגדרת הטבלה
URI: ה-URI של Cloud Storageלדוגמה,
gs://mybucket/myfile.
PATH_TO_SCHEMA_FILE: המיקום של קובץ סכימת ה-JSON במחשב המקומי
(אופציונלי) פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. לדוגמה, הפקודה
nano /tmp/file_nameפותחת את הקובץ ב-
nano. הקובץ צריך להיראות כך. שימו לב שהאפשרות"autodetect"לא מופעלת, ופרטי הסכימה נכתבים בקובץ הגדרת הטבלה.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "NEWLINE_DELIMITED_JSON", "sourceUris": [ "URI" ] }
(אופציונלי) עורכים באופן ידני את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כלליות כמו
maxBadRecordsו-ignoreUnknownValues. אין הגדרות שספציפיות לקובצי מקור JSON, אבל יש הגדרות שחלות על קובצי CSV ועל קובצי Google Sheets. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.
שימוש בקובץ סכמה עם מקור נתונים ב-Drive
יוצרים הגדרת טבלה למקור נתונים ב-Drive באמצעות קובץ סכימת JSON:
משתמשים בפקודה
bq mkdefעם הדגל--noautodetectכדי ליצור הגדרת טבלה. הפקודהmkdefיוצרת קובץ הגדרת טבלה בפורמט JSON. בדוגמה הבאה נוצרת הגדרה של טבלה והפלט נכתב לקובץ:/tmp/file_name.bq mkdef \ --noautodetect \ --source_format=source_format \ "URI" \ PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
מחליפים את מה שכתוב בשדות הבאים:
-
SOURCE_FORMAT: פורמט קובץ המקור
URI: Drive URIלדוגמה,
https://drive.google.com/open?id=123ABCD123AbcD123Abcd.
PATH_TO_SCHEMA_FILE: המיקום של קובץ סכימת ה-JSON במחשב המקומיFILE_NAME: השם של קובץ הגדרת הטבלה
-
פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. לדוגמה, הפקודה
nano /tmp/file_nameפותחת את הקובץ ב-nano. הקובץ צריך להיראות כך. ההודעה"autodetect"לא מופעלת, ופרטי הסכימה נכתבים בקובץ הגדרת הטבלה.{ "schema": { "fields": [ { "name": "FIELD", "type": "DATA_TYPE" }, { "name": "FIELD", "type": "DATA_TYPE" } ... ] }, "sourceFormat": "GOOGLE_SHEETS", "sourceUris": [ "URI" ] }
(אופציונלי) עורכים באופן ידני את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כלליות כמו
maxBadRecordsו-ignoreUnknownValues. אין הגדרות שספציפיות לקובצי מקור JSON, אבל יש הגדרות שחלות על קובצי CSV ועל קובצי Google Sheets. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.כדי לציין גיליון מסוים או טווח תאים בקובץ Google Sheets, מוסיפים את המאפיין
rangeלאובייקטGoogleSheetsOptionsבקובץ הגדרת הטבלה. כדי לשלוח שאילתה לגיליון מסוים, מציינים את שם הגיליון. כדי להריץ שאילתה על טווח תאים, מציינים את הטווח בפורמט:sheet_name!top_left_cell_id:bottom_right_cell_id, לדוגמה,"Sheet1!A1:B20". אם לא מציינים את הפרמטרrange, המערכת משתמשת בגיליון הראשון בקובץ.
יצירת קובץ הגדרה לפורמטים עם תיאור עצמי
Avro, Parquet ו-ORC הם פורמטים עם תיאור עצמי. קבצי נתונים בפורמטים האלה מכילים מידע על הסכימה שלהם. אם משתמשים באחד מהפורמטים האלה כמקור נתונים חיצוני, BigQuery מאחזר אוטומטית את הסכימה באמצעות נתוני המקור. כשיוצרים הגדרת טבלה, לא צריך להשתמש בזיהוי אוטומטי של סכימה, ולא צריך לספק הגדרת סכימה מוטבעת או קובץ סכימה.
אפשר ליצור קובץ הגדרת טבלה לנתוני Avro, Parquet או ORC שמאוחסנים ב-Cloud Storage או ב-Drive:
משתמשים בפקודה
bq mkdefכדי ליצור הגדרת טבלה.bq mkdef \ --source_format=FORMAT \ "URI" > FILE_NAME
מחליפים את מה שכתוב בשדות הבאים:
FORMAT: פורמט המקור
URI: ה-URI של Cloud Storage או ה-URI של Driveלדוגמה,
gs://mybucket/myfileל-Cloud Storage אוhttps://drive.google.com/open?id=123ABCD123AbcD123Abcdל-Drive.FILE_NAME: השם של קובץ הגדרת הטבלה
אופציונלי: פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. הקובץ נראה כך:
{ "sourceFormat": "AVRO", "sourceUris": [ "URI" ] }
אופציונלי: עורכים ידנית את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כלליות כמו
maxBadRecordsו-ignoreUnknownValues. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.
יצירת קובץ הגדרה לנתונים שמחולקים למחיצות ב-Hive
משתמשים בפקודה bq mkdef עם הדגלים hive_partitioning_mode ו-hive_partitioning_source_uri_prefix כדי ליצור קובץ הגדרה לנתונים שמחולקים למחיצות ב-Hive ומאוחסנים ב-Cloud Storage, ב-Amazon Simple Storage Service (Amazon S3) או ב-Azure Blob Storage.
יצירת קובץ הגדרה ל-Datastore ול-Firestore
אם אתם משתמשים בייצוא של Datastore או Firestore כמקור נתונים חיצוני, BigQuery מאחזר באופן אוטומטי את הסכימה באמצעות נתוני המקור שמתארים את עצמם. כשיוצרים הגדרת טבלה, לא צריך לספק הגדרת סכימה מוטבעת או קובץ סכימה.
אתם יכולים ליצור קובץ הגדרת טבלה לנתונים מיוצאים מ-Datastore ומ-Firestore שמאוחסנים ב-Cloud Storage:
משתמשים בפקודה
bq mkdefכדי ליצור הגדרת טבלה. אין צורך להשתמש בדגל--noautodetectעם קובצי גיבוי של Datastore או Firestore. הזיהוי האוטומטי של סכימה מושבת בסוגי הקבצים האלה. הפקודהmkdefיוצרת קובץ הגדרת טבלה בפורמט JSON. בדוגמה הבאה נוצרת הגדרה של טבלה והפלט נכתב לקובץ:/tmp/file_name.bq mkdef \ --source_format=DATASTORE_BACKUP \ "URI" > /tmp/FILE_NAME
מחליפים את מה שכתוב בשדות הבאים:
-
URI: ה-URI של Cloud Storage FILE_NAME: השם של קובץ הגדרת הטבלה
פורמט המקור
DATASTORE_BACKUPמשמש גם את Datastore וגם את Firestore.-
(אופציונלי) פותחים את קובץ הגדרת הטבלה בכלי לעריכת טקסט. לדוגמה, הפקודה
nano /tmp/file_nameפותחת את הקובץ ב-nano. הקובץ צריך להיראות כך. שימו לב שלא צריך להגדיר את האפשרות"autodetect".{ "sourceFormat": "DATASTORE_BACKUP", "sourceUris": [ "gs://URI" ] }
(אופציונלי) עורכים ידנית את קובץ הגדרת הטבלה כדי לשנות, להוסיף או למחוק הגדרות כמו
maxBadRecordsו-ignoreUnknownValues. אין הגדרות שספציפיות לקובצי ייצוא של Datastore ו-Firestore. מידע נוסף זמין במאמרExternalDataConfigurationבהפניה ל-API.
יצירת קובץ הגדרה ל-Bigtable
כשיוצרים קובץ הגדרת טבלה ל-Bigtable, צריך ליצור את הקובץ בפורמט JSON באופן ידני. השימוש בפקודה mkdef ליצירת הגדרת טבלה אינו נתמך במקורות נתונים של Bigtable.
בנוסף, אין תמיכה בזיהוי אוטומטי של סכימה ב-Bigtable. רשימה של אפשרויות להגדרת טבלאות Bigtable מופיעה במאמר BigtableOptions בהפניית ה-API בארכיטקטורת REST.
קובץ הגדרת טבלה בפורמט JSON ל-Bigtable נראה כך. באמצעות קובץ הגדרת הטבלה הזה, BigQuery קורא נתונים מקבוצת עמודות אחת, ומפרש את הערכים כמספרים שלמים שמקודדים בפורמט בינארי.
{ "sourceFormat": "BIGTABLE", "sourceUris": [ "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID[/appProfiles/APP_PROFILE_ID]/tables/TABLE_NAME" ], "bigtableOptions": { "columnFamilies" : [ { "familyId": "FAMILY_ID", "type": "INTEGER", "encoding": "BINARY" } ] } }
מחליפים את מה שכתוב בשדות הבאים:
-
PROJECT_ID: הפרויקט שמכיל את אשכול Bigtable -
INSTANCE_ID: מזהה מכונת Bigtable -
APP_PROFILE_ID(אופציונלי): המזהה של פרופיל האפליקציה שרוצים להשתמש בו כדי לקרוא את נתוני Bigtable. הגדרות פרופיל האפליקציה מציינות אם הטבלה החיצונית משתמשת ב-Data Boost או בצמתים שהוקצו לחישוב. TABLE_NAME: שם הטבלה שאתם שולחים אליה שאילתה-
FAMILY_ID: מזהה קבוצת העמודות
מידע נוסף זמין במאמר בנושא אחזור ה-URI של Bigtable.
תמיכה בתווים כלליים לחיפוש בקובצי הגדרות של טבלאות
אם הנתונים שלכם מפוצלים לכמה קבצים, אתם יכולים להשתמש בתו כללי של כוכבית (*) כדי לבחור כמה קבצים. השימוש בתו הכללי לחיפוש כוכבית צריך לעמוד בכללים הבאים:
- הכוכבית יכולה להופיע בתוך שם האובייקט או בסוף שם האובייקט.
- אי אפשר להשתמש בכמה כוכביות. לדוגמה, הנתיב
gs://mybucket/fed-*/temp/*.csvלא תקין. - אי אפשר להשתמש בכוכבית עם שם הקטגוריה.
דוגמאות:
בדוגמה הבאה אפשר לראות איך בוחרים את כל הקבצים בכל התיקיות שמתחילות בקידומת
gs://mybucket/fed-samples/fed-sample:gs://mybucket/fed-samples/fed-sample*בדוגמה הבאה אפשר לראות איך בוחרים רק קבצים עם הסיומת
.csvבתיקייה בשםfed-samplesובכל תיקיות המשנה שלfed-samples:gs://mybucket/fed-samples/*.csvבדוגמה הבאה אפשר לראות איך בוחרים קבצים עם תבנית שמות של
fed-sample*.csvבתיקייה בשםfed-samples. בדוגמה הזו לא נבחרו קבצים בתיקיות משנה שלfed-samples.gs://mybucket/fed-samples/fed-sample*.csv
כשמשתמשים בכלי שורת הפקודה של BigQuery, יכול להיות שיהיה צורך להוסיף תו בריחה לכוכבית בפלטפורמות מסוימות.
אם משתמשים בתו כללי לחיפוש מסוג כוכבית, צריך להוסיף מרכאות לשם הקטגוריה ולשם הקובץ. לדוגמה, אם יש לכם שני קבצים בשמות fed-sample000001.csv ו-fed-sample000002.csv ואתם רוצים להשתמש בכוכבית כדי לבחור את שניהם, ה-URI של הקטגוריה יהיה "gs://mybucket/fed-sample*".
אסור להשתמש בתו הכללי * כשיוצרים קובצי הגדרות של טבלאות למקורות הנתונים הבאים:
- Bigtable. לנתוני Bigtable, אפשר לציין רק מקור נתונים אחד. ערך ה-URI חייב להיות כתובת URL תקינה של HTTPS לטבלת Bigtable.
- Datastore או Firestore. ייצוא של Datastore או Firestore שמאוחסן ב-Cloud Storage. בגיבויים של Datastore, אפשר לציין רק מקור נתונים אחד. ערך ה-URI חייב להסתיים ב-
.backup_infoאו ב-.export_metadata. - Drive. נתונים שמאוחסנים ב-Drive.
המאמרים הבאים
- איך שולחים שאילתות לנתונים ב-Cloud Storage
- איך שולחים שאילתות לגבי נתונים ב-Drive
- איך מריצים שאילתות על נתונים ב-Bigtable