ציון סכימה

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

כשמעלים קובצי ייצוא של Avro,‏ Parquet,‏ ORC,‏ Firestore או Datastore, הסכימה מאוחזרת באופן אוטומטי מנתוני המקור שמתארים את עצמם.

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

  • משתמשים במסוף Google Cloud .
  • משתמשים בהצהרת SQL‏ CREATE TABLE.
  • בתוך השורה באמצעות כלי שורת הפקודה של BigQuery.
  • יוצרים קובץ סכימה בפורמט JSON.
  • מבצעים קריאה לשיטה jobs.insert ומגדירים את המאפיין schema בהגדרות של משימת load.
  • מבצעים קריאה לשיטה tables.insert ומגדירים את הסכימה במשאב הטבלה באמצעות המאפיין schema.

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

רכיבי סכימה

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

שמות של עמודות

שם העמודה יכול להכיל אותיות (a-z, A-Z), מספרים (0-9) או קווים תחתונים (_), והוא חייב להתחיל באות או בקו תחתון. אם משתמשים בשמות עמודות גמישים, ב-BigQuery אפשר להתחיל שם של עמודה במספר. יש לנקוט משנה זהירות כשמתחילים עמודות במספר, מכיוון ששימוש בשמות עמודות גמישים עם BigQuery Storage Read API או BigQuery Storage Write API דורש טיפול מיוחד. מידע נוסף על תמיכה בשמות גמישים של עמודות זמין במאמר שמות גמישים של עמודות.

האורך המקסימלי של שמות העמודות הוא 300 תווים. בשמות של עמודות אי אפשר להשתמש באף אחת מהתחיליות הבאות:

  • _TABLE_
  • _FILE_
  • _PARTITION
  • _ROW_TIMESTAMP
  • __ROOT__
  • _COLIDENTIFIER
  • _CHANGE_SEQUENCE_NUMBER
  • _CHANGE_TYPE
  • _CHANGE_TIMESTAMP

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

אם שם הטבלה (לדוגמה, test) זהה לאחד משמות העמודות שלה (לדוגמה, test), הביטוי SELECT מפרש את העמודה test כSTRUCT שמכילה את כל העמודות האחרות בטבלה. כדי להימנע מהתנגשות כזו, אפשר להשתמש באחת מהשיטות הבאות:

  • אל תשתמשו באותו שם לטבלה ולעמודות שלה.

  • אל תשתמשו ב-_field_ כתוספת לשם של עמודה. קידומות שמורות למערכת גורמות לשינוי שם אוטומטי במהלך שאילתות. לדוגמה, השאילתה SELECT _field_ FROM project1.dataset.test מחזירה עמודה בשם _field_1. אם אתם חייבים לשלוח שאילתה לעמודה עם השם הזה, אתם יכולים להשתמש בכינוי כדי לשלוט בפלט.

  • מקצים לטבלה כינוי אחר. לדוגמה, השאילתה הבאה מקצה כינוי לטבלה t לטבלה project1.dataset.test:

    SELECT test FROM project1.dataset.test AS t;

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

    SELECT test.test FROM project1.dataset.test;

שמות גמישים של עמודות

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

