Create clustered tables

You can reduce the amount of data processed by a query by using clustered tables in BigQuery.

With clustered tables, table data is organized based on the values of specified columns, also called the clustering columns . BigQuery sorts the data by the clustered columns, then stores the rows that have similar values in the same or nearby physical blocks. When a query filters on a clustered column, BigQuery efficiently scans only the relevant blocks and skips the data that doesn't match the filter.

For more information, see the following:

To learn more about clustered tables in BigQuery, see Introduction to clustered tables .
To learn about working with and controlling access to clustered tables, see Manage clustered tables .

Before you begin

Required roles

To get the permissions that you need to create a table, ask your administrator to grant you the following IAM roles:

BigQuery Job User ( roles/bigquery.jobUser ) on the project if you're creating a table by loading data or by saving query results to a table.
BigQuery Data Editor ( roles/bigquery.dataEditor ) on the dataset where you're creating the table.

For more information about granting roles, see Manage access to projects, folders, and organizations .

These predefined roles contain the permissions required to create a table. To see the exact permissions that are required, expand the Required permissionssection:

Required permissions

The following permissions are required to create a table:

bigquery.tables.create on the dataset where you're creating the table.
bigquery.tables.getData on all tables and views that your query references if you're saving query results as a table.
bigquery.jobs.create on the project if you're creating the table by loading data or by saving query results to a table.
bigquery.tables.updateData on the table if you're appending to or overwriting a table with query results.

You might also be able to get these permissions with custom roles or other predefined roles .

Table naming requirements

When you create a table in BigQuery, the table name must be unique per dataset. The table name can:

Contain characters with a total of up to 1,024 UTF-8 bytes.
Contain Unicode characters in category L (letter), M (mark), N (number), Pc (connector, including underscore), Pd (dash), Zs (space). For more information, see General Category .

The following are all examples of valid table names: table 01 , ग्राहक , 00_お客様 , étudiant-01 .

Caveats:

Table names are case-sensitive by default. mytable and MyTable can coexist in the same dataset, unless they are part of a dataset with case-sensitivity turned off .
Some table names and table name prefixes are reserved. If you receive an error saying that your table name or prefix is reserved, then select a different name and try again.
If you include multiple dot operators ( . ) in a sequence, the duplicate operators are implicitly stripped.

For example, this: project_name....dataset_name..table_name

Becomes this: project_name.dataset_name.table_name

Clustered column requirements

You can specify the columns used to create the clustered table when you create a table in BigQuery. After the table is created, you can modify the columns used to create the clustered table. For details, see Modifying the clustering specification .

Clustering columns must be top-level, non-repeated columns, and they must be one of the following data types:

BIGNUMERIC
BOOL
DATE
DATETIME
GEOGRAPHY
INT64
NUMERIC
RANGE
STRING
TIMESTAMP

You can specify up to four clustering columns. When you specify multiple columns, the order of the columns determines how the data is sorted. For example, if the table is clustered by columns a, b and c, the data is sorted in the same order: first by column a, then by column b, and then by column c. As a best practice, place the most frequently filtered or aggregated column first.

The order of your clustering columns also affects query performance and pricing. For more information about query best practices for clustered tables, see Querying clustered tables .

Create an empty clustered table with a schema definition

To create an empty clustered table with a schema definition:

Console

In the Google Cloud console, go to the BigQuery page.

Go to BigQuery
In the Explorer pane, expand your project, and then select a dataset.
In the Dataset info section, click Create table .
In the Create table panel, specify the following details:

In the Source section, select Empty table in the Create table from list.
In the Destination section, specify the following details:
1. For Dataset , select the dataset in which you want to create the table.
2. In the Table field, enter the name of the table that you want to create.
3. Verify that the Table type field is set to Native table .
In the Schema section, enter the schema definition. You can enter schema information manually by using one of the following methods:
- Option 1: Click Edit as text and paste the schema in the form of a JSON array. When you use a JSON array, you generate the schema using the same process as creating a JSON schema file . You can view the schema of an existing table in JSON format by entering the following command:
```
  
 bq  
show 
  
--format = 
prettyjson  
 dataset.table 
  
```
- Option 2: Click Add field and enter the table schema. Specify each field's Name , Type , and Mode .
For Clustering order , enter between one and four comma-separated column names.
Optional: In the Advanced options section, if you want to use a customer-managed encryption key, then select the Use a customer-managed encryption key (CMEK) option. By default, BigQuery encrypts customer content stored at rest by using a Google-owned and Google-managed encryption key.
Click Create table .

SQL

Use the CREATE TABLE DDL statement command with the CLUSTER BY option. The following example creates a clustered table named myclusteredtable in mydataset :

In the Google Cloud console, go to the BigQuerypage.

Go to BigQuery

In the query editor, enter the following statement:

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

Click Run.

For more information about how to run queries, see Run an interactive query .

bq

Use the bq mk command with the following flags:

--table (or the -t shortcut).
--schema . You can supply the table's schema definition inline or use a JSON schema file.
--clustering_fields . You can specify up to four clustering columns.

Optional parameters include --expiration , --description , --time_partitioning_type , --time_partitioning_field , --time_partitioning_expiration , --destination_kms_key , and --label .

