Manage datasets (original) (raw)

Stay organized with collections Save and categorize content based on your preferences.

This document describes how to copy datasets, recreate datasets in another location, secure datasets, delete datasets, and restore tables from deleted datasets in BigQuery. For information about how to restore (or undelete) a deleted dataset, seeRestore deleted datasets.

As a BigQuery administrator, you can organize and control access to tables and views that analysts use. For more information about datasets, see Introduction to datasets.

You cannot change the name of an existing dataset or relocate a dataset after it's created. As a workaround for changing the dataset name, you can copy a datasetand change the destination dataset's name. To relocate a dataset, you can follow one of the following methods:

Required roles

This section describes the roles and permissions that you need to manage datasets. If your source or destination dataset is in the same project as the one you are using to copy, then you don't need extra permissions or roles on that dataset.

To get the permissions that you need to manage datasets, ask your administrator to grant you the following IAM roles:

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

These predefined roles contain the permissions required to manage datasets. To see the exact permissions that are required, expand the Required permissions section:

Required permissions

The following permissions are required to manage datasets:

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

For more information about IAM roles and permissions in BigQuery, seeIntroduction to IAM.

Copy datasets

You can copy a dataset, including partitioned data within a region or across regions, without extracting, moving, or reloading data into BigQuery. BigQuery uses the BigQuery Data Transfer Servicein the backend to copy datasets. For location considerations when you transfer data, see Data location and transfers.

For each dataset copy configuration, you can have one transfer run active at a time. Additional transfer runs are queued. If you are using the Google Cloud console, you can schedule recurring copies, and configure an email or Pub/Sub notifications with the BigQuery Data Transfer Service.

Limitations

The following limitations apply when you copy datasets:

Copy a dataset

Select one of the following options:

Console

  1. Enable the BigQuery Data Transfer Servicefor your destination dataset.
    Enable the BigQuery Data Transfer Service API
  2. Ensure that you have the required roles.
    If you intend to set up transfer run notifications for Pub/Sub (Option 2 later in these steps), then you must have the pubsub.topics.setIamPolicypermission.
    If you only set up email notifications, then Pub/Sub permissions are not required. For more information, see the BigQuery Data Transfer Servicerun notifications.
  3. Create a BigQuery datasetin the same region or a different region from your source dataset.

Option 1: Use the BigQuery copy function

To create a one-time transfer, use the BigQuery copy function:

  1. Go to the BigQuery page.
    Go to BigQuery
  2. In the Explorer panel, expand your project and select a dataset.
  3. In the Dataset info section, click Copy, and then do the following:
    1. In the Dataset field, either create a new dataset or select an existing dataset ID from the list.
      Dataset names within a project must be unique. The project and dataset can be in different regions, but not all regions are supported for cross-region dataset copying.
      In the Location field, the location of the source dataset is displayed.
    2. Optional: To overwrite both the data and schema of the destination tables with the source tables, select the Overwrite destination tablescheckbox. Both the source and destination tables must have the same partitioning schema.
    3. To copy the dataset, click Copy.

Option 2: Use the BigQuery Data Transfer Service

To schedule recurring copies and configure email or Pub/Sub notifications, use the BigQuery Data Transfer Service in the Google Cloud console of the destination project:

  1. Go to the Data transfers page.
    Go to Data transfers
  2. Click Create a transfer.
  3. In the Source list, select Dataset Copy.
  4. In the Display name field, enter a name for your transfer run.
  5. In the Schedule options section, do the following:
    1. For Repeat frequency, choose an option for how often to run the transfer:
      If you select Custom, enter a custom frequency—for example,every day 00:00. For more information, see Formatting the schedule.
    2. For Start date and run time, enter the date and time to start the transfer. If you choose Start now, this option is disabled.
  6. In the Destination settings section, select a destination dataset to store your transfer data. You can also click CREATE NEW DATASET to create a new dataset before you select it for this transfer.
  7. In the Data source details section, enter the following information:
    1. For Source dataset, enter the dataset ID that you want to copy.
    2. For Source project, enter the project ID of your source dataset.
  8. To overwrite both the data and schema of the destination tables with the source tables, select the Overwrite destination tables checkbox. Both the source and destination tables must have the same partitioning schema.
  9. In the Service Account menu, select a service accountfrom the service accounts associated with your Google Cloud project. You can associate a service account with your transfer instead of using your user credentials. For more information about using service accounts with data transfers, seeUse service accounts.
    • If you signed in with a federated identity, then a service account is required to create a transfer. If you signed in with a Google Account, then a service account for the transfer is optional.
    • The service account must have the required roles.
  10. Optional: In the Notification options section, do the following:
  1. Click Save.