שמות עמודות גמישים יכולים להכיל את התווים הבאים:

  • כל אות בכל שפה, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{L}.
  • כל תו מספרי בכל שפה, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{N}.
  • כל תו פיסוק של מחבר, כולל קו תחתון, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{Pc}.
  • מקף או קו מפריד, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \p{Pd}.
  • כל סימן שמיועד ללוות תו אחר, כפי שמיוצג על ידי הביטוי הרגולרי של Unicode:‏ \p{M}. לדוגמה, סימני הטעמה, אומלאוט או תיבות סוגרות.
  • התווים המיוחדים הבאים:
    • אמפרסנד (&) כמו שהוא מיוצג בביטוי הרגולרי של Unicode‏ \u0026.
    • סימן האחוז (%) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0025.
    • סימן שוויון (=) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003D.
    • סימן פלוס (+) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u002B.
    • נקודתיים (:) כמו שמיוצגות על ידי הביטוי הרגולרי של Unicode‏ \u003A.
    • גרש (') כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0027.
    • סימן קטן מ- (<) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003C.
    • הסימן גדול מ- (>) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003E.
    • סימן סולמית (#) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0023.
    • קו אנכי (|) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007c.
    • רווח לבן.

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

  • סימן קריאה (!) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0021.
  • מירכאות (") כמו שמיוצגות על ידי הביטוי הרגולרי של Unicode‏ \u0022.
  • סימן דולר ($) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0024.
  • סוגר שמאלי (() כמו שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0028.
  • סוגר ימני ()) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0029.
  • כוכבית (*) כפי שהיא מיוצגת על ידי הביטוי הרגולרי של Unicode‏ \u002A.
  • פסיק (,) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u002C.
  • נקודה (.) כפי שמיוצגת על ידי הביטוי הרגולרי של Unicode‏ \u002E. כשמשתמשים במיפוי תווים של שמות עמודות, הנקודות לא מוחלפות בקו תחתון בשמות העמודות בקובץ Parquet. מידע נוסף זמין במאמר בנושא מגבלות על עמודות גמישות.
  • לוכסן (/) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u002F.
  • נקודה ופסיק (;) כמו שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003B.
  • סימן שאלה (?) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u003F.
  • הסימן @, שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0040.@
  • סוגר מרובע שמאלי ([) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u005B.
  • קו נטוי הפוך (\) כמו שהוא מיוצג בביטוי הרגולרי של Unicode‏ \u005C.
  • סוגר מרובע ימני (]) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u005D.
  • סימן גג (^) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u005E.
  • סימן הטעם (`) כפי שהוא מיוצג על ידי הביטוי הרגולרי של Unicode‏ \u0060.
  • סוגר מסולסל שמאלי {{) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007B.
  • סוגר מסולסל ימני (}) כמו שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007D.
  • סימן טילדה (~) כפי שמיוצג על ידי הביטוי הרגולרי של Unicode‏ \u007E.

הנחיות נוספות זמינות במאמר שמות עמודות.

התווים המורחבים של העמודות נתמכים גם על ידי BigQuery Storage Read API וגם על ידי BigQuery Storage Write API. כדי להשתמש ברשימה המורחבת של תווי Unicode עם BigQuery Storage Read API, צריך להגדיר דגל. אפשר להשתמש במאפיין displayName כדי לאחזר את שם העמודה. בדוגמה הבאה אפשר לראות איך מגדירים דגל באמצעות לקוח Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

כדי להשתמש ברשימה המורחבת של תווי Unicode עם BigQuery Storage Write API, צריך לספק את הסכימה עם סימון column_name, אלא אם משתמשים באובייקט הכתיבה JsonStreamWriter. בדוגמה הבאה אפשר לראות איך מספקים את הסכימה:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

בדוגמה הזו, item_name_column ו-item_description_column הם שמות של משתני מיקום שצריכים להיות תואמים למוסכמות למתן שמות של מאגר אחסון לפרוטוקולים. חשוב לזכור שcolumn_nameהערות תמיד מקבלות עדיפות על פני שמות של placeholder.

מגבלות

תיאורי העמודות

כל עמודה יכולה לכלול תיאור אופציונלי. התיאור הוא מחרוזת באורך של עד 1,024 תווים.

ערכי ברירת מחדל

ערך ברירת המחדל של עמודה חייב להיות literal או אחת מהפונקציות הבאות:

סוגי נתונים ב-GoogleSQL

ב-GoogleSQL אפשר לציין את סוגי הנתונים הבאים בסכימה. חובה לציין את סוג הנתונים.

שם סוג נתונים תיאור
מספר שלם INT64 ערכים מספריים ללא רכיבי שבר
נקודה צפה FLOAT64 הערכה של ערכים מספריים עם רכיבי שבר
מספרי NUMERIC ערכים מספריים מדויקים עם רכיבי שבר
BigNumeric BIGNUMERIC ערכים מספריים מדויקים עם רכיבי שבר
בוליאני BOOL TRUE או FALSE (לא תלוי-רישיות)
מחרוזת STRING נתונים של תווים באורך משתנה (Unicode)
בייטים BYTES נתונים בינאריים באורך משתנה
תאריך DATE תאריך לוגי ביומן
תאריך/שעה DATETIME שנה, חודש, יום, שעה, דקה, שנייה וחלק השנייה
שעה TIME שעה, ללא תאריך ספציפי
חותמת זמן TIMESTAMP נקודה מוחלטת בזמן, עם דיוק של מיקרו-שנייה
Struct (Record) STRUCT קונטיינר של שדות מסודרים, שלכל אחד מהם יש סוג (חובה) ושם שדה (אופציונלי)
מיקום גיאוגרפי GEOGRAPHY קבוצת נקודות על פני כדור הארץ (קבוצה של נקודות, קווים ומצולעים על הספרואיד של WGS84, עם קצוות גאודזיים)
JSON JSON מייצג JSON, פורמט קל להחלפת נתונים
RANGE RANGE טווח של ערכים DATE, DATETIME או TIMESTAMP

מידע נוסף על סוגי נתונים ב-GoogleSQL זמין במאמר בנושא סוגי נתונים ב-GoogleSQL.

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

מצבים

‫BigQuery תומך במצבים הבאים של העמודות. השדה הזה אופציונלי. אם לא מציינים את המצב, ברירת המחדל של העמודה היא NULLABLE.

מצב תיאור
Nullable העמודה מאפשרת ערכים של NULL (ברירת מחדל)
חובה אסור להשתמש בערכי NULL
שדה העמודה מכילה מערך של ערכים מהסוג שצוין

מידע נוסף על מצבים זמין במאמר mode ב-TableFieldSchema.

מצב עיגול

אם העמודה היא מסוג NUMERIC או BIGNUMERIC, אפשר להגדיר את אפשרות העמודה rounding_mode, שקובעת איך הערכים בעמודה הזו יעוגלו כשייכתבו לטבלה. אפשר להגדיר את האפשרות rounding_mode בעמודה ברמה העליונה או בשדה STRUCT. יש תמיכה במצבי העיגול הבאים:

  • ‫"ROUND_HALF_AWAY_FROM_ZERO": במצב הזה (ברירת המחדל) מעגלים את המספרים שבאמצע הדרך מאפס.
  • ‫"ROUND_HALF_EVEN": במצב הזה, אם המספר מסתיים ב-5, הוא מעוגל למספר הזוגי הקרוב ביותר.

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

בדוגמה הבאה נוצרת טבלה ומוכנסים אליה ערכים שעברו עיגול בהתאם למצב העיגול של העמודה:

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

הטבלה mytable נראית כך:

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

מידע נוסף זמין במאמר roundingMode בTableFieldSchema.

ציון סכימות

כשאתם טוענים נתונים או יוצרים טבלה ריקה, אתם יכולים לציין את הסכימה של הטבלה באמצעות Google Cloud המסוף או כלי שורת הפקודה של BigQuery. אפשר לציין סכימה כשמעלים קובצי CSV ו-JSON (עם תווי שורה חדשה כמפריד). כשאתם טוענים נתוני ייצוא של Avro,‏ Parquet,‏ ORC,‏ Firestore או Datastore, הסכימה מאוחזרת באופן אוטומטי מנתוני המקור שמתארים את עצמם.

כדי לציין סכימת טבלה:

המסוף

במסוף Google Cloud , אפשר לציין סכימה באמצעות האפשרות הוספת שדה או האפשרות עריכה כטקסט.

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

    כניסה ל-BigQuery

  2. בחלונית הימנית, לוחצים על כלי הניתוחים:

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

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

  3. בחלונית Explorer, לוחצים על Datasets ואז על מערך הנתונים.

  4. בחלונית הפרטים, לוחצים על יצירת טבלה .

  5. בדף יצירת טבלה, בקטע מקור, בוחרים באפשרות טבלה ריקה.

  6. בדף יצירת טבלה, בקטע יעד:

    • בשדה Dataset name (שם קבוצת הנתונים), בוחרים את קבוצת הנתונים המתאימה.

      בוחרים מערך נתונים.

    • בשדה Table name (שם הטבלה), מזינים את שם הטבלה שיוצרים.

    • מוודאים שסוג הטבלה מוגדר לטבלה מקורית.

  7. בקטע Schema (סכימה), מזינים את הגדרת הסכימה.

    • אפשרות 1: משתמשים באפשרות הוספת שדה ומציינים את השם, הסוג והמצב של כל שדה.
    • אפשרות 2: לוחצים על Edit as text (עריכה כטקסט) ומדביקים את הסכימה כ מערך JSON. כשמשתמשים במערך JSON, יוצרים את הסכימה באותו תהליך שבו יוצרים קובץ סכימת JSON.

  8. לוחצים על יצירת טבלה.

SQL

משתמשים בהצהרה CREATE TABLE. מציינים את הסכימה באמצעות האפשרות column. בדוגמה הבאה נוצרת טבלה חדשה בשם newtable עם העמודות x,‏ y ו-z מהסוגים integer,‏ string ו-boolean:

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

    כניסה ל-BigQuery

  2. מזינים את ההצהרה הבאה בעורך השאילתות:

    CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRING, z BOOL)
  OPTIONS(
    description = 'My example table');

  3. לוחצים על הפעלה.

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

BQ

מספקים את הסכימה בשורה בפורמט field:data_type,field:data_type באמצעות אחת מהפקודות הבאות:

  • אם אתם טוענים נתונים, משתמשים בפקודה bq load.
  • אם יוצרים טבלה ריקה, משתמשים בפקודה bq mk.

כשמציינים את הסכימה בשורת הפקודה, אי אפשר לכלול את הסוגים RECORD (STRUCT) או RANGE, אי אפשר לכלול תיאור של עמודה ואי אפשר לציין את מצב העמודה. ברירת המחדל של כל אמצעי התחבורה היא NULLABLE. כדי לכלול תיאורים, מצבים, סוגי RECORD וסוגי RECORD, צריך לספק במקום זאת קובץ סכימת JSON.RANGE

כדי לטעון נתונים לטבלה באמצעות הגדרת סכימה מוטבעת, מזינים את הפקודה load ומציינים את פורמט הנתונים באמצעות הדגל --source_format. אם אתם טוענים נתונים לטבלה בפרויקט שאינו פרויקט ברירת המחדל, צריך לכלול את מזהה הפרויקט בפורמט הבא: project_id:dataset.table_name.

(אופציונלי) מציינים את הדגל --location ומגדירים את הערך למיקום.

bq --location=location load \
--source_format=format \
project_id:dataset.table_name \
path_to_source \
schema

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

  • ‫location: שם המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות הקובץ ‎.bigqueryrc.
  • ‫format: NEWLINE_DELIMITED_JSON או CSV.
  • project_id: מזהה הפרויקט.
  • ‫dataset: מערך הנתונים שמכיל את הטבלה שאליה טוענים את הנתונים.
  • ‫table_name: השם של הטבלה שאליה אתם טוענים את הנתונים.
  • ‫path_to_source: המיקום של קובץ הנתונים בפורמט CSV או JSON במחשב המקומי או ב-Cloud Storage.
  • ‫schema: הגדרת הסכימה במקום.

דוגמה:

מזינים את הפקודה הבאה כדי לטעון נתונים מקובץ CSV מקומי בשם myfile.csv אל mydataset.mytable בפרויקט שמוגדר כברירת מחדל. הסכימה מצוינת בשורה.

bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING

מידע נוסף על טעינת נתונים ל-BigQuery זמין במאמר מבוא לטעינת נתונים.

כדי להגדיר הגדרת סכימה מוטבעת כשיוצרים טבלה ריקה, מזינים את הפקודה bq mk עם הדגל --table או -t. אם יוצרים טבלה בפרויקט שאינו פרויקט ברירת המחדל, מוסיפים את מזהה הפרויקט לפקודה בפורמט הבא: project_id:dataset.table.

bq mk --table project_id:dataset.table schema

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

  • project_id: מזהה הפרויקט.
  • ‫dataset: מערך נתונים בפרויקט.
  • ‫table: השם של הטבלה שיוצרים.
  • ‫schema: הגדרת סכימה מוטבעת.

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

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

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

C#‎

כדי לציין את הסכימה של טבלה כשאתם טוענים נתונים לטבלה:

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי C#הוראות ההגדרה שבמדריך למתחילים של BigQuery באמצעות ספריות לקוח. מידע נוסף מופיע במאמרי העזרה של BigQuery C# API.

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 


using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

כדי להגדיר סכימה כשיוצרים טבלה ריקה:


using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

כדי לציין את הסכימה של טבלה כשאתם טוענים נתונים לטבלה:

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

כדי להגדיר סכימה כשיוצרים טבלה ריקה:

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

כדי לציין את הסכימה של טבלה כשאתם טוענים נתונים לטבלה:

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCS {

  public static void runLoadJsonFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Json from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

כדי להגדיר סכימה כשיוצרים טבלה ריקה:

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

Python

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

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח. 

from google.cloud import bigquery

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

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

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    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))

כדי לציין סכימה כשיוצרים טבלה ריקה, צריך להגדיר את המאפיין Table.schema.

from google.cloud import bigquery

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

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

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

ציון קובץ סכימת JSON

אם אתם מעדיפים, אתם יכולים לציין את הסכימה באמצעות קובץ סכימת JSON במקום להשתמש בהגדרת סכימה מוטבעת. קובץ סכימת JSON מורכב ממערך JSON שמכיל את הרכיבים הבאים:

  • השם של העמודה
  • סוג הנתונים בעמודה
  • אופציונלי: השיטה של העמודה (אם לא מציינים שיטה, ברירת המחדל היא NULLABLE)
  • אופציונלי: השדות של העמודה אם היא מסוג STRUCT
  • אופציונלי: תיאור העמודה
  • אופציונלי: תגי המדיניות של העמודה, שמשמשים לבקרת גישה ברמת השדה
  • אופציונלי: האורך המקסימלי של הערכים בעמודה עבור סוגי STRING או BYTES
  • אופציונלי: הדיוק של העמודה עבור סוגים NUMERIC או BIGNUMERIC
  • אופציונלי: הסולם של העמודה עבור סוגים NUMERIC או BIGNUMERIC
  • אופציונלי: אוסף הכללים (collation) של העמודה לסוגים STRING
  • אופציונלי: ערך ברירת המחדל של העמודה
  • אופציונלי: מצב העיגול של העמודה, אם העמודה היא מסוג NUMERIC או BIGNUMERIC

יצירת קובץ סכימת JSON

כדי ליצור קובץ סכימת JSON, מזינים TableFieldSchema לכל עמודה. חובה למלא את השדות name וtype. כל שאר השדות הם אופציונליים.

[
  {
    "name": string,
    "type": string,
    "mode": string,
    "fields": [
      {
        object (TableFieldSchema)
      }
    ],
    "description": string,
    "policyTags": {
      "names": [
        string
      ]
    },
    "maxLength": string,
    "precision": string,
    "scale": string,
    "collation": string,
    "defaultValueExpression": string,
    "roundingMode": string
  },
  {
    "name": string,
    "type": string,
    ...
  }
]

אם העמודה היא מסוג RANGE<T>, צריך להשתמש בשדה rangeElementType כדי לתאר את T, כאשר T חייב להיות אחד מהערכים DATE,‏ DATETIME או TIMESTAMP.

[
  {
    "name": "duration",
    "type": "RANGE",
    "mode": "NULLABLE",
    "rangeElementType": {
      "type": "DATE"
    }
  }
]

מערך ה-JSON מסומן על ידי הסוגריים המרובעים [] בתחילת המערך ובסופו. צריך להפריד בין הערכים בכל עמודה באמצעות פסיק: },.

כדי לכתוב סכימת טבלה קיימת לקובץ מקומי:

BQ

bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

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

  • project_id: מזהה הפרויקט.
  • ‫dataset: מערך נתונים בפרויקט.
  • ‫table: השם של סכימת טבלה קיימת.
  • ‫path_to_file: המיקום של הקובץ המקומי שאליו אתם כותבים את סכימת הטבלה.

Python

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

כדי לכתוב קובץ JSON של סכימה מטבלה באמצעות ספריית הלקוח של Python, קוראים לשיטה Client.schema_to_json. 
from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change the table_id variable to the full name of the
# table you want to get schema from.
table_id = "your-project.your_dataset.your_table_name"

# TODO(dev): Change schema_path variable to the path
# of your schema file.
schema_path = "path/to/schema.json"
table = client.get_table(table_id)  # Make an API request.

# Write a schema file to schema_path with the schema_to_json method.
client.schema_to_json(table.schema, schema_path)

with open(schema_path, "r", encoding="utf-8") as schema_file:
    schema_contents = schema_file.read()

# View table properties
print(f"Got table '{table.project}.{table.dataset_id}.{table.table_id}'.")
print(f"Table schema: {schema_contents}")

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

לדוגמה, מערך ה-JSON הבא מייצג סכימת טבלה בסיסית. לסכימה הזו יש שלוש עמודות: qtr (REQUIRED STRING),‏ rep (NULLABLE STRING) ו-sales (NULLABLE FLOAT).

[
  {
    "name": "qtr",
    "type": "STRING",
    "mode": "REQUIRED",
    "description": "quarter"
  },
  {
    "name": "rep",
    "type": "STRING",
    "mode": "NULLABLE",
    "description": "sales representative"
  },
  {
    "name": "sales",
    "type": "FLOAT",
    "mode": "NULLABLE",
    "defaultValueExpression": "2.55"
  }
]

שימוש בקובץ סכימת JSON

אחרי שיוצרים את קובץ סכימת ה-JSON, אפשר לציין אותו באמצעות כלי שורת הפקודה של BigQuery. אי אפשר להשתמש בקובץ סכימה עם Google Cloud המסוף או ה-API.

מספקים את קובץ הסכימה:

  • אם אתם טוענים נתונים, משתמשים בפקודה bq load.
  • אם יוצרים טבלה ריקה, משתמשים בפקודה bq mk.

כשמספקים קובץ סכימת JSON, הוא צריך להיות מאוחסן במיקום שאפשר לקרוא ממנו באופן מקומי. אי אפשר לציין קובץ סכימת JSON שמאוחסן ב-Cloud Storage או ב-Google Drive.

ציון קובץ סכימה כשמעלים נתונים

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

BQ

bq --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

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

  • ‫location: שם המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, אתם יכולים להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
  • ‫format: NEWLINE_DELIMITED_JSON או CSV.
  • project_id: מזהה הפרויקט.
  • ‫dataset: מערך הנתונים שמכיל את הטבלה שאליה טוענים את הנתונים.
  • ‫table: שם הטבלה שאליה טוענים את הנתונים.
  • ‫path_to_data_file: המיקום של קובץ הנתונים בפורמט CSV או JSON במחשב המקומי או ב-Cloud Storage.
  • ‫path_to_schema_file: הנתיב לקובץ הסכימה במחשב המקומי.

דוגמה:

מזינים את הפקודה הבאה כדי לטעון נתונים מקובץ CSV מקומי בשם myfile.csv אל mydataset.mytable בפרויקט שמוגדר כברירת מחדל. הסכימה מוגדרת בקובץ myschema.json בספרייה הנוכחית.

bq load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

Python

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

כדי לטעון סכימת טבלה מקובץ JSON באמצעות ספריית הלקוח של Python, קוראים לשיטה schema_from_json. 
from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change uri variable to the path of your data file.
uri = "gs://your-bucket/path/to/your-file.csv"
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

job_config = bigquery.LoadJobConfig(
    # To use the schema you loaded pass it into the
    # LoadJobConfig constructor.
    schema=schema,
    skip_leading_rows=1,
)

# Pass the job_config object to the load_table_from_file,
# load_table_from_json, or load_table_from_uri method
# to use the schema on a new table.
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)  # Make an API request.
print(f"Loaded {destination_table.num_rows} rows to {table_id}.")

ציון קובץ סכימה כשיוצרים טבלה

כדי ליצור טבלה ריקה במערך נתונים קיים באמצעות קובץ סכימת JSON:

BQ

bq mk --table project_id:dataset.table path_to_schema_file

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

  • project_id: מזהה הפרויקט.
  • ‫dataset: מערך נתונים בפרויקט.
  • ‫table: השם של הטבלה שיוצרים.
  • ‫path_to_schema_file: הנתיב לקובץ הסכימה במחשב המקומי.

לדוגמה, הפקודה הבאה יוצרת טבלה בשם mytable ב-mydataset בפרויקט ברירת המחדל. הסכימה מצוינת ב-myschema.json בספרייה הנוכחית:

bq mk --table mydataset.mytable ./myschema.json

Python

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

כדי לבצע אימות ב-BigQuery, צריך להגדיר את Application Default Credentials. מידע נוסף זמין במאמר הגדרת אימות לספריות לקוח.

כדי לטעון סכימת טבלה מקובץ JSON באמצעות ספריית הלקוח של Python, קוראים לשיטה schema_from_json. 
from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(f"Created table {table_id}.")

ציון סכימה ב-API

מציינים סכימת טבלה באמצעות ה-API:

  • כדי לציין סכמה כשמעלים נתונים, צריך להפעיל את השיטה jobs.insert ולהגדיר את המאפיין schema במשאב JobConfigurationLoad.

  • כדי לציין סכימה כשיוצרים טבלה, צריך לבצע קריאה ל-method‏ tables.insert ולהגדיר את המאפיין schema במשאב Table.

הגדרת סכימה באמצעות ה-API דומה לתהליך של יצירת קובץ סכימת JSON.

אבטחת טבלאות

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

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