שינוי סכימות של טבלה

במאמר הזה מוסבר איך לשנות את הגדרות הסכימה של טבלאות קיימות ב-BigQuery.

אפשר לבצע את רוב השינויים בסכימה שמתוארים במסמך הזה באמצעות הצהרות של שפת הגדרת נתונים (DDL) ב-SQL. לא חלים חיובים על הדוחות האלה.

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

הערה: כשמעדכנים סכימה, יכול להיות שהשינויים לא יופיעו מיד בתצוגות INFORMATION_SCHEMA.TABLES ו-INFORMATION_SCHEMA.COLUMNS. כדי לראות שינויים מיידיים בסכימה, צריך להתקשר אל השיטה tables.get.

הוספת עמודה

אפשר להוסיף עמודות להגדרת הסכימה של טבלה קיימת באמצעות אחת מהאפשרויות הבאות:

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

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

הוספת עמודה ריקה

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

כדי להוסיף עמודות ריקות להגדרת הסכימה של טבלה:

המסוף

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

   כניסה ל-BigQuery

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

   

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

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

4. לוחצים על סקירה כללית > טבלאות ובוחרים את הטבלה.

5. בחלונית הפרטים, לוחצים על הכרטיסייה סכימה.

6. לוחצים על עריכת הסכימה. יכול להיות שתצטרכו לגלול כדי לראות את הלחצן הזה.

7. בדף Current schema (סכימה נוכחית), בקטע New fields (שדות חדשים), לוחצים על Add field (הוספת שדה).

   • בשדה Name (שם), מקלידים את שם העמודה.
   • בשדה Type, בוחרים את סוג הנתונים.
   • בקטע Mode (מצב), בוחרים באפשרות NULLABLE או REPEATED.

8. כשמסיימים להוסיף עמודות, לוחצים על שמירה.

הערה: אי אפשר להשתמש במסוף Google Cloud כדי להוסיף עמודה לטבלה חיצונית.

SQL

משתמשים בהצהרת ה-DDL‏ ALTER TABLE ADD COLUMN:

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

   כניסה ל-BigQuery

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

   ALTER TABLE mydataset.mytable
   ADD COLUMN new_column STRING;

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

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

הערה: אי אפשר להשתמש בהצהרת ALTER TABLE ADD COLUMN כדי להוסיף עמודה לטבלה חיצונית.

BQ

מריצים את הפקודה bq update ומספקים קובץ סכימת JSON. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט לשם מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
• ‫TABLE: שם הטבלה שרוצים לעדכן.
• ‫SCHEMA: הנתיב לקובץ סכימת ה-JSON במחשב המקומי.

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

אם מנסים להוסיף עמודות באמצעות הגדרת סכימה מוטבעת, צריך לספק את כל הגדרת הסכימה, כולל העמודות החדשות. מכיוון שאי אפשר לציין מצבי עמודות באמצעות הגדרת סכימה מוטבעת, העדכון משנה כל עמודה קיימת מסוג REPEATED ל-NULLABLE, ומופיעה השגיאה הבאה: BigQuery error in update operation: Provided Schema does not match Table PROJECT_ID:dataset.table. Field field has changed mode from REPEATED to NULLABLE.

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

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

1. קודם מריצים את הפקודה bq show עם הדגל --schema וכותבים את סכימת הטבלה הקיימת לקובץ. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל שלכם, צריך להוסיף את מזהה הפרויקט לשם של מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

   bq show \
   --schema \
   --format=prettyjson \
   PROJECT_ID:DATASET.TABLE > SCHEMA

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
   • ‫TABLE: שם הטבלה שרוצים לעדכן.
   • ‫SCHEMA: קובץ הגדרת הסכימה שנכתב במחשב המקומי.

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

      bq show \
      --schema \
      --format=prettyjson \
      mydataset.mytable > /tmp/myschema.json
   

2. פותחים את קובץ הסכימה בכלי לעריכת טקסט. הסכימה צריכה להיראות כך:

   [
     {
       "mode": "REQUIRED",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "mode": "REPEATED",
       "name": "column3",
       "type": "STRING"
     }
   ]
   

3. מוסיפים את העמודות החדשות לסוף הגדרת הסכימה. אם מנסים להוסיף עמודות חדשות במקום אחר במערך, מוצגת השגיאה הבאה: BigQuery error in update operation: Precondition Failed.

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

     [
       {
         "mode": "REQUIRED",
         "name": "column1",
         "type": "STRING"
       },
       {
         "mode": "REQUIRED",
         "name": "column2",
         "type": "FLOAT"
       },
       {
         "mode": "REPEATED",
         "name": "column3",
         "type": "STRING"
       },
       {
         "description": "my new column",
         "mode": "NULLABLE",
         "name": "column4",
         "type": "STRING"
       }
     ]
     

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

4. אחרי שמעדכנים את קובץ הסכימה, מריצים את הפקודה הבאה כדי לעדכן את הסכימה של הטבלה. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט לשם מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

   bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
   • ‫TABLE: שם הטבלה שרוצים לעדכן.
   • ‫SCHEMA: קובץ הגדרת הסכימה שנכתב במחשב המקומי.

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

   bq update mydataset.mytable /tmp/myschema.json
   

API

קוראים למתודה tables.patch ומשתמשים במאפיין schema כדי להוסיף עמודות ריקות להגדרת הסכימה. השיטה המועדפת היא tables.patch, כי השיטה tables.update מחליפה את כל משאב הטבלה.

Go

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

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

