יצירת טבלאות מחולקות למחיצות

המסוף

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

   כניסה לדף BigQuery

2. בחלונית הימנית, לוחצים על explore כלי הניתוחים.
3. בחלונית Explorer, מרחיבים את הפרויקט, לוחצים על Datasets ובוחרים מערך נתונים.
4. בקטע פרטי מערך הנתונים, לוחצים על add_box יצירת טבלה.
5. בחלונית Create table, מציינים את הפרטים הבאים:
1. בקטע מקור, בוחרים באפשרות טבלה ריקה ברשימה יצירת טבלה מ.
2. בקטע יעד, מציינים את הפרטים הבאים:
   1. בקטע Dataset (מערך נתונים), בוחרים את מערך הנתונים שבו רוצים ליצור את הטבלה.
   2. בשדה Table, מזינים את השם של הטבלה שרוצים ליצור.
   3. מוודאים שהשדה Table type (סוג הטבלה) מוגדר ל-Native table (טבלה מקורית).
3. בקטע Schema (סכימה), מזינים את הגדרת הסכימה. הסכימה צריכה לכלול עמודה של DATE, TIMESTAMP או DATETIME עבור עמודת החלוקה למחיצות. מידע נוסף זמין במאמר בנושא ציון סכימה. אפשר להזין את פרטי הסכימה באופן ידני באחת מהשיטות הבאות:
   • אפשרות 1: לוחצים על Edit as text (עריכה כטקסט) ומדביקים את הסכימה כ-JSON array. כשמשתמשים במערך JSON, יוצרים את הסכימה באותו תהליך שבו יוצרים קובץ סכימת JSON. כדי לראות את הסכימה של טבלה קיימת בפורמט JSON, מזינים את הפקודה הבאה:

         bq show --format=prettyjson dataset.table
         

   • אפשרות 2: לוחצים על add_box הוספת שדה ומזינים את סכימת הטבלה. מציינים את השם, הסוג, והמצב של כל שדה.
4. בקטע Partition and cluster settings, ברשימה Partitioning, בוחרים באפשרות Partition by field ואז בוחרים את עמודת החלוקה למחיצות. האפשרות הזו זמינה רק אם הסכימה מכילה עמודה של DATE, TIMESTAMP או DATETIME.
5. אופציונלי: כדי לדרוש מסנן מחיצה בכל השאילתות של הטבלה הזו, מסמנים את תיבת הסימון דרישת מסנן מחיצה. מסנן של מחיצה יכול להקטין את העלות ולשפר את הביצועים. מידע נוסף מופיע במאמר בנושא הגדרת דרישות לסינון מחיצות.
6. בוחרים את סוג החלוקה.
7. אופציונלי: בקטע Advanced options, אם רוצים להשתמש במפתח הצפנה בניהול הלקוח, בוחרים באפשרות Use a customer-managed encryption key (CMEK). כברירת מחדל, BigQuery מצפין את תוכן הלקוחות שמאוחסן במצב מנוחה באמצעות Google Cloud-powered encryption key.
8. לוחצים על יצירת טבלה.

SQL

כדי ליצור טבלה עם חלוקה למחיצות לפי יחידת זמן, משתמשים בCREATE TABLE הצהרת DDL עם פסוקית PARTITION BY.

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

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

   כניסה ל-BigQuery

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

   CREATE TABLE
     mydataset.newtable (transaction_id INT64, transaction_date DATE)
   PARTITION BY
     transaction_date
     OPTIONS (
       partition_expiration_days = 3,
       require_partition_filter = TRUE);

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

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

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

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

CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_date DATE)
PARTITION BY
  DATE_TRUNC(transaction_date, MONTH)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

אפשר גם לציין עמודה מסוג TIMESTAMP או DATETIME כעמודת החלוקה. במקרה כזה, צריך לכלול את הפונקציה TIMESTAMP_TRUNC או DATETIME_TRUNC בסעיף PARTITION BY כדי לציין את סוג המחיצה. לדוגמה, ההצהרה הבאה יוצרת טבלה עם מחיצות יומיות שמבוססות על עמודה TIMESTAMP:

CREATE TABLE
  mydataset.newtable (transaction_id INT64, transaction_ts TIMESTAMP)
PARTITION BY
  TIMESTAMP_TRUNC(transaction_ts, DAY)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

BQ

