הגדרת סכימה

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

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

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

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

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

רכיבי סכימה

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

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

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

האורך המקסימלי של שמות העמודות הוא 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 ‏ (gRPC). כדי להשתמש ברשימה המורחבת של תווי 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‏ (gRPC), צריך לספק לסכימה את הסימון 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 תמיד מקבלות עדיפות על פני שמות של פלייסהולדרים.

מגבלות

• שמות גמישים של עמודות נתמכים כברירת מחדל בטבלאות מנוהלות של Iceberg, בטבלאות חיצוניות של Iceberg ובטבלאות של Apache Iceberg שמנוהלות על ידי קטלוג ייעודי לזמן ריצה של Lakehouse. בטבלאות חיצוניות אחרות (כמו Parquet,‏ ORC,‏ Avro,‏ CSV או Delta Lake), שמות עמודות גמישים לא מופעלים כברירת מחדל. כדי לבקש הפעלה ברמת הפרויקט, צריך לפנות אל Cloud Customer Care.
  • בטבלאות Delta Lake, צריך גם להפעיל מיפוי עמודות במצב id או name.
• כשמייצאים טבלאות חיצוניות עם שמות עמודות גמישים לפורמטים של קבצים פתוחים (כמו Parquet או Avro באמצעות EXPORT DATA או משימות חילוץ), שמות עמודות שלא נתמכים ממופים לשמות גיבוב (hash) פנימיים שנוצרו (col_...), כי פורמטים של צד שלישי לא כוללים מטא-נתונים של שמות תצוגה ב-BigQuery.
• שמות עמודות גמישים לא נתמכים ב-SQL מדור קודם. חובה להשתמש ב-GoogleSQL.

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

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

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

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

• CURRENT_DATE
• CURRENT_DATETIME
• CURRENT_TIME
• CURRENT_TIMESTAMP
• GENERATE_UUID
• RAND
• SESSION_USER
• ST_GEOGPOINT

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

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

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

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

מצבים

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

מידע נוסף על מצבים זמין בקטע mode בTableFieldSchema.

מצב עיגול

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

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

אי אפשר להגדיר את האפשרות 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, הסכימה מאוחזרת באופן אוטומטי מנתוני המקור שמתארים את עצמם.

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

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

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

bq mk --table project_id:dataset.table schema

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

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);
    }
}

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
}

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());
    }
  }
}

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))

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
• אופציונלי: ההשוואה של העמודה לסוגים 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 show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

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 --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

bq load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.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 mk --table project_id:dataset.table path_to_schema_file

bq mk --table mydataset.mytable ./myschema.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:

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

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

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

אבטחת טבלאות

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

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

• איך מגדירים עמודות בתוך עמודות ועמודות חוזרות בהגדרת סכימה
• מידע על זיהוי אוטומטי של סכימה
• מידע על טעינת נתונים ל-BigQuery
• מידע ולמידה על יצירה ושימוש בטבלאות