יצירת טבלאות מסודרות באשכולות

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

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

לפני שמתחילים

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות ליצירת טבלה, בקשו מהאדמין להקצות לכם את תפקידי ה-IAM הבאים:

• משתמש במשימות ב-BigQuery ‏ (roles/bigquery.jobUser) בפרויקט, אם יוצרים טבלה על ידי טעינת נתונים או שמירת שאילתות שמורות בטבלה.
• BigQuery Data Editor ‏ (roles/bigquery.dataEditor) במערך הנתונים שבו יוצרים את הטבלה.

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

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

ההרשאות הנדרשות

כדי ליצור טבלה, צריך את ההרשאות הבאות:

• bigquery.tables.create במערך הנתונים שבו יוצרים את הטבלה.
• bigquery.tables.getData בכל הטבלאות והתצוגות שהשאילתה מפנה אליהן, אם שומרים את תוצאות השאילתה כטבלה.
• bigquery.jobs.create בפרויקט, אם יוצרים את הטבלה על ידי טעינת נתונים או על ידי שמירת שאילתה שמורה בטבלה.
• bigquery.tables.updateData בטבלה אם מוסיפים לטבלה או מחליפים אותה בתוצאות של שאילתה.

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

דרישות לגבי שמות של טבלאות

כשיוצרים טבלה ב-BigQuery, שם הטבלה צריך להיות ייחודי לכל מערך נתונים. שם הטבלה יכול:

• להכיל תווים באורך כולל של עד 1,024 בייטים בקידוד UTF-8.
• להכיל תווי Unicode בקטגוריות הבאות: L (אות), M (סימון), N (מספר), Pc (סימן חיבור, כולל קו תחתון), Pd (קו מפריד), Zs (רווח). מידע נוסף זמין במאמר קטגוריה כללית.

השמות הבאים הם דוגמאות לשמות תקינים של טבלאות: table 01, ग्राहक, 00_お客様, étudiant-01.

נקודות שצריך לשים לב אליהן:

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

• אם תכללו כמה אופרטורים של נקודה (.) ברצף, האופרטורים הכפולים יוסרו באופן משתמע.

  לדוגמה: project_name....dataset_name..table_name

  הופך לזה: project_name.dataset_name.table_name

דרישות לגבי תרשים עמודות מקובץ

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

עמודות אשכולות חייבות להיות עמודות ברמה העליונה, לא חוזרות, והן חייבות להיות אחד מסוגי הנתונים הבאים:

• BIGNUMERIC
• BOOL
• DATE
• DATETIME
• GEOGRAPHY
• INT64
• NUMERIC
• RANGE
• STRING
• TIMESTAMP

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

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

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

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

המסוף

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

   כניסה לדף BigQuery

2. בחלונית הימנית, לוחצים על Explorer.
3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
4. בקטע Dataset info, לוחצים על Create table.
5. בחלונית Create table, מציינים את הפרטים הבאים:
1. בקטע Source, בוחרים באפשרות Empty table ברשימה Create table from.
2. בקטע Destination, מציינים את הפרטים הבאים:
   1. בשדה Dataset, בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
   2. בשדה Table, מזינים את שם הטבלה שרוצים ליצור.
   3. מוודאים שהשדה Table type מוגדר ל-Native table.
3. בקטע Schema, מזינים את הגדרת הסכימה. אפשר להזין את פרטי הסכימה באופן ידני באחת מהשיטות הבאות:
   • אפשרות 1: לוחצים על Edit as text ומדביקים את הסכימה בצורה של מערך JSON. כשמשתמשים במערך JSON, יוצרים את הסכימה באותו תהליך שמשמש ליצירת קובץ סכימה של JSON. כדי להציג את הסכימה של טבלה קיימת בפורמט JSON, מזינים את הפקודה הבאה:

         bq show --format=prettyjson dataset.table
         

   • אפשרות 2: לוחצים על Add field ומזינים את סכימת הטבלה. מציינים את הערכים של השדות Name,‏ Type ו-Mode.