1. במסוף Cloud de Confiance , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Cloud de Confiance המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. משתמשים בפקודה bq mk עם הדגל --table (או במקש הקיצור -t):

   bq mk \
      --table \
      --schema SCHEMA \
      --time_partitioning_field COLUMN \
      --time_partitioning_type UNIT_TIME \
      --time_partitioning_expiration EXPIRATION_TIME \
      --require_partition_filter=BOOLEAN
      PROJECT_ID:DATASET.TABLE

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

   • ‫SCHEMA: הגדרת סכימה בפורמט column:data_type,column:data_type או הנתיב לקובץ סכימת JSON במחשב המקומי. מידע נוסף זמין במאמר בנושא ציון סכימה.
   • ‫COLUMN: השם של עמודת החלוקה למחיצות. בסכימת הטבלה, העמודה הזו חייבת להיות מסוג TIMESTAMP, DATETIME או DATE.
   • ‫UNIT_TIME: סוג החלוקה למחיצות. הערכים הנתמכים כוללים DAY,‏ HOUR,‏ MONTH או YEAR.
   • ‫EXPIRATION_TIME: זמן התפוגה של המחיצות בטבלה, בשניות. הדגל --time_partitioning_expiration הוא אופציונלי. מידע נוסף זמין במאמר בנושא הגדרת תאריך התפוגה של המחיצה.
   • ‫BOOLEAN: אם true, השאילתות בטבלה הזו חייבות לכלול מסנן מחיצות. הדגל --require_partition_filter הוא אופציונלי. מידע נוסף מופיע במאמר בנושא הגדרת דרישות לסינון מחיצות.
   • ‫PROJECT_ID: מזהה הפרויקט. אם לא מציינים פרויקט, המערכת משתמשת בפרויקט ברירת המחדל.
   • ‫DATASET: השם של מערך נתונים בפרויקט.
   • ‫TABLE: השם של הטבלה שרוצים ליצור.

   אפשרויות נוספות בשורת הפקודה מופיעות במאמר בנושא bq mk.

   בדוגמה הבאה נוצרת טבלה בשם mytable שמחולקת למחיצות לפי העמודה ts, באמצעות חלוקה למחיצות לפי שעה. תוקף המחיצה הוא 259,200 שניות (3 ימים).

   bq mk \
      -t \
      --schema 'ts:TIMESTAMP,qtr:STRING,sales:FLOAT' \
      --time_partitioning_field ts \
      --time_partitioning_type HOUR \
      --time_partitioning_expiration 259200  \
      mydataset.mytable

Terraform

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

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

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

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"

  time_partitioning {
    type          = "DAY"
    field         = "Created"
    expiration_ms = 432000000 # 5 days
  }
  require_partition_filter = true

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

}

כדי להחיל את הגדרות Terraform בפרויקט ב- Cloud de Confiance , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

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

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

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

   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. פותחים את Cloud de Confiance הפרויקט כדי לראות את התוצאות. במסוף Cloud de Confiance , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

API

קוראים לשיטה tables.insert עם משאב טבלה מוגדר שמציין את המאפיין timePartitioning ואת המאפיין schema.

המשך

import (
	"context"
	"fmt"
	"time"

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

// createTablePartitioned demonstrates creating a table and specifying a time partitioning configuration.
func createTablePartitioned(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: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.IntegerFieldType},
		{Name: "date", Type: bigquery.DateFieldType},
	}
	metadata := &bigquery.TableMetadata{
		TimePartitioning: &bigquery.TimePartitioning{
			Field:      "date",
			Expiration: 90 * 24 * time.Hour,
		},
		Schema: sampleSchema,
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metadata); err != nil {
		return err
	}
	return nil
}

Java

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

// Sample to create a partition table
public class CreatePartitionedTable {

  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";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING),
            Field.of("date", StandardSQLTypeName.DATE));
    createPartitionedTable(datasetName, tableName, schema);
  }

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

      TableId tableId = TableId.of(datasetName, tableName);

      TimePartitioning partitioning =
          TimePartitioning.newBuilder(TimePartitioning.Type.DAY)
              .setField("date") //  name of column to use for partitioning
              .setExpirationMs(7776000000L) // 90 days
              .build();

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

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

Node.js

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

async function createTablePartitioned() {
  // Creates a new partitioned table named "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  const schema = 'Name:string, Post_Abbr:string, Date:date';

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    location: 'US',
    timePartitioning: {
      type: 'DAY',
      expirationMS: '7776000000',
      field: 'date',
    },
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);
  console.log(`Table ${table.id} created with partitioning: `);
  console.log(table.metadata.timePartitioning);
}