bq

  1. Enable the BigQuery Data Transfer Servicefor your destination dataset.
  2. Ensure that you have the required roles.
  3. To create a BigQuery dataset, use the bq mk commandwith the dataset creation flag --dataset and the location flag:
    bq mk \
    --dataset \
    --location=LOCATION \
    PROJECT:DATASET
    Replace the following:
    • LOCATION: the location where you want to copy the dataset
    • PROJECT: the project ID of your target dataset
    • DATASET: the name of the target dataset
  4. To copy a dataset, use the bq mk command with the transfer creation flag--transfer_configand the --data_source flag. You must set the --data_source flag to cross_region_copy. For a complete list of valid values for the --data_source flag, see the transfer-config flagsin the bq command-line tool reference.
    bq mk \
    --transfer_config \
    --project_id=PROJECT \
    --data_source=cross_region_copy \
    --target_dataset=DATASET \
    --display_name=NAME \
    --service_account_name=SERCICE_ACCOUNT \
    --params='PARAMETERS'
    Replace the following:
    • NAME: the display name for the copy job or the transfer configuration
    • SERVICE_ACCOUNT: the service account name used to authenticate your transfer. The service account should be owned by the same project_id used to create the transfer and it should have all of the required permissions.
    • PARAMETERS: the parameters for the transfer configuration in the JSON format
      Parameters for a dataset copy configuration include the following:
      * source_dataset_id: the ID of the source dataset that you want to copy
      * source_project_id: the ID of the project that your source dataset is in
      * overwrite_destination_table: an optional flag that lets you truncate the tables of a previous copy and refresh all the data

    Both the source and destination tables must have the same partitioning schema.
    The following examples show the formatting of the parameters, based on your system's environment:

    • Linux: use single quotes to enclose the JSON string–for example:
      '{"source_dataset_id":"mydataset","source_project_id":"mysourceproject","overwrite_destination_table":"true"}'
    • Windows command line: use double quotes to enclose the JSON string, and escape double quotes in the string with a backslash–for example:
      "{"source_dataset_id":"mydataset","source_project_id":"mysourceproject","overwrite_destination_table":"true"}"
    • PowerShell: use single quotes to enclose the JSON string, and escape double quotes in the string with a backslash–for example:
      '{"source_dataset_id":"mydataset","source_project_id":"mysourceproject","overwrite_destination_table":"true"}'
      For example, the following command creates a dataset copy configuration that's named My Transfer with a target dataset that's named mydatasetand a project with the ID of myproject.
      bq mk \
      --transfer_config \
      --project_id=myproject \
      --data_source=cross_region_copy \
      --target_dataset=mydataset \
      --display_name='My Transfer' \
      --params='{
      "source_dataset_id":"123_demo_eu",
      "source_project_id":"mysourceproject",
      "overwrite_destination_table":"true"
      }'

API

  1. Enable the BigQuery Data Transfer Servicefor your destination dataset.
  2. Ensure that you have the required roles.
  3. To create a BigQuery dataset, call the datasets.insertmethod with a defined dataset resource.
  4. To copy a dataset, use the projects.locations.transferConfigs.create method and supply an instance of the TransferConfig resource.

Java

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

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

Python

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

To avoid additional storage costs, consider deleting the prior dataset.

View dataset copy jobs

To see the status and view details of a dataset copy job in the Google Cloud console, do the following:

  1. In the Google Cloud console, go to the Data transfers page.
    Go to Data transfers
  2. Select a transfer for which you want to view the transfer details, and then do the following:
    1. On the Transfer details page, select a transfer run.
    2. To refresh, click Refresh.

Recreate datasets in another location

To manually move a dataset from one location to another, follow these steps:

  1. Export the data from your BigQuery tables to a Cloud Storage bucket.
    There are no charges for exporting data from BigQuery, but you do incur charges for storing the exported data in Cloud Storage. BigQuery exports are subject to the limits onexport jobs.
  2. Copy or move the data from your export Cloud Storage bucket to a new bucket you created in the destination location. For example, if you are moving your data from the US multi-region to the asia-northeast1 Tokyo region, you would transfer the data to a bucket that you created in Tokyo. For information about transferring Cloud Storage objects, seeCopy, rename, and move objects in the Cloud Storage documentation.
    Transferring data between regions incursnetwork egress charges in Cloud Storage.
  3. Create a new BigQuery dataset in the new location, and then load your data from the Cloud Storage bucket into the new dataset.
    You are not charged for loading the data into BigQuery, but you will incur charges for storing the data in Cloud Storage until you delete the data or the bucket. You are also charged for storing the data in BigQuery after it is loaded. Loading data into BigQuery is subject to theload jobs limits.