4. בשדה Clustering order, מזינים בין אחד לארבעה שמות של עמודות, מופרדים בפסיקים.
5. אופציונלי: בקטע Advanced options, אם רוצים להשתמש במפתח הצפנה בניהול הלקוח, בוחרים באפשרות Use a customer-managed encryption key (CMEK). כברירת מחדל, BigQuery מצפין תוכן של לקוחות שמאוחסן במצב מנוחה באמצעות Google-owned and Google-managed encryption key.
6. לוחצים על Create table.

SQL

משתמשים בפקודה CREATE TABLE DDL statement עם האפשרות CLUSTER BY. בדוגמה הבאה נוצרת טבלה מסודרת באשכולות בשם myclusteredtable ב-mydataset:

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

   כניסה ל-BigQuery

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

   CREATE TABLE mydataset.myclusteredtable
   (
     customer_id STRING,
     transaction_amount NUMERIC
   )
   CLUSTER BY
     customer_id
     OPTIONS (
       description = 'a table clustered by customer_id');

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

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

BQ

משתמשים בפקודה bq mk עם הדגלים הבאים:

• ‫--table (או מקש הקיצור -t).
• --schema. אפשר לספק את הגדרת הסכימה של הטבלה בתוך השורה או להשתמש בקובץ סכימת JSON.
• ‫--clustering_fields. אפשר לציין עד ארבע עמודות אשכולות.

הפרמטרים האופציונליים כוללים את --expiration,‏ --description,‏ --time_partitioning_type,‏ --time_partitioning_field,‏ --time_partitioning_expiration,‏ --destination_kms_key ו---label.

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

הדוגמה הזו לא ממחישה את --destination_kms_key. למידע על השימוש ב---destination_kms_key, קראו את המאמר מפתחות הצפנה בניהול הלקוח.

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

bq mk \
    --table \
    --expiration INTEGER1 \
    --schema SCHEMA \
    --clustering_fields CLUSTER_COLUMNS \
    --description "DESCRIPTION" \
    --label KEY:VALUE,KEY:VALUE \
    PROJECT_ID:DATASET.TABLE

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

• INTEGER1: משך החיים של הטבלה, בשניות, כברירת מחדל. הערך המינימלי הוא 3,600 שניות (שעה). זמן התפוגה מחושב לפי הזמן הנוכחי ב-UTC בתוספת הערך של המספר השלם. אם מגדירים את זמן התפוגה של הטבלה כשיוצרים אותה, המערכת מתעלמת מהגדרת ברירת המחדל של זמן התפוגה של הטבלה במערך הנתונים. הגדרת הערך הזה מוחקת את הטבלה אחרי הזמן שצוין.
• ‫SCHEMA: הגדרת סכימה בתוך השורה בפורמט COLUMN:DATA_TYPE,COLUMN:DATA_TYPE או הנתיב לקובץ הסכימה ב-JSON במחשב המקומי.
• ‫CLUSTER_COLUMNS: רשימה מופרדת בפסיקים של עד ארבע עמודות אשכולות. הרשימה לא יכולה להכיל רווחים.
• ‫DESCRIPTION: תיאור הטבלה, במירכאות.
• ‫KEY:VALUE: צמד המפתח/ערך שמייצג תווית. אפשר להזין כמה תוויות באמצעות רשימה שמופרדת בפסיקים.
• PROJECT_ID: מזהה הפרויקט.
• ‫DATASET: מערך נתונים בפרויקט.
• ‫TABLE: שם הטבלה שיוצרים.

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

דוגמאות:

מזינים את הפקודה הבאה כדי ליצור טבלה מסודרת באשכולות בשם myclusteredtable ב-mydataset בפרויקט ברירת המחדל. תפוגת התוקף של הטבלה מוגדרת ל-2,592,000 (חודש אחד של 30 יום), התיאור מוגדר ל-This is my clustered table והתווית מוגדרת ל-organization:development. בפקודה הזו משתמשים במקש הקיצור -t במקום --table.