import (
	"context"
	"fmt"

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

// updateTableAddColumn demonstrates modifying the schema of a table to append an additional column.
func updateTableAddColumn(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()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	newSchema := append(meta.Schema,
		&bigquery.FieldSchema{Name: "phone", Type: bigquery.StringFieldType},
	)
	update := bigquery.TableMetadataToUpdate{
		Schema: newSchema,
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); 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.FieldList;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.Table;
import java.util.ArrayList;
import java.util.List;

public class AddEmptyColumn {

  public static void runAddEmptyColumn() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableId = "MY_TABLE_NAME";
    String newColumnName = "NEW_COLUMN_NAME";
    addEmptyColumn(newColumnName, datasetName, tableId);
  }

  public static void addEmptyColumn(String newColumnName, String datasetName, String tableId) {
    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();

      Table table = bigquery.getTable(datasetName, tableId);
      Schema schema = table.getDefinition().getSchema();
      FieldList fields = schema.getFields();

      // Create the new field/column
      Field newField = Field.of(newColumnName, LegacySQLTypeName.STRING);

      // Create a new schema adding the current fields, plus the new one
      List<Field> fieldList = new ArrayList<Field>();
      fields.forEach(fieldList::add);
      fieldList.add(newField);
      Schema newSchema = Schema.of(fieldList);

      // Update the table with the new schema
      Table updatedTable =
          table.toBuilder().setDefinition(StandardTableDefinition.of(newSchema)).build();
      updatedTable.update();
      System.out.println("Empty column successfully added to table");
    } catch (BigQueryException e) {
      System.out.println("Empty column was not added. \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function addEmptyColumn() {
  // Adds an empty column to the schema.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';
  const column = {name: 'size', type: 'STRING'};

  // Retrieve current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Update table schema
  const schema = metadata.schema;
  const new_schema = schema;
  new_schema.fields.push(column);
  metadata.schema = new_schema;

  const [result] = await table.setMetadata(metadata);
  console.log(result.schema.fields);
}

Python

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

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

מוסיפים אובייקט חדש של SchemaField לעותק של Table.schema ואז מחליפים את הערך של המאפיין 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 add an empty column.
# table_id = "your-project.your_dataset.your_table_name"

table = client.get_table(table_id)  # Make an API request.

original_schema = table.schema
new_schema = original_schema[:]  # Creates a copy of the schema.
new_schema.append(bigquery.SchemaField("phone", "STRING"))

table.schema = new_schema
table = client.update_table(table, ["schema"])  # Make an API request.

if len(table.schema) == len(original_schema) + 1 == len(new_schema):
    print("A new column has been added.")
else:
    print("The column has not been added.")

הוספת עמודה משנית לעמודה RECORD

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

המסוף

הוספה של שדה חדש עם היררכיה לעמודה קיימת RECORD לא נתמכת במסוף Google Cloud .

SQL

הוספת שדה מקונן חדש לעמודה RECORD קיימת באמצעות הצהרת SQL DDL אינה נתמכת.

BQ

מריצים את הפקודה bq update ומספקים קובץ סכימה ב-JSON שמוסיף את השדה המקונן להגדרת הסכימה של העמודה הקיימת RECORD. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל שלכם, צריך להוסיף את מזהה הפרויקט לשם מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
• ‫TABLE: שם הטבלה שרוצים לעדכן.
• ‫SCHEMA : הנתיב לקובץ סכימת ה-JSON במחשב המקומי.

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

כדי להוסיף עמודה מקוננת ל-RECORD באמצעות קובץ סכימת JSON:

1. קודם מריצים את הפקודה bq show עם הדגל --schema וכותבים את סכימת הטבלה הקיימת לקובץ. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט לשם של מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.TABLE.

   bq show \
   --schema \
   --format=prettyjson \
   PROJECT_ID:DATASET.TABLE > SCHEMA

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
   • ‫TABLE: שם הטבלה שרוצים לעדכן.
   • ‫SCHEMA: קובץ הגדרת הסכימה שנכתב במחשב המקומי.

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

   bq show \
   --schema \
   --format=prettyjson \
   mydataset.mytable > /tmp/myschema.json
   

2. פותחים את קובץ הסכימה בכלי לעריכת טקסט. הסכימה צריכה להיראות כך: בדוגמה הזו, column3 היא עמודה חוזרת מקוננת. העמודות המקוננות הן nested1 ו-nested2. המערך fields מפרט את השדות שמוטמעים בתוך column3.

   [
     {
       "mode": "REQUIRED",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "fields": [
         {
           "mode": "NULLABLE",
           "name": "nested1",
           "type": "STRING"
         },
         {
           "mode": "NULLABLE",
           "name": "nested2",
           "type": "STRING"
         }
       ],
       "mode": "REPEATED",
       "name": "column3",
       "type": "RECORD"
     }
   ]
   

3. מוסיפים את העמודה החדשה המקוננת לסוף המערך fields. בדוגמה הזו, nested3 היא העמודה החדשה שמוטמעת בתוך עמודה אחרת.

     [
       {
         "mode": "REQUIRED",
         "name": "column1",
         "type": "STRING"
       },
       {
         "mode": "REQUIRED",
         "name": "column2",
         "type": "FLOAT"
       },
       {
         "fields": [
           {
             "mode": "NULLABLE",
             "name": "nested1",
             "type": "STRING"
           },
           {
             "mode": "NULLABLE",
             "name": "nested2",
             "type": "STRING"
           },
           {
             "mode": "NULLABLE",
             "name": "nested3",
             "type": "STRING"
           }
         ],
         "mode": "REPEATED",
         "name": "column3",
         "type": "RECORD"
       }
     ]
     

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

4. אחרי שמעדכנים את קובץ הסכימה, מריצים את הפקודה הבאה כדי לעדכן את הסכימה של הטבלה. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט לשם מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

   bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
   • ‫TABLE: שם הטבלה שרוצים לעדכן.
   • ‫SCHEMA: הנתיב לקובץ סכימת ה-JSON במחשב המקומי.

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

   bq update mydataset.mytable /tmp/myschema.json
   

API

קוראים לשיטה tables.patch ומשתמשים במאפיין schema כדי להוסיף את העמודות המקוננות להגדרת הסכימה. מומלץ להשתמש בשיטה tables.patch כי השיטה tables.update מחליפה את כל משאב הטבלה.

הוספת עמודות כשמחליפים נתונים או מוסיפים נתונים

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

• Avro
• Parquet
• ORC
• CSV
• JSON

הוספת עמודות בעבודת טעינה מסוג 'הוספה'

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

• זיהוי אוטומטי (לקובצי CSV ו-JSON)
• סכימה שמוגדרת בקובץ סכימה בפורמט JSON (לקובצי CSV ו-JSON)
• נתוני המקור שמתארים את עצמם בקובצי ייצוא של Avro, ‏ ORC, ‏ Parquet ו-Datastore

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

כשמוסיפים עמודות חדשות במהלך פעולת צירוף, הערכים בעמודות החדשות מוגדרים כ-NULL בשורות הקיימות.

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

BQ

משתמשים בפקודה bq load כדי לטעון את הנתונים ומציינים את הדגל --noreplace כדי לציין שאתם מוסיפים את הנתונים לטבלה קיימת.

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

מגדירים את הדגל --schema_update_option לערך ALLOW_FIELD_ADDITION כדי לציין שהנתונים שמוסיפים מכילים עמודות חדשות.

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

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

מזינים את הפקודה load באופן הבא:

bq --location=LOCATION load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

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

• ‫LOCATION: שם המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, צריך להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
• ‫FORMAT: הפורמט של הסכימה. ‫NEWLINE_DELIMITED_JSON, CSV, AVRO, PARQUET, ORC או DATASTORE_BACKUP.
• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET: השם של מערך הנתונים שמכיל את הטבלה.
• ‫TABLE: שם הטבלה שרוצים לצרף.
• ‫PATH_TO_SOURCE: URI מלא של Cloud Storage, רשימה מופרדת בפסיקים של מזהי URI, או הנתיב לקובץ נתונים במחשב המקומי.
• ‫SCHEMA: הנתיב לקובץ סכימת JSON מקומי. קובץ סכימה נדרש רק לקובצי CSV ו-JSON כשלא מציינים את --autodetect. סכימות של Avro ו-Datastore נגזרות מנתוני המקור.

דוגמאות:

מזינים את הפקודה הבאה כדי לצרף קובץ נתונים מקומי בפורמט Avro‏, /tmp/mydata.avro, אל mydataset.mytable באמצעות עבודת טעינה. מכיוון שאפשר להסיק סכימות מנתוני Avro באופן אוטומטי, אין צורך להשתמש בדגל --autodetect. ‫mydataset נמצא בפרויקט ברירת המחדל שלכם.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=AVRO \
mydataset.mytable \
/tmp/mydata.avro

מזינים את הפקודה הבאה כדי לצרף קובץ נתונים בפורמט JSON עם תווי שורה חדשה כתוחמים ב-Cloud Storage אל mydataset.mytable באמצעות משימת טעינה. הדגל --autodetect משמש לזיהוי העמודות החדשות. ‫mydataset נמצא בפרויקט ברירת המחדל שלכם.

bq load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json

מזינים את הפקודה הבאה כדי לצרף קובץ נתונים בפורמט JSON עם תווי שורה חדשה כתוחמים ב-Cloud Storage אל mydataset.mytable באמצעות משימת טעינה. הסכימה שמכילה את העמודות החדשות מצוינת בקובץ סכימת JSON מקומי, /tmp/myschema.json. mydataset נמצא בmyotherproject, ולא בפרויקט ברירת המחדל שלך.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
myotherproject:mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json

API

מבצעים קריאה ל-method‏ jobs.insert. מגדירים משימת load ומגדירים את המאפיינים הבאים:

• אפשר להפנות לנתונים ב-Cloud Storage באמצעות המאפיין sourceUris.
• מגדירים את פורמט הנתונים באמצעות הנכס sourceFormat.
• מציינים את הסכימה במאפיין schema.
• מציינים את אפשרות העדכון של הסכימה באמצעות המאפיין schemaUpdateOptions.
• מגדירים את מאפיין הכתיבה של טבלת היעד ל-WRITE_APPEND באמצעות המאפיין writeDisposition.

Go

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

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

import (
	"context"
	"fmt"
	"os"

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

// createTableAndWidenLoad demonstrates augmenting a table's schema to add a new column via a load job.
func createTableAndWidenLoad(projectID, datasetID, tableID, filename 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, import data from a local file, but specify field additions are allowed.
	// Because the data has a second column (age), the schema is amended as part of
	// the load.
	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
	loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); 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.JobId;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LegacySQLTypeName;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.TableId;
import com.google.common.collect.ImmutableList;
import java.util.UUID;

public class AddColumnLoadAppend {

  public static void runAddColumnLoadAppend() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "/path/to/file.csv";
    addColumnLoadAppend(datasetName, tableName, sourceUri);
  }

  public static void addColumnLoadAppend(String datasetName, String tableName, String sourceUri)
      throws Exception {
    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);

      // Add a new column to a BigQuery table while appending rows via a load job.
      // 'REQUIRED' fields cannot  be added to an existing schema, so the additional column must be
      // 'NULLABLE'.
      Schema newSchema =
          Schema.of(
              Field.newBuilder("name", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.REQUIRED)
                  .build(),
              // Adding below additional column during the load job
              Field.newBuilder("post_abbr", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build());

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setSchema(newSchema)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_ADDITION))
              .build();

      // Create a job ID so that we can safely retry.
      JobId jobId = JobId.of(UUID.randomUUID().toString());
      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).setJobId(jobId).build());

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = loadJob.waitFor();

      // Check for errors
      if (completedJob == null) {
        throw new Exception("Job not executed since it no longer exists.");
      } else if (completedJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(
            "BigQuery was unable to load into the table due to an error: \n"
                + loadJob.getStatus().getError());
      }
      System.out.println("Column successfully added during load append job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function addColumnLoadAppend() {
  // Adds a new column to a BigQuery table while appending rows via a load job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const fileName = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // In this example, the existing table contains only the 'Name', 'Age',
  // & 'Weight' columns. 'REQUIRED' fields cannot  be added to an existing
  // schema, so the additional column must be 'NULLABLE'.
  const schema = 'Name:STRING, Age:INTEGER, Weight:FLOAT, IsMagic:BOOLEAN';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // Set load job options
  const options = {
    schema: schema,
    schemaUpdateOptions: ['ALLOW_FIELD_ADDITION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
  };

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(fileName, options);

  console.log(`Job ${job.id} completed.`);
  console.log(`New Schema:`);
  console.log(job.configuration.load.schema.fields);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, 'my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the length of the schema
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
print("Table {} contains {} columns.".format(table_id, len(table.schema)))

# Configures the load job to append the data to the destination table,
# allowing field addition
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION
]
# In this example, the existing table contains only the 'full_name' column.
# 'REQUIRED' fields cannot be added to an existing schema, so the
# additional column must be 'NULLABLE'.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="NULLABLE"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated length of the schema
table = client.get_table(table)
print("Table {} now contains {} columns.".format(table_id, len(table.schema)))

הוספת עמודות בעבודת שרשור של שאילתות

אפשר להוסיף עמודות לטבלה כשמצרפים אליה תוצאות של שאילתה.

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

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

BQ

משתמשים בפקודה bq query כדי להריץ שאילתה על הנתונים ומציינים את הדגל --destination_table כדי לציין לאיזו טבלה רוצים לצרף את הנתונים.

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

מגדירים את הדגל --schema_update_option לערך ALLOW_FIELD_ADDITION כדי לציין שתוצאות השאילתה שאתם מצרפים מכילות עמודות חדשות.

מציינים את הדגל use_legacy_sql=false כדי להשתמש בתחביר GoogleSQL בשאילתה.

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

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

bq --location=LOCATION query \
--destination_table PROJECT_ID:DATASET.TABLE \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'QUERY'

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

• ‫LOCATION: שם המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, צריך להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc. שימו לב: אי אפשר לצרף תוצאות של שאילתה לטבלה במיקום אחר.
• PROJECT_ID: מזהה הפרויקט.
• ‫dataset: השם של מערך הנתונים שמכיל את הטבלה שמוסיפים לה נתונים.
• ‫TABLE: שם הטבלה שרוצים לצרף.
• ‫QUERY: שאילתה בתחביר GoogleSQL.

דוגמאות:

מזינים את הפקודה הבאה כדי לשלוח שאילתה ל-mydataset.mytable בפרויקט ברירת המחדל ולהוסיף את תוצאות השאילתה ל-mydataset.mytable2 (גם בפרויקט ברירת המחדל).

bq query \
--destination_table mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

מזינים את הפקודה הבאה כדי לשלוח שאילתה ל-mydataset.mytable בפרויקט ברירת המחדל ולהוסיף את תוצאות השאילתה ל-mydataset.mytable2 ב-myotherproject.

bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

API

מבצעים קריאה ל-method‏ jobs.insert. מגדירים משימת query ומגדירים את המאפיינים הבאים:

• מציינים את טבלת היעד באמצעות המאפיין destinationTable.
• מגדירים את מאפיין הכתיבה של טבלת היעד ל-WRITE_APPEND באמצעות המאפיין writeDisposition.
• מציינים את אפשרות העדכון של הסכימה באמצעות המאפיין schemaUpdateOptions.
• מציינים את שאילתת GoogleSQL באמצעות המאפיין query.

Go

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

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

import (
	"context"
	"fmt"

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

// createTableAndWidenQuery demonstrates how the schema of a table can be modified to add columns by appending
// query results that include the new columns.
func createTableAndWidenQuery(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()

	// First, we create a sample table.
	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	original := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, original); err != nil {
		return err
	}
	// Our table has two columns.  We'll introduce a new favorite_color column via
	// a subsequent query that appends to the table.
	q := client.Query("SELECT \"Timmy\" as full_name, 85 as age, \"Blue\" as favorite_color")
	q.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	q.WriteDisposition = bigquery.WriteAppend
	q.Location = "US"
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	_, err = job.Wait(ctx)
	if 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.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;

public class RelaxTableQuery {

  public static void runRelaxTableQuery() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    relaxTableQuery(projectId, datasetName, tableName);
  }

  // To relax all columns in a destination table when you append data to it during a query job
  public static void relaxTableQuery(String projectId, String datasetName, String tableName)
      throws Exception {
    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);

      String sourceTable = "`" + projectId + "." + datasetName + "." + tableName + "`";
      String query = "SELECT word FROM " + sourceTable + " WHERE word like '%is%'";

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setDestinationTable(tableId)
              .build();

      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).build());

      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new Exception("Job no longer exists");
      } else if (queryJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(queryJob.getStatus().getError().toString());
      }

      // Get the results.
      TableResult results = queryJob.getQueryResults();

      // Print all pages of the results.
      results
          .iterateAll()
          .forEach(
              rows -> {
                rows.forEach(row -> System.out.println("row: " + row.toString()));
              });

      System.out.println("Successfully relaxed all columns in destination table during query job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Columns not relaxed during query job \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function addColumnQueryAppend() {
  // Adds a new column to a BigQuery table while appending rows via a query job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // In this example, the existing table contains only the 'name' column.
  // 'REQUIRED' fields cannot  be added to an existing schema,
  // so the additional column must be 'NULLABLE'.
  const query = `SELECT name, year
    FROM \`bigquery-public-data.usa_names.usa_1910_2013\`
    WHERE state = 'TX'
    LIMIT 10`;

  // Set load job options
  const options = {
    query: query,
    schemaUpdateOptions: ['ALLOW_FIELD_ADDITION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
    // Location must match that of the dataset(s) referenced in the query.
    location: 'US',
  };

  const [job] = await bigquery.createQueryJob(options);
  console.log(`Job ${job.id} started.`);

  // Wait for the query to finish
  const [rows] = await job.getQueryResults();
  console.log(`Job ${job.id} completed.`);

  // Print the results
  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי 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 destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Retrieves the destination table and checks the length of the schema.
table = client.get_table(table_id)  # Make an API request.
print("Table {} contains {} columns".format(table_id, len(table.schema)))

# Configures the query to append the results to a destination table,
# allowing field addition.
job_config = bigquery.QueryJobConfig(
    destination=table_id,
    schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION],
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
)

# Start the query, passing in the extra configuration.
client.query_and_wait(
    # In this example, the existing table contains only the 'full_name' and
    # 'age' columns, while the results of this query will contain an
    # additional 'favorite_color' column.
    'SELECT "Timmy" as full_name, 85 as age, "Blue" as favorite_color;',
    job_config=job_config,
)  # Make an API request and wait for job to complete.

# Checks the updated length of the schema.
table = client.get_table(table_id)  # Make an API request.
print("Table {} now contains {} columns".format(table_id, len(table.schema)))

שינוי השם של עמודה

כדי לשנות את השם של עמודה בטבלה, משתמשים בהצהרת ALTER TABLE RENAME COLUMN DDL. בדוגמה הבאה משנים את השם של העמודה old_name ל-new_name ב-mytable:

ALTER TABLE mydataset.mytable
  RENAME COLUMN old_name TO new_name;

מידע נוסף על הצהרות ALTER TABLE RENAME COLUMN זמין בפרטים על DDL.

שינוי סוג הנתונים של עמודה

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

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

אפשר להשתמש ב-GoogleSQL כדי לבצע שינויים מסוימים בסוג הנתונים של עמודה. למידע נוסף ולרשימה מלאה של המרות נתמכות של סוגי נתונים, אפשר לעיין בהצהרת DDL של ALTER COLUMN SET DATA TYPE.

בדוגמה הבאה נוצרת טבלה עם עמודה מסוג INT64, ואז הסוג משתנה ל-NUMERIC:

CREATE TABLE mydataset.mytable(c1 INT64);

ALTER TABLE mydataset.mytable
ALTER COLUMN c1 SET DATA TYPE NUMERIC;

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

CREATE TABLE mydataset.mytable(s1 STRUCT<a INT64, b STRING>);

ALTER TABLE mydataset.mytable ALTER COLUMN s1
SET DATA TYPE STRUCT<a NUMERIC, b STRING>;

שינוי סוגי עמודות מקוננות

בשינויים מורכבים בסכימה, כמו שינוי שדה במערך של STRUCT, אין תמיכה בהצהרת DDL‏ ALTER TABLE. כפתרון עקיף, אפשר להשתמש בהצהרת CREATE OR REPLACE TABLE עם הצהרת SELECT כדי לשנות את סכימת הנתונים המקוננת.

בדוגמה הבאה אפשר לראות איך משנים עמודה במערך של STRUCTS:

נניח שיש טבלה samples.test עם הסכימה והנתונים הבאים:

CREATE OR REPLACE TABLE
  samples.test(D STRUCT <L ARRAY<STRUCT<R STRING, U STRING, V STRING>>, F STRING>);

INSERT INTO
  samples.test(D)
VALUES
  (STRUCT([STRUCT("r1", "u1", "v1"), STRUCT("r2", "u2", "v2")], "f1"));

התוצאה אמורה להיראות כך:

+----------------------------------------------------------------------------+
|                                     D                                      |
+----------------------------------------------------------------------------+
| {"L":[{"R":"r1","U":"u1","V":"v1"},{"R":"r2","U":"u2","V":"v2"}],"F":"f1"} |
+----------------------------------------------------------------------------+

נניח שאתם צריכים לשנות את סוג השדה U במערך המקונן של STRUCT ל-STRUCT<W STRING>. בדוגמה הבאה של הצהרת SQL אפשר לראות איך עושים את זה:

CREATE OR REPLACE TABLE
  samples.new_table AS
SELECT
  STRUCT(ARRAY(
    SELECT
      STRUCT(tmp.R,
        STRUCT(tmp.U AS W) AS U,
        tmp.V)
    FROM
      UNNEST(t.D.L) AS tmp) AS L,
    t.D.F) AS D
FROM
  samples.test AS t

ההצהרה הזו יוצרת טבלה חדשה, samples.new_table, עם סכימת היעד. הפונקציה UNNEST מרחיבה את מערך ה-STRUCT בתוך t.D.L. הביטוי STRUCT(tmp.U AS W) AS U בונה את ה-STRUCT החדש עם השדה W, שאוכלס בערך מהשדה המקורי U. הטבלה שמתקבלת, samples.new_table, כוללת את הסכימה והנתונים הבאים:

+----------------------------------------------------------------------------------------+
|                                           D                                            |
+----------------------------------------------------------------------------------------+
| {"L":[{"R":"r1","U":{"W":"u1"},"V":"v1"},{"R":"r2","U":{"W":"u2"},"V":"v2"}],"F":"f1"} |
+----------------------------------------------------------------------------------------+

המרת סוג הנתונים של עמודה

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

בדוגמה הבאה מוצגת שאילתת SQL שבוחרת את כל הנתונים מ-column_two ומ-column_three ב-mydataset.mytable ומבצעת המרה של column_one מ-DATE ל-STRING. תוצאת השאילתה משמשת להחלפת הטבלה הקיימת. הטבלה שמוחלפת מאחסנת את הערך column_one כסוג הנתונים STRING.

כשמשתמשים ב-CAST, שאילתה עלולה להיכשל אם ל-BigQuery אין אפשרות לבצע את ההמרה. פרטים על כללי המרת טיפוסים ב-GoogleSQL מופיעים במאמר בנושא המרת טיפוסים.

המסוף

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

   כניסה ל-BigQuery

2. בעורך השאילתות, מזינים את השאילתה הבאה כדי לבחור את כל הנתונים מ-column_two ומ-column_three ב-mydataset.mytable ולהמיר את column_one מ-DATE ל-STRING. השאילתה משתמשת בכינוי כדי להגדיר את column_one עם אותו שם. ‫mydataset.mytable נמצא בפרויקט ברירת המחדל שלכם.

   SELECT
    column_two,
    column_three,
    CAST(column_one AS STRING) AS column_one
   FROM
    mydataset.mytable;

3. לוחצים על עוד ובוחרים באפשרות הגדרות שאילתה.

4. בקטע יעד, מבצעים את הפעולות הבאות:

   1. בוחרים באפשרות הגדרת טבלת יעד לתוצאות השאילתה.

   2. בקטע Project name, משאירים את הערך שמוגדר לפרויקט ברירת המחדל. זהו הפרויקט שמכיל את mydataset.mytable.

   3. בשדה Dataset, בוחרים באפשרות mydataset.

   4. בשדה Table Id (מזהה הטבלה), מזינים mytable.

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

5. אופציונלי: בוחרים את המיקום של הנתונים.

6. כדי לעדכן את ההגדרות, לוחצים על שמירה.

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

   כשעבודת השאילתה מסתיימת, סוג הנתונים של column_one הוא STRING.

BQ

מזינים את הפקודה bq query הבאה כדי לבחור את כל הנתונים מ-column_two ומ-column_three ב-mydataset.mytable ולהפעיל את column_one מ-DATE אל STRING. השאילתה משתמשת בכינוי כדי להגדיר את column_one עם אותו שם. ‫mydataset.mytable נמצא בפרויקט ברירת המחדל שלכם.

תוצאות השאילתה נכתבות אל mydataset.mytable באמצעות הדגל --destination_table, והדגל --replace משמש להחלפת mytable. מציינים את הדגל use_legacy_sql=false כדי להשתמש בתחביר של GoogleSQL.

אפשר גם לציין את הדגל --location ולהגדיר את הערך למיקום.

bq query \
    --destination_table mydataset.mytable \
    --replace \
    --use_legacy_sql=false \
'SELECT
  column_two,
  column_three,
  CAST(column_one AS STRING) AS column_one
FROM
  mydataset.mytable'

API

כדי לבחור את כל הנתונים מ-column_two ומ-column_three ב-mydataset.mytable ולהמיר את column_one מ-DATE ל-STRING, קוראים לשיטה jobs.insert ומגדירים משימת query. אפשר גם לציין את המיקום במאפיין location בקטע jobReference.

שאילתת ה-SQL שבה נעשה שימוש בעבודת השאילתה תהיה SELECT column_two, column_three, CAST(column_one AS STRING) AS column_one FROM mydataset.mytable. השאילתה משתמשת בכינוי כדי להטיל את column_one עם אותו שם.

כדי להחליף את mytable בתוצאות השאילתה, צריך לכלול את mydataset.mytable במאפיין configuration.query.destinationTable ולציין את WRITE_TRUNCATE במאפיין configuration.query.writeDisposition.

שינוי המצב של עמודה

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

יצירת עמודה NULLABLE בטבלה קיימת

כדי לשנות את המצב של עמודה מ-REQUIRED ל-NULLABLE, בוחרים באחת מהאפשרויות הבאות:

המסוף

1. עוברים לדף BigQuery.

   כניסה ל-BigQuery

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

   

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

4. לוחצים על סקירה כללית > טבלאות ובוחרים את הטבלה.

5. בחלונית הפרטים, לוחצים על הכרטיסייה סכימה.

6. לוחצים על עריכת הסכימה. יכול להיות שתצטרכו לגלול כדי לראות את הלחצן הזה.

7. בדף Current schema (סכימה נוכחית), מאתרים את השדה שרוצים לשנות.

8. ברשימה הנפתחת Mode של השדה, בוחרים באפשרות NULLABLE.

9. כדי לעדכן את ההגדרות, לוחצים על שמירה.

הערה: אי אפשר להשתמש במסוף Google Cloud כדי לשנות עמודה בטבלה חיצונית.

SQL

משתמשים בהצהרת ה-DDL‏ ALTER COLUMN DROP NOT NULL. בדוגמה הבאה משנים את המצב של העמודה mycolumn מ-REQUIRED ל-NULLABLE:

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

   כניסה ל-BigQuery

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

   ALTER TABLE mydataset.mytable
   ALTER COLUMN mycolumn
   DROP NOT NULL;

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

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

BQ

1. קודם מריצים את הפקודה bq show עם הדגל --schema וכותבים את סכימת הטבלה הקיימת לקובץ. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט לשם של מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

   bq show \
   --schema \
   --format=prettyjson \
   PROJECT_ID:DATASET.TABLE > SCHEMA_FILE

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
   • ‫TABLE: שם הטבלה שרוצים לעדכן.
   • ‫SCHEMA_FILE: קובץ הגדרת הסכימה שנכתב במחשב המקומי.

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

     bq show \
     --schema \
     --format=prettyjson \
     mydataset.mytable > /tmp/myschema.json
   

2. פותחים את קובץ הסכימה בכלי לעריכת טקסט. הסכימה צריכה להיראות כך:

   [
     {
       "mode": "REQUIRED",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "mode": "REPEATED",
       "name": "column3",
       "type": "STRING"
     }
   ]
   

3. שינוי המצב של עמודה קיימת מ-REQUIRED ל-NULLABLE. בדוגמה הזו, המצב של column1 הוא relaxed.

   [
     {
       "mode": "NULLABLE",
       "name": "column1",
       "type": "STRING"
     },
     {
       "mode": "REQUIRED",
       "name": "column2",
       "type": "FLOAT"
     },
     {
       "mode": "REPEATED",
       "name": "column3",
       "type": "STRING"
     }
   ]
   

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

4. אחרי שמעדכנים את קובץ הסכימה, מריצים את הפקודה הבאה כדי לעדכן את הסכימה של הטבלה. אם הטבלה שאתם מעדכנים נמצאת בפרויקט שאינו פרויקט ברירת המחדל, צריך להוסיף את מזהה הפרויקט לשם מערך הנתונים בפורמט הבא: PROJECT_ID:DATASET.

   bq update PROJECT_ID:DATASET.TABLE SCHEMA

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

   • PROJECT_ID: מזהה הפרויקט.
   • ‫DATASET: שם מערך הנתונים שמכיל את הטבלה שאתם מעדכנים.
   • ‫TABLE: שם הטבלה שרוצים לעדכן.
   • ‫SCHEMA: הנתיב לקובץ סכימת ה-JSON במחשב המקומי.

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

     bq update mydataset.mytable /tmp/myschema.json
   

API

מתקשרים אל tables.patch ומשתמשים במאפיין schema כדי לשנות עמודה REQUIRED ל-NULLABLE בהגדרת הסכימה. השיטה המועדפת היא tables.patch, כי היא מחליפה את כל משאב הטבלה.tables.update

Go

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

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

import (
	"context"
	"fmt"

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

// relaxTableAPI demonstrates modifying the schema of a table to remove the requirement that columns allow
// no NULL values.
func relaxTableAPI(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()

	// Setup: We first create a table with a schema that's restricts NULL values.
	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	original := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	if err := client.Dataset(datasetID).Table(tableID).Create(ctx, original); err != nil {
		return err
	}

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	// Iterate through the schema to set all Required fields to false (nullable).
	var relaxed bigquery.Schema
	for _, v := range meta.Schema {
		v.Required = false
		relaxed = append(relaxed, v)
	}
	newMeta := bigquery.TableMetadataToUpdate{
		Schema: relaxed,
	}
	if _, err := tableRef.Update(ctx, newMeta, meta.ETag); 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.LegacySQLTypeName;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.Table;

public class RelaxColumnMode {

  public static void runRelaxColumnMode() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableId = "MY_TABLE_NAME";
    relaxColumnMode(datasetName, tableId);
  }

  public static void relaxColumnMode(String datasetName, String tableId) {
    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();

      Table table = bigquery.getTable(datasetName, tableId);

      // Create new relaxed schema based on the existing table schema
      Schema relaxedSchema =
          Schema.of(
              // The only supported modification you can make to a column's mode is changing it from
              // REQUIRED to NULLABLE
              // Changing a column's mode from REQUIRED to NULLABLE is also called column relaxation
              // INFO: LegacySQLTypeName will be updated to StandardSQLTypeName in release 1.103.0
              Field.newBuilder("word", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("word_count", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("corpus", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build(),
              Field.newBuilder("corpus_date", LegacySQLTypeName.STRING)
                  .setMode(Field.Mode.NULLABLE)
                  .build());

      // Update the table with the new schema
      Table updatedTable =
          table.toBuilder().setDefinition(StandardTableDefinition.of(relaxedSchema)).build();
      updatedTable.update();
      System.out.println("Table schema successfully relaxed.");
    } catch (BigQueryException e) {
      System.out.println("Table schema not relaxed \n" + e.toString());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function relaxColumn() {
  /**
   * Changes columns from required to nullable.
   * Assumes existing table with the following schema:
   * [{name: 'Name', type: 'STRING', mode: 'REQUIRED'},
   * {name: 'Age', type: 'INTEGER'},
   * {name: 'Weight', type: 'FLOAT'},
   * {name: 'IsMagic', type: 'BOOLEAN'}];
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  const newSchema = [
    {name: 'Name', type: 'STRING', mode: 'NULLABLE'},
    {name: 'Age', type: 'INTEGER'},
    {name: 'Weight', type: 'FLOAT'},
    {name: 'IsMagic', type: 'BOOLEAN'},
  ];

  // Retrieve current table metadata
  const table = bigquery.dataset(datasetId).table(tableId);
  const [metadata] = await table.getMetadata();

  // Update schema
  metadata.schema = newSchema;
  const [apiResponse] = await table.setMetadata(metadata);

  console.log(apiResponse.schema.fields);
}

Python

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

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

מחליפים את המאפיין Table.schema ברשימה של אובייקטים מסוג SchemaField עם המאפיין mode שמוגדר לערך 'NULLABLE'

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"

table = client.get_table(table_id)
new_schema = []
for field in table.schema:
    if field.mode != "REQUIRED":
        new_schema.append(field)
    else:
        # SchemaField properties cannot be edited after initialization.
        # To make changes, construct new SchemaField objects.
        new_field = field.to_api_repr()
        new_field["mode"] = "NULLABLE"
        relaxed_field = bigquery.SchemaField.from_api_repr(new_field)
        new_schema.append(relaxed_field)

table.schema = new_schema
table = client.update_table(table, ["schema"])

print(f"Updated {table_id} schema: {table.schema}.")

יצירת עמודה NULLABLE באמצעות משימת טעינה של צירוף

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

• כשמוסיפים נתונים מקובצי CSV ו-JSON, אפשר להגדיר את המצב של עמודות ספציפיות על ידי ציון קובץ סכימת JSON.
• כשמוסיפים נתונים מקובצי Avro,‏ ORC או Parquet, צריך להגדיר את העמודות בסכימה כ-NULL relaxed ולאפשר להסקת הסכימה לזהות את העמודות האלה.

הערה: הרחבת העמודות לא חלה על הוספות לייצוא של Datastore. העמודות בטבלאות שנוצרות על ידי טעינת קובצי ייצוא של Datastore הן תמיד NULLABLE.

כדי להרחיב עמודה מ-REQUIRED ל-NULLABLE כשמוסיפים נתונים לטבלה במהלך עבודת טעינה, בוחרים באחת מהאפשרויות הבאות:

המסוף

אי אפשר לשנות את המצב של עמוד באמצעות מסוף Google Cloud .

BQ

משתמשים בפקודה bq load כדי לטעון את הנתונים ומציינים את הדגל --noreplace כדי לציין שאתם מוסיפים את הנתונים לטבלה קיימת.

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

אפשר להסיק באופן אוטומטי עמודות עם הרפיה מקבצים בפורמטים Avro,‏ ORC ו-Parquet. הגמשת העמודות לא חלה על הוספות לייצוא של Datastore. העמודות בטבלאות שנוצרות על ידי טעינה של קובצי ייצוא של Datastore הן תמיד NULLABLE.

מגדירים את הדגל --schema_update_option לערך ALLOW_FIELD_RELAXATION כדי לציין שהנתונים שאתם מוסיפים מכילים עמודות עם הגבלות פחות מחמירות.

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

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

מזינים את הפקודה load באופן הבא:

bq --location=LOCATION load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=FORMAT \
PROJECT_ID:DATASET.TABLE \
PATH_TO_SOURCE \
SCHEMA

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

• ‫LOCATION: שם המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, צריך להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
• FORMAT: NEWLINE_DELIMITED_JSON, CSV, PARQUET, ORC, או AVRO. לא צריך להגדיר הקלה על כללי העמודות בקובצי DATASTORE_BACKUP. העמודות בטבלאות שנוצרות מקובצי ייצוא של Datastore הן תמיד NULLABLE.
• PROJECT_ID: מזהה הפרויקט.
• ‫dataset הוא שם מערך הנתונים שמכיל את הטבלה.
• TABLE: שם הטבלה שרוצים לצרף.
• ‫PATH_TO_SOURCE: URI מלא של Cloud Storage, רשימה מופרדת בפסיקים של מזהי URI, או הנתיב לקובץ נתונים במחשב המקומי.
• ‫SCHEMA: הנתיב לקובץ סכימת JSON מקומי. האפשרות הזו משמשת רק לקובצי CSV ו-JSON. העמודות המורחבות מוסקות באופן אוטומטי מקובצי Avro.

דוגמאות:

מזינים את הפקודה הבאה כדי לצרף קובץ נתונים מקומי בפורמט Avro‏, /tmp/mydata.avro, אל mydataset.mytable באמצעות עבודת טעינה. מכיוון שאפשר להסיק באופן אוטומטי עמודות עם הקלה על הגבלות מנתוני Avro, אין צורך לציין קובץ סכימה. ‫mydataset נמצא בפרויקט ברירת המחדל שלכם.

bq load \
    --noreplace \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --source_format=AVRO \
    mydataset.mytable \
    /tmp/mydata.avro

מזינים את הפקודה הבאה כדי לצרף נתונים מקובץ JSON עם תווי שורה להפרדה ב-Cloud Storage אל mydataset.mytable באמצעות משימת טעינה. הסכימה שמכילה את העמודות הגמישות נמצאת בקובץ סכימת JSON מקומי – /tmp/myschema.json. ‫mydataset נמצא בפרויקט ברירת המחדל שלכם.

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json

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

bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=CSV \
--autodetect \
myotherproject:mydataset.mytable \
mydata.csv

API

מבצעים קריאה ל-method‏ jobs.insert. מגדירים משימת load ומגדירים את המאפיינים הבאים:

• אפשר להפנות לנתונים ב-Cloud Storage באמצעות המאפיין sourceUris.
• מגדירים את פורמט הנתונים באמצעות הנכס sourceFormat.
• מציינים את הסכימה במאפיין schema.
• מציינים את אפשרות העדכון של הסכימה באמצעות המאפיין schemaUpdateOptions.
• מגדירים את מאפיין הכתיבה של טבלת היעד ל-WRITE_APPEND באמצעות המאפיין writeDisposition.

Go

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

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

import (
	"context"
	"fmt"
	"os"

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

// relaxTableImport demonstrates amending the schema of a table to relax columns from
// not allowing NULL values to allowing them.
func relaxTableImport(projectID, datasetID, tableID, filename 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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, import data from a local file, but specify relaxation of required
	// fields as a side effect while the data is appended.
	f, err := os.Open(filename)
	if err != nil {
		return err
	}
	source := bigquery.NewReaderSource(f)
	source.AutoDetect = true   // Allow BigQuery to determine schema.
	source.SkipLeadingRows = 1 // CSV has a single header line.

	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
	loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); 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.CsvOptions;
import com.google.cloud.bigquery.Field;
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.Table;
import com.google.cloud.bigquery.TableId;
import com.google.common.collect.ImmutableList;

// Sample to append relax column in a table.
public class RelaxColumnLoadAppend {

  public static void main(String[] args) {
    // 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.csv";
    relaxColumnLoadAppend(datasetName, tableName, sourceUri);
  }

  public static void relaxColumnLoadAppend(String datasetName, String tableName, String sourceUri) {
    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();

      // Retrieve destination table reference
      Table table = bigquery.getTable(TableId.of(datasetName, tableName));

      // column as a 'REQUIRED' field.
      Field name =
          Field.newBuilder("name", StandardSQLTypeName.STRING).setMode(Field.Mode.REQUIRED).build();
      Field postAbbr =
          Field.newBuilder("post_abbr", StandardSQLTypeName.STRING)
              .setMode(Field.Mode.REQUIRED)
              .build();
      Schema schema = Schema.of(name, postAbbr);

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      // Set job options
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(table.getTableId(), sourceUri)
              .setSchema(schema)
              .setFormatOptions(csvOptions)
              .setSchemaUpdateOptions(
                  ImmutableList.of(JobInfo.SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(JobInfo.WriteDisposition.WRITE_APPEND)
              .build();

      // Create a load job and wait for it to complete.
      Job job = bigquery.create(JobInfo.of(loadConfig));
      job = job.waitFor();
      // Check the job's status for errors
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Relax column append 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());
    }
  }
}

Node.js

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

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

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');

// Instantiate client
const bigquery = new BigQuery();

async function relaxColumnLoadAppend() {
  // Changes required column to nullable in load append job.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const fileName = '/path/to/file.csv';
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // In this example, the existing table contains the 'Name'
  // column as a 'REQUIRED' field.
  const schema = 'Age:INTEGER, Weight:FLOAT, IsMagic:BOOLEAN';

  // Retrieve destination table reference
  const [table] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .get();
  const destinationTableRef = table.metadata.tableReference;

  // Set load job options
  const options = {
    schema: schema,
    schemaUpdateOptions: ['ALLOW_FIELD_RELAXATION'],
    writeDisposition: 'WRITE_APPEND',
    destinationTable: destinationTableRef,
  };

  // Load data from a local file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(fileName, options);

  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

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

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

# from google.cloud import bigquery
# client = bigquery.Client()
# project = client.project
# dataset_ref = bigquery.DatasetReference(project, 'my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the number of required fields
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
# In this example, the existing table has 3 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the load job to append the data to a destination table,
# allowing field relaxation
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION
]
# In this example, the existing table contains three required fields
# ('full_name', 'age', and 'favorite_color'), while the data to load
# contains only the first two fields.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated number of required fields
table = client.get_table(table)
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

הפיכת כל העמודות ל-NULLABLE באמצעות עבודת צירוף

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

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

המסוף

אי אפשר לשנות את המצב של עמוד באמצעות מסוף Google Cloud .

BQ

משתמשים בפקודה bq query כדי להריץ שאילתה על הנתונים ומציינים את הדגל --destination_table כדי לציין לאיזו טבלה רוצים לצרף את הנתונים.

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

מגדירים את הדגל --schema_update_option לערך ALLOW_FIELD_RELAXATION כדי לציין שכל העמודות REQUIRED בטבלה שמוסיפים צריכות להשתנות לערך NULLABLE.

מציינים את הדגל use_legacy_sql=false כדי להשתמש בתחביר GoogleSQL בשאילתה.

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

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

bq --location=LOCATION query \
--destination_table PROJECT_ID:DATASET.TABLE \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'QUERY'

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

• ‫LOCATION: שם המיקום. הדגל --location הוא אופציונלי. לדוגמה, אם אתם משתמשים ב-BigQuery באזור טוקיו, צריך להגדיר את הערך של הדגל ל-asia-northeast1. אפשר להגדיר ערך ברירת מחדל למיקום באמצעות קובץ ‎.bigqueryrc.
• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET: השם של מערך הנתונים שמכיל את הטבלה שמוסיפים לה נתונים.
• ‫TABLE: שם הטבלה שרוצים לצרף.
• ‫QUERY: שאילתה בתחביר GoogleSQL.

דוגמאות:

מזינים את שאילתת הפקודה הבאה mydataset.mytable בפרויקט ברירת המחדל כדי לצרף את תוצאות השאילתה ל-mydataset.mytable2 (גם בפרויקט ברירת המחדל). הפקודה משנה את כל העמודות REQUIRED בטבלת היעד ל-NULLABLE.

bq query \
    --destination_table mydataset.mytable2 \
    --append_table \
    --schema_update_option=ALLOW_FIELD_RELAXATION \
    --use_legacy_sql=false \
    'SELECT
       column1,column2
     FROM
       mydataset.mytable'

מזינים את שאילתת הפקודה הבאה mydataset.mytable בפרויקט ברירת המחדל כדי לצרף את תוצאות השאילתה ל-mydataset.mytable2 ב-myotherproject. הפקודה משנה את כל העמודות REQUIRED בטבלת היעד ל-NULLABLE.

bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'SELECT
   column1,column2
 FROM
   mydataset.mytable'

API

מבצעים קריאה ל-method‏ jobs.insert. מגדירים משימת query ומגדירים את המאפיינים הבאים:

• מציינים את טבלת היעד באמצעות המאפיין destinationTable.
• מגדירים את מאפיין הכתיבה של טבלת היעד ל-WRITE_APPEND באמצעות המאפיין writeDisposition.
• מציינים את אפשרות העדכון של הסכימה באמצעות המאפיין schemaUpdateOptions.
• מציינים את שאילתת GoogleSQL באמצעות המאפיין query.

Go

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

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

import (
	"context"
	"fmt"

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

// relaxTableQuery demonstrates relaxing the schema of a table by appending query results to
// enable the table to allow NULL values.
func relaxTableQuery(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()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType, Required: true},
		{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
	}
	meta := &bigquery.TableMetadata{
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, meta); err != nil {
		return err
	}
	// Now, append a query result that includes nulls, but allow the job to relax
	// all required columns.
	q := client.Query("SELECT \"Beyonce\" as full_name")
	q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
	q.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
	q.WriteDisposition = bigquery.WriteAppend
	q.Location = "US"
	job, err := q.Run(ctx)
	if err != nil {
		return err
	}
	_, err = job.Wait(ctx)
	if 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.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.SchemaUpdateOption;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.QueryJobConfiguration;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;
import com.google.common.collect.ImmutableList;

public class RelaxTableQuery {

  public static void runRelaxTableQuery() throws Exception {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    relaxTableQuery(projectId, datasetName, tableName);
  }

  // To relax all columns in a destination table when you append data to it during a query job
  public static void relaxTableQuery(String projectId, String datasetName, String tableName)
      throws Exception {
    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);

      String sourceTable = "`" + projectId + "." + datasetName + "." + tableName + "`";
      String query = "SELECT word FROM " + sourceTable + " WHERE word like '%is%'";

      QueryJobConfiguration queryConfig =
          QueryJobConfiguration.newBuilder(query)
              // Use standard SQL syntax for queries.
              // See: https://cloud.google.com/bigquery/sql-reference/
              .setUseLegacySql(false)
              .setSchemaUpdateOptions(ImmutableList.of(SchemaUpdateOption.ALLOW_FIELD_RELAXATION))
              .setWriteDisposition(WriteDisposition.WRITE_APPEND)
              .setDestinationTable(tableId)
              .build();

      Job queryJob = bigquery.create(JobInfo.newBuilder(queryConfig).build());

      queryJob = queryJob.waitFor();

      // Check for errors
      if (queryJob == null) {
        throw new Exception("Job no longer exists");
      } else if (queryJob.getStatus().getError() != null) {
        // You can also look at queryJob.getStatus().getExecutionErrors() for all
        // errors, not just the latest one.
        throw new Exception(queryJob.getStatus().getError().toString());
      }

      // Get the results.
      TableResult results = queryJob.getQueryResults();

      // Print all pages of the results.
      results
          .iterateAll()
          .forEach(
              rows -> {
                rows.forEach(row -> System.out.println("row: " + row.toString()));
              });

      System.out.println("Successfully relaxed all columns in destination table during query job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Columns not relaxed during query job \n" + e.toString());
    }
  }
}

Python

לפני שמנסים את הדוגמה הזו, צריך לפעול לפי 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 destination table.
# table_id = "your-project.your_dataset.your_table_name"

# Retrieves the destination table and checks the number of required fields.
table = client.get_table(table_id)  # Make an API request.
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)

# In this example, the existing table has 2 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the query to append the results to a destination table,
# allowing field relaxation.
job_config = bigquery.QueryJobConfig(
    destination=table_id,
    schema_update_options=[bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION],
    write_disposition=bigquery.WriteDisposition.WRITE_APPEND,
)

# Start the query, passing in the extra configuration.
client.query_and_wait(
    # In this example, the existing table contains 'full_name' and 'age' as
    # required columns, but the query results will omit the second column.
    'SELECT "Beyonce" as full_name;',
    job_config=job_config,
)  # Make an API request and wait for job to complete

# Checks the updated number of required fields.
table = client.get_table(table_id)  # Make an API request.
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

שינוי ערך ברירת המחדל של עמודה

כדי לשנות את ערך ברירת המחדל של עמודה, בוחרים באחת מהאפשרויות הבאות:

המסוף

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

   כניסה ל-BigQuery

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

   

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

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

4. לוחצים על סקירה כללית > טבלאות ואז לוחצים על טבלה.

5. לוחצים על הכרטיסייה סכימה.

6. לוחצים על עריכת הסכימה. יכול להיות שתצטרכו לגלול כדי לראות את הלחצן הזה.

7. בדף Current schema (סכימה נוכחית), מאתרים את השדה ברמה העליונה שרוצים לשנות.

8. מזינים את ערך ברירת המחדל של השדה.

9. לוחצים על Save.

SQL

משתמשים בהצהרת ה-DDL‏ ALTER COLUMN SET DEFAULT.

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

   כניסה ל-BigQuery

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

   ALTER TABLE mydataset.mytable
   ALTER COLUMN column_name SET DEFAULT default_expression;

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

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

שינוי תיאור של עמודה

כדי לשנות את התיאור של עמודה, בוחרים באחת מהאפשרויות הבאות:

המסוף

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

   כניסה ל-BigQuery

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

   

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

4. לוחצים על סקירה כללית > טבלאות ובוחרים את הטבלה.

5. בחלונית הפרטים, לוחצים על הכרטיסייה סכימה.

6. לוחצים על עריכת הסכימה. יכול להיות שתצטרכו לגלול כדי לראות את הלחצן הזה.

7. בדף Current schema (סכימה נוכחית), מאתרים את השדה שרוצים לשנות.

8. מזינים את התיאור של השדה.

9. לוחצים על Save.

SQL

משתמשים בהצהרת ה-DDL‏ ALTER COLUMN SET OPTIONS.

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

   כניסה ל-BigQuery

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

   ALTER TABLE mydataset.mytable
   ALTER COLUMN column_name
   SET OPTIONS (description = 'This is a column description.');

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

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

Gemini

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

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

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

   כניסה ל-BigQuery

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

   

3. בחלונית Explorer מרחיבים את הפרויקט ואת מערך הנתונים, ואז בוחרים את הטבלה.

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

5. לוחצים על יצירה.

   הערה: אם הלחצן יצירה לא מופיע, לוחצים על תיאור הנתונים. יכול להיות שתצטרכו לגלול כדי לראות את הכפתור הזה.

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

6. כדי לערוך ולשמור את תיאורי העמודות שנוצרו:

   1. לוחצים על הצגת תיאורי העמודות.

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

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

   3. עורכים את תיאורי העמודות לפי הצורך ולוחצים על שמירה.

      תיאורי העמודות מתעדכנים באופן מיידי.

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

מחיקת עמודה

אפשר למחוק עמודה מטבלה קיימת באמצעות הצהרת ה-DDL‏ ALTER TABLE DROP COLUMN.

ההצהרה לא מפנה באופן מיידי את נפח האחסון שמשויך לעמודה שהוסרה. מידע נוסף על ההשפעה על האחסון כשמשמיטים עמוד באחסון זמין במאמר פרטי הצהרה.ALTER TABLE DROP COLUMN יש שתי אפשרויות לשחרור מיידי של נפח אחסון:

• החלפת טבלה באמצעות שאילתת SELECT * EXCEPT:

  CREATE OR REPLACE TABLE mydataset.mytable AS (
    SELECT * EXCEPT (column_to_delete) FROM mydataset.mytable
  );
  

• מייצאים את הנתונים ל-Cloud Storage, מוחקים את העמודות הלא רצויות ואז טוענים את הנתונים לטבלה חדשה עם הסכימה הנכונה.