Python

from google.cloud import bigquery

client = bigquery.Client()

# Use format "your-project.your_dataset.your_table_name" for table_id
table_id = your_fully_qualified_table_id
schema = [
    bigquery.SchemaField("name", "STRING"),
    bigquery.SchemaField("post_abbr", "STRING"),
    bigquery.SchemaField("date", "DATE"),
]
table = bigquery.Table(table_id, schema=schema)
table.time_partitioning = bigquery.TimePartitioning(
    type_=bigquery.TimePartitioningType.DAY,
    field="date",  # name of column to use for partitioning
    expiration_ms=1000 * 60 * 60 * 24 * 90,
)  # 90 days

table = client.create_table(table)

print(
    f"Created table {table.project}.{table.dataset_id}.{table.table_id}, "
    f"partitioned on column {table.time_partitioning.field}."
)

המסוף

1. פותחים את הדף BigQuery במסוף Cloud de Confiance .

   לדף BigQuery

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

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

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

5. בדף Create table, בקטע Source, בוחרים באפשרות Empty table.

6. בקטע יעד:

   • בשדה Dataset name (שם קבוצת הנתונים), בוחרים את קבוצת הנתונים המתאימה.
   • בשדה Table name (שם הטבלה), מזינים את שם הטבלה.
   • מוודאים שההגדרה של Table type היא Native table.

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

8. בקטע Partition and cluster settings (הגדרות של מחיצות ושל אשכולות), לוחצים על Partition by ingestion time (חלוקה למחיצות לפי זמן ההטמעה) באפשרות Partitioning (חלוקה למחיצות).

9. (אופציונלי) כדי לדרוש מסנן מחיצה בכל השאילתות של הטבלה הזו, מסמנים את תיבת הסימון Require partition filter (דרישת מסנן מחיצה). הוספת דרישה למסנן מחיצות יכולה להקטין את העלות ולשפר את הביצועים. מידע נוסף מופיע במאמר בנושא הגדרת דרישות לסינון מחיצות.

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

SQL

כדי ליצור טבלה מחולקת למחיצות (partitioning) לפי זמני כתיבת הנתונים, משתמשים בהצהרת CREATE TABLE עם פסוקית PARTITION BY שמחלקת למחיצות לפי _PARTITIONDATE.

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

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

   כניסה ל-BigQuery

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

   CREATE TABLE
     mydataset.newtable (transaction_id INT64)
   PARTITION BY
     _PARTITIONDATE
     OPTIONS (
       partition_expiration_days = 3,
       require_partition_filter = TRUE);

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

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

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

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

CREATE TABLE
  mydataset.newtable (transaction_id INT64)
PARTITION BY
  DATE_TRUNC(_PARTITIONTIME, MONTH)
  OPTIONS (
    partition_expiration_days = 3,
    require_partition_filter = TRUE);

BQ

1. במסוף Cloud de Confiance , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Cloud de Confiance המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. משתמשים בפקודה bq mk עם הדגל --table (או במקש הקיצור -t):

   bq mk \
      --table \
      --schema SCHEMA \
      --time_partitioning_type UNIT_TIME \
      --time_partitioning_expiration EXPIRATION_TIME \
      --require_partition_filter=BOOLEAN  \
      PROJECT_ID:DATASET.TABLE

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

   • ‫SCHEMA: הגדרה בפורמט column:data_type,column:data_type או הנתיב לקובץ סכימת JSON במחשב המקומי. מידע נוסף זמין במאמר בנושא ציון סכימה.
   • ‫UNIT_TIME: סוג החלוקה למחיצות. הערכים הנתמכים כוללים DAY,‏ HOUR,‏ MONTH או YEAR.
   • ‫EXPIRATION_TIME: זמן התפוגה של המחיצות בטבלה, בשניות. הדגל --time_partitioning_expiration הוא אופציונלי. מידע נוסף זמין במאמר בנושא הגדרת תאריך התפוגה של המחיצה.
   • ‫BOOLEAN: אם true, השאילתות בטבלה הזו חייבות לכלול מסנן מחיצות. הדגל --require_partition_filter הוא אופציונלי. מידע נוסף מופיע במאמר בנושא הגדרת דרישות לסינון מחיצות.
   • ‫PROJECT_ID: מזהה הפרויקט. אם לא מציינים פרויקט, המערכת משתמשת בפרויקט ברירת המחדל.
   • ‫DATASET: השם של מערך נתונים בפרויקט.
   • ‫TABLE: השם של הטבלה שרוצים ליצור.

   אפשרויות נוספות בשורת הפקודה מופיעות במאמר בנושא bq mk.

   בדוגמה הבאה נוצרת טבלה מחולקת למחיצות (Partitions) לפי זמני כתיבת הנתונים בשם mytable. הטבלה מחולקת למחיצות יומיות, ותוקף המחיצה הוא 259,200 שניות (3 ימים).

   bq mk \
      -t \
      --schema qtr:STRING,sales:FLOAT,year:STRING \
      --time_partitioning_type DAY \
      --time_partitioning_expiration 259200 \
      mydataset.mytable

