יצירת קובץ הגדרת טבלה למקור נתונים חיצוני
קובץ הגדרת טבלה מאפשר ליצור טבלה חיצונית קבועה או זמנית באמצעות כלי שורת הפקודה של BigQuery. הקובץ מכיל את הגדרת הסכימה והמטא-נתונים של הטבלה החיצונית, כמו פורמט הנתונים והמאפיינים הקשורים. לדוגמה, כשמריצים את הפקודה bq mk --table, מציינים את הקובץ באמצעות הדגל --external_table_definition. אפשר להגדיר בקובץ הגדרת הטבלה את אותם מאפיינים שמתועדים במשאב ExternalDataConfiguration ב-API בארכיטקטורת REST.
במאמר הזה מוסבר איך ליצור קובצי הגדרת טבלה למקורות נתונים ב-Cloud Storage, ב-Google Drive וב-Bigtable.
מקורות נתונים ופורמטים נתמכים
אפשר ליצור קובצי הגדרת טבלה למקורות הנתונים החיצוניים הבאים:
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: ה-URI של Driveלדוגמה,
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: ה-URI של Driveלדוגמה,
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, יכול להיות שתצטרכו להוסיף תו בריחה (escape) לכוכבית בפלטפורמות מסוימות.
אם משתמשים בתו כללי לחיפוש מסוג כוכבית, צריך להקיף את הקטגוריה ואת שם הקובץ במירכאות. לדוגמה, אם יש לכם שני קבצים בשם 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