הסכימה מצוינת בתוך השורה בתור: timestamp:timestamp,customer_id:string,transaction_amount:float. שדה האשכולות שצוין, customer_id, משמש לאשכולות בטבלה.

bq mk \
    -t \
    --expiration 2592000 \
    --schema 'timestamp:timestamp,customer_id:string,transaction_amount:float' \
    --clustering_fields customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    mydataset.myclusteredtable

מזינים את הפקודה הבאה כדי ליצור טבלה מסודרת באשכולות בשם myclusteredtable ב-myotherproject, ולא בפרויקט ברירת המחדל. התיאור מוגדר כ-This is my clustered table והתווית מוגדרת כ-organization:development. בפקודה הזו משתמשים במקש הקיצור -t במקום --table. הפקודה הזו לא מציינת תאריך תפוגה לטבלה. אם למערך הנתונים יש תאריך תפוגה שמוגדר כברירת מחדל, הוא יחול על הטבלה. אם לא הוגדר תאריך תפוגה כברירת מחדל לטבלאות במערך הנתונים, הטבלה לא תפוג לעולם.

הסכימה מצוינת בקובץ JSON מקומי: /tmp/myschema.json. השדה customer_id משמש לאשכול הטבלה.

bq mk \
    -t \
    --expiration 2592000 \
    --schema /tmp/myschema.json \
    --clustering_fields=customer_id \
    --description "This is my clustered table" \
    --label org:dev \
    myotherproject:mydataset.myclusteredtable

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

Terraform

משתמשים במשאב google_bigquery_table.

הערה: כדי ליצור אובייקטים של BigQuery באמצעות Terraform, צריך להפעיל את Cloud Resource Manager API.

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

בדוגמה הבאה נוצרת טבלה בשם mytable, שמקובצת לפי העמודות ID ו-Created:

resource "google_bigquery_dataset" "default" {
  dataset_id                      = "mydataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "mytable"

  clustering = ["ID", "Created"]

  schema = <<EOF
[
  {
    "name": "ID",
    "type": "INT64",
    "description": "Item ID"
  },
  {
    "name": "Item",
    "type": "STRING",
    "mode": "NULLABLE"
  },
 {
   "name": "Created",
   "type": "TIMESTAMP"
 }
]
EOF

}

כך מחילים את ההגדרות של Terraform בפרויקט ב- Google Cloud :

הכנת Cloud Shell

1. מפעילים את Cloud Shell.

2. מגדירים את פרויקט ברירת המחדל ב- Google Cloud שבו רוצים להחיל את ההגדרות של Terraform.

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

   export GOOGLE_CLOUD_PROJECT=PROJECT_ID

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

הכנת הספרייה

לכל קובץ תצורה של Terraform צריכה להיות ספרייה משלו (שנקראת גם מודול ברמה הבסיסית).

1. יוצרים ספרייה חדשה ב-Cloud Shell ובה יוצרים קובץ חדש. שם הקובץ חייב לכלול את הסיומת .tf, למשל main.tf. במדריך הזה, הקובץ נקרא main.tf.

   mkdir DIRECTORY && cd DIRECTORY && touch main.tf

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

   מעתיקים את הקוד לדוגמה בקובץ main.tf החדש שיצרתם.

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

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

   terraform init

   אופציונלי: תוכלו לכלול את האפשרות -upgrade, כדי להשתמש בגרסה העדכנית ביותר של הספק של Google:

   terraform init -upgrade

החלה של השינויים

1. בודקים את ההגדרות ומוודאים שהמשאבים שמערכת Terraform תיצור או תעדכן תואמים לציפיות שלכם:

   terraform plan

   מתקנים את ההגדרות לפי הצורך.