Terraform

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

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

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

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"

  time_partitioning {
    type          = "MONTH"
    expiration_ms = 604800000 # 7 days
  }
  require_partition_filter = true

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

}

כדי להחיל את הגדרות Terraform בפרויקט ב- Cloud de Confiance , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

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

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

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

   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. פותחים את Cloud de Confiance הפרויקט כדי לראות את התוצאות. במסוף Cloud de Confiance , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

API

קוראים לשיטה tables.insert עם משאב טבלה מוגדר שמציין את המאפיין timePartitioning ואת המאפיין schema.

המסוף

1. פותחים את הדף BigQuery במסוף Cloud de Confiance .

   לדף BigQuery

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

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

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

5. בדף Create table, בקטע Source, בוחרים באפשרות Empty table.

6. בקטע יעד:

   • בשדה Dataset name (שם קבוצת הנתונים), בוחרים את קבוצת הנתונים המתאימה.
   • בשדה Table name (שם הטבלה), מזינים את שם הטבלה.
   • מוודאים שההגדרה של Table type היא Native table.

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

8. בקטע Partition and cluster settings, ברשימה הנפתחת Partitioning, בוחרים באפשרות Partition by field ובוחרים את עמודת החלוקה למחיצות. האפשרות הזו זמינה רק אם הסכימה מכילה עמודה INTEGER.

9. מזינים ערכים עבור התחלה, סיום ומרווח:

   • ‫Start הוא תחילת הטווח של המחיצה הראשונה (כולל).
   • ‫End הוא סוף הטווח של המחיצה האחרונה (לא כולל).
   • מרווח הוא הרוחב של כל טווח מחיצות.

   ערכים מחוץ לטווחים האלה נכנסים למחיצה מיוחדת __UNPARTITIONED__.

10. (אופציונלי) כדי לדרוש מסנן מחיצה בכל השאילתות של הטבלה הזו, מסמנים את תיבת הסימון Require partition filter (דרישת מסנן מחיצה). הוספת דרישה למסנן מחיצות יכולה להקטין את העלות ולשפר את הביצועים. מידע נוסף מופיע במאמר בנושא הגדרת דרישות לסינון מחיצות.

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

SQL

כדי ליצור טבלה מחולקת למחיצות (Partitions) עם טווח של מספרים שלמים, משתמשים בהצהרת DDL‏ CREATE TABLE עם סעיף PARTITION BY.

בדוגמה הבאה נוצרת טבלה שמחולקת למחיצות בעמודה customer_id עם התחלה 0, סיום 100 ומרווח 10:

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

   כניסה ל-BigQuery

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

   CREATE TABLE mydataset.newtable (customer_id INT64, date1 DATE)
   PARTITION BY
     RANGE_BUCKET(customer_id, GENERATE_ARRAY(0, 100, 10))
     OPTIONS (
       require_partition_filter = TRUE);

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

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

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

BQ