You can also use Cloud Composer to move and copy large datasets programmatically.

For more information about using Cloud Storage to store and move large datasets, seeUse Cloud Storage with big data.

Secure datasets

To control access to datasets in BigQuery, seeControlling access to datasets. For information about data encryption, see Encryption at rest.

Delete datasets

When you delete a dataset by using the Google Cloud console, tables and views in the dataset, including their data, are deleted. When you delete a dataset by using the bq command-line tool, you must use the -r flag to delete the tables and views.

To delete a dataset, select one of the following options:

Console

  1. Go to the BigQuery page.
    Go to BigQuery
  2. In the Explorer pane, expand your project and select a dataset.
  3. Expand theActions option and click Delete.
  4. In the Delete dataset dialog, type delete into the field, and then click Delete.

SQL

To delete a dataset, use theDROP SCHEMA DDL statement.

The following example deletes a dataset named mydataset:

  1. In the Google Cloud console, go to the BigQuery page.
    Go to BigQuery
  2. In the query editor, enter the following statement:
    DROP SCHEMA IF EXISTS mydataset;
    By default, this only works to delete an empty dataset. To delete a dataset and all of its contents, use the CASCADEkeyword:
    DROP SCHEMA IF EXISTS mydataset CASCADE;
  3. Click Run.

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

bq

Use the bq rm commandwith the --dataset or -d flag, which is optional. If your dataset contains tables, you must use the -r flag to remove all tables in the dataset. If you use the -r flag, then you can omit the --dataset or -d flag.

After you run the command, the system asks for confirmation. You can use the-f flag to skip the confirmation.

If you are deleting a table in a project other than your default project, add the project ID to the dataset name in the following format:PROJECT_ID:DATASET.

bq rm -r -f -d PROJECT_ID:DATASET

Replace the following:

Examples:

Enter the following command to remove a dataset that's named mydataset and all the tables in it from your default project. The command uses the-d flag.

bq rm -r -d mydataset

When prompted, type y and press enter.

Enter the following command to remove mydataset and all the tables in it from myotherproject. The command does not use the optional -d flag. The -f flag is used to skip confirmation.

bq rm -r -f myotherproject:mydataset

You can use the bq ls command to confirm that the dataset was deleted.

API

Call thedatasets.delete method to delete the dataset and set the deleteContents parameter to true to delete the tables in it.

C#

The following code sample deletes an empty dataset.

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

The following code sample deletes a dataset and all of its contents:

Go

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

Java

The following code sample deletes an empty dataset.

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

The following code sample deletes a dataset and all of its contents:

Node.js

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

PHP

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

Python

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

Ruby

The following code sample deletes an empty dataset.

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

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

Install the Python client for the BigQuery Data Transfer API with pip install google-cloud-bigquery-datatransfer. Then create a transfer configuration to copy the dataset.

The following code sample deletes a dataset and all of its contents:

Restore tables from deleted datasets

You can restore tables from a deleted dataset that are within the dataset'stime travel window. To restore the entire dataset, see Restore deleted datasets.

  1. Create a dataset with the same name and in the same location as the original.
  2. Choose a timestamp from before the original dataset was deleted by using a format of milliseconds since the epoch–for example, 1418864998000.
  3. Copy the originaldataset.table1 table at the time 1418864998000 into the new dataset:
    bq cp originaldataset.table1@1418864998000 mydataset.mytable
    To find the names of the nonempty tables that were in the deleted dataset, query the dataset'sINFORMATION_SCHEMA.TABLE_STORAGE viewwithin the time travel window.

Restore deleted datasets

To learn how to restore (or undelete) a deleted dataset, seeRestore deleted datasets.

Quotas

For information about copy quotas, see Copy jobs. Usage for copy jobs are available in the INFORMATION_SCHEMA. To learn how to query the INFORMATION_SCHEMA.JOBS view, seeJOBS view.

Pricing

For pricing information for copying datasets, see Data replication pricing.

BigQuery sends compressed data for copying across regions so the data that is billed might be less than the actual size of your dataset. For more information, see BigQuery pricing.

What's next