2. מריצים את הפקודה הבאה ומזינים yes בהודעה שמופיעה, כדי להחיל את הגדרות Terraform:

   terraform apply

   ממתינים עד שב-Terraform תוצג ההודעה "Apply complete!‎".

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

הערה: בדרך כלל הנחת העבודה בדוגמאות של Terraform היא שממשקי ה-API הנדרשים מופעלים בפרויקט ב- Google Cloud .

API

קוראים ל-method‏ tables.insert עם משאב טבלה מוגדר שמציין את המאפיין clustering.fields ואת המאפיין schema.

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 table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING"),
    bigquery.SchemaField("city", "STRING"),
    bigquery.SchemaField("zipcode", "INTEGER"),
]

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

המשך

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

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

import (
	"context"
	"fmt"
	"time"

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

// createTableClustered demonstrates creating a BigQuery table with advanced properties like
// partitioning and clustering features.
func createTableClustered(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: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	metaData := &bigquery.TableMetadata{
		Schema: sampleSchema,
		TimePartitioning: &bigquery.TimePartitioning{
			Field:      "timestamp",
			Expiration: 90 * 24 * time.Hour,
		},
		Clustering: &bigquery.Clustering{
			Fields: []string{"origin", "destination"},
		},
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

Java

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

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

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Clustering;
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.TableId;
import com.google.cloud.bigquery.TableInfo;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class CreateClusteredTable {
  public static void runCreateClusteredTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    createClusteredTable(datasetName, tableName);
  }

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

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      StandardTableDefinition tableDefinition =
          StandardTableDefinition.newBuilder()
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

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

יצירת טבלה מסודרת באשכולות מתוצאת שאילתה

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

• כותבים את התוצאות בטבלת יעד חדשה ומציינים את עמודות האשכולות.
• באמצעות הצהרת DDL CREATE TABLE AS SELECT. למידע נוסף על השיטה הזו, קראו את המאמר יצירת טבלה מסודרת באשכולות מתוצאה של שאילתה בדף שימוש בהצהרות של שפת הגדרת נתונים.

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

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

SQL

כדי ליצור טבלה מסודרת באשכולות מתוצאת שאילתה, משתמשים בהצהרת DDL של CREATE TABLE עם האפשרות CLUSTER BY. בדוגמה הבאה נוצרת טבלה חדשה באשכולות לפי customer_id, באמצעות שליחת שאילתה לטבלה קיימת שלא באשכולות:

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

   כניסה ל-BigQuery

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

   CREATE TABLE mydataset.clustered_table
   (
     customer_id STRING,
     transaction_amount NUMERIC
   )
   CLUSTER BY
     customer_id
   AS (
     SELECT * FROM mydataset.unclustered_table
   );

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

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

BQ

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

bq --location=LOCATION query \
    --use_legacy_sql=false 'QUERY'

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

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

דוגמאות:

מזינים את הפקודה הבאה כדי לכתוב את תוצאות השאילתה בטבלת יעד מקובצת בשם myclusteredtable ב-mydataset. ‫mydataset נמצא בפרויקט שמוגדר כברירת מחדל. השאילתה מאחזרת נתונים מטבלה לא מחולקת: mytable. העמודה customer_id משמשת לאשכול הטבלה. העמודה timestamp בטבלה משמשת ליצירת טבלה מחולקת למחיצות.

bq query --use_legacy_sql=false \
    'CREATE TABLE
       mydataset.myclusteredtable
     PARTITION BY
       DATE(timestamp)
     CLUSTER BY
       customer_id
     AS (
       SELECT
         *
       FROM
         `mydataset.mytable`
     );'

API

כדי לשמור את תוצאות השאילתה בטבלה מסודרת באשכולות, מפעילים את ה-method‏ jobs.insert, מגדירים משימת query וכוללים הצהרת CREATE TABLE DDL שיוצרת את הטבלה המסודרת באשכולות.

מציינים את המיקום במאפיין location בקטע jobReference של משאב המשימה.

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

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

למידע נוסף על טעינת נתונים, קראו את המאמר מבוא לטעינת נתונים ל-BigQuery.

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

SQL

משתמשים בהצהרה LOAD DATA. בדוגמה הבאה נטענים נתוני AVRO כדי ליצור טבלה שמחולקת למחיצות לפי השדה transaction_date ומקובצת לפי השדה customer_id. הוא גם מגדיר את המחיצות כך שתוקפן יפוג אחרי שלושה ימים.

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

   כניסה ל-BigQuery

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

   LOAD DATA INTO mydataset.mytable
   PARTITION BY transaction_date
   CLUSTER BY customer_id
     OPTIONS (
       partition_expiration_days = 3)
   FROM FILES(
     format = 'AVRO',
     uris = ['gs://bucket/path/file.avro']);

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

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

API

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

המשך

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

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

import (
	"context"
	"fmt"

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

// importClusteredTable demonstrates creating a table from a load job and defining partitioning and clustering
// properties.
func importClusteredTable(projectID, destDatasetID, destTableID 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/sample-transactions/transactions.csv")
	gcsRef.SkipLeadingRows = 1
	gcsRef.Schema = bigquery.Schema{
		{Name: "timestamp", Type: bigquery.TimestampFieldType},
		{Name: "origin", Type: bigquery.StringFieldType},
		{Name: "destination", Type: bigquery.StringFieldType},
		{Name: "amount", Type: bigquery.NumericFieldType},
	}
	loader := client.Dataset(destDatasetID).Table(destTableID).LoaderFrom(gcsRef)
	loader.TimePartitioning = &bigquery.TimePartitioning{
		Field: "timestamp",
	}
	loader.Clustering = &bigquery.Clustering{
		Fields: []string{"origin", "destination"},
	}
	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
}

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.Clustering;
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;
import com.google.cloud.bigquery.TimePartitioning;
import com.google.common.collect.ImmutableList;

public class LoadTableClustered {

  public static void runLoadTableClustered() 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";
    loadTableClustered(datasetName, tableName, sourceUri);
  }

  public static void loadTableClustered(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);

      Schema schema =
          Schema.of(
              Field.of("name", StandardSQLTypeName.STRING),
              Field.of("post_abbr", StandardSQLTypeName.STRING),
              Field.of("date", StandardSQLTypeName.DATE));

      TimePartitioning partitioning = TimePartitioning.of(TimePartitioning.Type.DAY);

      Clustering clustering =
          Clustering.newBuilder().setFields(ImmutableList.of("name", "post_abbr")).build();

      LoadJobConfiguration loadJobConfig =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.csv())
              .setSchema(schema)
              .setTimePartitioning(partitioning)
              .setClustering(clustering)
              .build();

      Job loadJob = bigquery.create(JobInfo.newBuilder(loadJobConfig).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("Data successfully loaded into clustered table during load job");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Data not loaded into clustered table during load 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 table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    skip_leading_rows=1,
    source_format=bigquery.SourceFormat.CSV,
    schema=[
        bigquery.SchemaField("timestamp", bigquery.SqlTypeNames.TIMESTAMP),
        bigquery.SchemaField("origin", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("destination", bigquery.SqlTypeNames.STRING),
        bigquery.SchemaField("amount", bigquery.SqlTypeNames.NUMERIC),
    ],
    time_partitioning=bigquery.TimePartitioning(field="timestamp"),
    clustering_fields=["origin", "destination"],
)

job = client.load_table_from_uri(
    ["gs://cloud-samples-data/bigquery/sample-transactions/transactions.csv"],
    table_id,
    job_config=job_config,
)

job.result()  # Waits for the job to complete.

table = client.get_table(table_id)  # Make an API request.
print(
    "Loaded {} rows and {} columns to {}".format(
        table.num_rows, len(table.schema), table_id
    )
)

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

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