1. במסוף Cloud de Confiance , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Cloud de Confiance המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. משתמשים בפקודה bq mk עם הדגל --table (או במקש הקיצור -t):

   bq mk \
      --schema schema \
      --range_partitioning=COLUMN_NAME,START,END,INTERVAL \
      --require_partition_filter=BOOLEAN  \
      PROJECT_ID:DATASET.TABLE

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

   • ‫SCHEMA: הגדרה מוטבעת של סכימה בפורמט column:data_type,column:data_type או הנתיב לקובץ סכימת JSON במחשב המקומי. מידע נוסף זמין במאמר בנושא ציון סכימה.
   • ‫COLUMN_NAME: השם של עמודת החלוקה למחיצות. בסכימת הטבלה, העמודה הזו חייבת להיות מסוג INTEGER.
   • ‫START: תחילת הטווח של המחיצה הראשונה (כולל).
   • ‫END: סוף הטווח של המחיצה האחרונה (לא כולל).
   • ‫INTERVAL: הרוחב של כל טווח מחיצות.
   • ‫BOOLEAN: אם true, השאילתות בטבלה הזו חייבות לכלול מסנן מחיצות. הדגל --require_partition_filter הוא אופציונלי. מידע נוסף מופיע במאמר בנושא הגדרת דרישות לסינון מחיצות.
   • ‫PROJECT_ID: מזהה הפרויקט. אם לא מציינים פרויקט, המערכת משתמשת בפרויקט ברירת המחדל.
   • ‫DATASET: השם של מערך נתונים בפרויקט.
   • ‫TABLE: השם של הטבלה שרוצים ליצור.

   ערכים מחוץ לטווח המחיצה נכנסים למחיצה מיוחדת __UNPARTITIONED__

   אפשרויות נוספות בשורת הפקודה מופיעות במאמר בנושא bq mk.

   בדוגמה הבאה נוצרת טבלה בשם mytable שמחולקת למחיצות בעמודה customer_id.

   bq mk \
      -t \
      --schema 'customer_id:INTEGER,qtr:STRING,sales:FLOAT' \
      --range_partitioning=customer_id,0,100,10 \
      mydataset.mytable

Terraform

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

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

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

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"

  range_partitioning {
    field = "ID"
    range {
      start    = 0
      end      = 1000
      interval = 10
    }
  }
  require_partition_filter = true

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

}

כדי להחיל את הגדרות Terraform בפרויקט ב- Cloud de Confiance , מבצעים את השלבים בקטעים הבאים.

הכנת Cloud Shell

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

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

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

   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. פותחים את Cloud de Confiance הפרויקט כדי לראות את התוצאות. במסוף Cloud de Confiance , נכנסים למשאבים בממשק המשתמש כדי לוודא שהם נוצרו או עודכנו ב-Terraform.

API

קוראים למתודה tables.insert עם משאב טבלה מוגדר שמציין את המאפיין rangePartitioning ואת המאפיין schema.

Java

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.RangePartitioning;
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;

// Sample to create a range partitioned table
public class CreateRangePartitionedTable {

  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";
    Schema schema =
        Schema.of(
            Field.of("integerField", StandardSQLTypeName.INT64),
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL),
            Field.of("dateField", StandardSQLTypeName.DATE));
    createRangePartitionedTable(datasetName, tableName, schema);
  }

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

      TableId tableId = TableId.of(datasetName, tableName);

      // Note: The field must be a top- level, NULLABLE/REQUIRED field.
      // The only supported type is INTEGER/INT64
      RangePartitioning partitioning =
          RangePartitioning.newBuilder()
              .setField("integerField")
              .setRange(
                  RangePartitioning.Range.newBuilder()
                      .setStart(1L)
                      .setInterval(2L)
                      .setEnd(10L)
                      .build())
              .build();

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

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

Node.js

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

async function createTableRangePartitioned() {
  // Creates a new integer range partitioned table named "my_table"
  // in "my_dataset".

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

  const schema = [
    {name: 'fullName', type: 'STRING'},
    {name: 'city', type: 'STRING'},
    {name: 'zipcode', type: 'INTEGER'},
  ];

  // To use integer range partitioning, select a top-level REQUIRED or
  // NULLABLE column with INTEGER / INT64 data type. Values that are
  // outside of the range of the table will go into the UNPARTITIONED
  // partition. Null values will be in the NULL partition.
  const rangePartition = {
    field: 'zipcode',
    range: {
      start: 0,
      end: 100000,
      interval: 10,
    },
  };

  // For all options, see https://cloud.google.com/bigquery/docs/reference/v2/tables#resource
  const options = {
    schema: schema,
    rangePartitioning: rangePartition,
  };

  // Create a new table in the dataset
  const [table] = await bigquery
    .dataset(datasetId)
    .createTable(tableId, options);

  console.log(`Table ${table.id} created with integer range partitioning: `);
  console.log(table.metadata.rangePartitioning);
}