If you are creating a table in a project other than your default project, add the project ID to the dataset in the following format: project_id:dataset .

--destination_kms_key is not demonstrated here. For information about using --destination_kms_key , see customer-managed encryption keys .

Enter the following command to create an empty clustered table with a schema definition:

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

Replace the following:

INTEGER1 : the default lifetime, in seconds, for the table. The minimum value is 3,600 seconds (one hour). The expiration time evaluates to the current UTC time plus the integer value. If you set the table's expiration time when you create a table, the dataset's default table expiration setting is ignored. Setting this value deletes the table after the specified time.
SCHEMA : an inline schema definition in the format COLUMN:DATA_TYPE,COLUMN:DATA_TYPE or the path to the JSON schema file on your local machine.
CLUSTER_COLUMNS : a comma-separated list of up to four clustering columns. The list cannot contain any spaces.
DESCRIPTION : a description of the table, in quotes.
KEY:VALUE : the key-value pair that represents a label . You can enter multiple labels using a comma-separated list.
PROJECT_ID : your project ID.
DATASET : a dataset in your project.
TABLE : the name of the table you're creating.

When you specify the schema on the command line, you cannot include a RECORD ( STRUCT ) type, you cannot include a column description, and you cannot specify the column's mode. All modes default to NULLABLE . To include descriptions, modes, and RECORD types, supply a JSON schema file instead.

Examples:

Enter the following command to create a clustered table named myclusteredtable in mydataset in your default project. The table's expiration is set to 2,592,000 (1 30-day month), the description is set to This is my clustered table , and the label is set to organization:development . The command uses the -t shortcut instead of --table .

The schema is specified inline as: timestamp:timestamp,customer_id:string,transaction_amount:float . The specified clustering field customer_id is used to cluster the table.

 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

Enter the following command to create a clustered table named myclusteredtable in myotherproject , not your default project. The description is set to This is my clustered table , and the label is set to organization:development . The command uses the -t shortcut instead of --table . This command does not specify a table expiration. If the dataset has a default table expiration, it is applied. If the dataset has no default table expiration, the table never expires.

The schema is specified in a local JSON file: /tmp/myschema.json . The customer_id field is used to cluster the table.

 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

After the table is created, you can update the table's description and labels .

Terraform

Use the google_bigquery_table resource.

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries .

The following example creates a table named mytable that is clustered on the ID and Created columns:

 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"
  deletion_protection = false # set to "true" in production

  clustering = ["ID", "Created"]

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

}

To apply your Terraform configuration in a Google Cloud project, complete the steps in the following sections.

Prepare Cloud Shell

Launch Cloud Shell .
Set the default Google Cloud project where you want to apply your Terraform configurations.

You only need to run this command once per project, and you can run it in any directory.
```
export GOOGLE_CLOUD_PROJECT= PROJECT_ID 
```
Environment variables are overridden if you set explicit values in the Terraform configuration file.

Prepare the directory

Each Terraform configuration file must have its own directory (also called a root module ).

In Cloud Shell , create a directory and a new file within that directory. The filename must have the .tf extension—for example main.tf . In this tutorial, the file is referred to as main.tf .
```
mkdir DIRECTORY 
&& cd DIRECTORY 
&& touch main.tf
```
If you are following a tutorial, you can copy the sample code in each section or step.

Copy the sample code into the newly created main.tf .

Optionally, copy the code from GitHub. This is recommended when the Terraform snippet is part of an end-to-end solution.
Review and modify the sample parameters to apply to your environment.
Save your changes.
Initialize Terraform. You only need to do this once per directory.
```
terraform init
```
Optionally, to use the latest Google provider version, include the -upgrade option:
```
terraform init -upgrade
```

Apply the changes

Review the configuration and verify that the resources that Terraform is going to create or update match your expectations:
```
terraform plan
```
Make corrections to the configuration as necessary.
Apply the Terraform configuration by running the following command and entering yes at the prompt:
```
terraform apply
```
Wait until Terraform displays the "Apply complete!" message.
Open your Google Cloud project to view the results. In the Google Cloud console, navigate to your resources in the UI to make sure that Terraform has created or updated them.

API

Call the tables.insert method with a defined table resource that specifies the clustering.fields property and the schema property.

Python

Before trying this sample, follow the Python setup instructions in the BigQuery quickstart using client libraries . For more information, see the BigQuery Python API reference documentation .

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries .

  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

Before trying this sample, follow the Go setup instructions in the BigQuery quickstart using client libraries . For more information, see the BigQuery Go API reference documentation .

To authenticate to BigQuery, set up Application Default Credentials. For more information, see Set up authentication for client libraries .

  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 
 }

Create clustered tables

Before you begin

Required roles

Required permissions

Table naming requirements

Clustered column requirements

Create an empty clustered table with a schema definition

Console

SQL

bq

Terraform

Prepare Cloud Shell

Prepare the directory

Apply the changes

API

Python

Go

Java

Create a clustered table from a query result

SQL

bq

API

Create a clustered table when you load data

SQL

API

Go

Java

Python

What's next