Python

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.range_partitioning = bigquery.RangePartitioning(
    # To use integer range partitioning, select a top-level REQUIRED /
    # NULLABLE column with INTEGER / INT64 data type.
    field="zipcode",
    range_=bigquery.PartitionRange(start=0, end=100000, interval=10),
)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

SQL

משתמשים בהצהרה CREATE TABLE. כוללים סעיף PARTITION BY כדי להגדיר את החלוקה למחיצות.

בדוגמה הבאה נוצרת טבלה עם חלוקה למחיצות בעמודה transaction_date:

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

   כניסה ל-BigQuery

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

   CREATE TABLE
     mydataset.newtable (transaction_id INT64, transaction_date DATE)
   PARTITION BY
     transaction_date
   AS (
     SELECT
       transaction_id, transaction_date
     FROM
       mydataset.mytable
   );

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

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

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

BQ

1. במסוף Cloud de Confiance , מפעילים את Cloud Shell.

   הפעלת Cloud Shell

   בחלק התחתון של Cloud de Confiance המסוף יתחיל סשן של Cloud Shell ותופיע הודעה של שורת הפקודה. Cloud Shell היא סביבת מעטפת שבה ה-CLI של Google Cloud מותקן ומוגדרים ערכים לפרויקט הקיים. הסשן יופעל תוך כמה שניות.

2. כדי ליצור טבלה עם מחיצות משאילתה, משתמשים בפקודה bq query עם הדגל --destination_table והדגל --time_partitioning_type.

   חלוקת מחיצות לפי עמודה של יחידת זמן:

   bq query \
      --use_legacy_sql=false \
      --destination_table TABLE_NAME \
      --time_partitioning_field COLUMN \
      --time_partitioning_type UNIT_TIME \
      'QUERY_STATEMENT'

   חלוקה למחיצות (partitioning) לפי זמני כתיבת הנתונים:

   bq query \
      --use_legacy_sql=false \
      --destination_table TABLE_NAME \
      --time_partitioning_type UNIT_TIME \
      'QUERY_STATEMENT'

   חלוקה למחיצות של טווח מספרים שלמים:

   bq query \
      --use_legacy_sql=false \
      --destination_table PROJECT_ID:DATASET.TABLE \
      --range_partitioning COLUMN,START,END,INTERVAL \
      'QUERY_STATEMENT'

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

   • ‫PROJECT_ID: מזהה הפרויקט. אם לא מציינים פרויקט, המערכת משתמשת בפרויקט ברירת המחדל.
   • ‫DATASET: השם של מערך נתונים בפרויקט.
   • ‫TABLE: השם של הטבלה שרוצים ליצור.
   • ‫COLUMN: השם של עמודת החלוקה למחיצות.
   • ‫UNIT_TIME: סוג החלוקה למחיצות. הערכים הנתמכים כוללים את DAY,‏ HOUR,‏ MONTH או YEAR.
   • ‫START: תחילת חלוקת הטווח, כולל.
   • ‫END: סוף חלוקת הטווח, לא כולל.
   • ‫INTERVAL: הרוחב של כל טווח במחיצה.
   • ‫QUERY_STATEMENT: השאילתה שמשמשת לאכלוס הטבלה.

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

   bq query \
      --use_legacy_sql=false \
      --destination_table mydataset.newtable \
      --time_partitioning_field transaction_date \
      --time_partitioning_type MONTH \
      'SELECT transaction_id, transaction_date FROM mydataset.mytable'

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

   bq query \
      --use_legacy_sql=false \
      --destination_table mydataset.newtable \
      --range_partitioning customer_id,0,100,10 \
      'SELECT * FROM mydataset.ponies'

   בטבלאות עם חלוקה למחיצות בזמן ההטמעה, אפשר גם לטעון נתונים למחיצה ספציפית באמצעות קישוט מחיצה. בדוגמה הבאה נוצרת טבלה חדשה שמחולקת למחיצות לפי זמני כתיבת הנתונים, ונטענים נתונים למחיצה 20180201 (1 בפברואר 2018):

   bq query \
      --use_legacy_sql=false  \
      --time_partitioning_type=DAY \
      --destination_table='newtable$20180201' \
      'SELECT * FROM mydataset.mytable'

API

כדי לשמור את תוצאות השאילתה בטבלה עם חלוקה למחיצות, מפעילים את השיטה jobs.insert. מגדירים משימת query. מציינים את טבלת היעד ב-destinationTable. מציינים את החלוקה למחיצות במאפיין timePartitioning או במאפיין rangePartitioning.