Updating dataset properties

Required permissions

To update dataset properties, you must have OWNER
access at the dataset level, or you must be assigned a project-level IAM role
that includes bigquery.datasets.update permissions. The following predefined,
project-level IAM roles include bigquery.datasets.update permissions:

In addition, because the bigquery.user role has bigquery.datasets.create
permissions, a user assigned to the bigquery.user role can update
any dataset that user creates. When a user assigned to the bigquery.user
role creates a dataset, that user is given OWNER access to the dataset.
OWNER access to a dataset gives the user full control over it.

Updating dataset descriptions

To update a dataset's description, you can use the BigQuery web UI, the bq update
CLI command, or the datasets.patch
API method.

To update a dataset's description:

Web UI

In the navigation pane, select your dataset.

On the Dataset Details page, in the Description section, click
Describe this dataset to open the description box if the dataset has no
description. Otherwise, click the existing description text.

Enter a description in the box or edit the existing description. When you
click away from the box, the text is saved.

CLI

Issue the bq update command with the --description flag. If you are
updating a dataset in a project other than your default project, add the
project ID to the dataset name in the following format:
[PROJECT_ID]:[DATASET].

bq update --description "[DESCRIPTION]" [PROJECT_ID]:[DATASET]

Where:

[DESCRIPTION] is the text that describes the dataset in quotes.

[PROJECT_ID] is your project ID.

[DATASET] is the name of the dataset you're updating.

Examples:

Enter the following command to change the description of mydataset to
"Description of mydataset." mydataset is in your default project.

bq update --description "Description of mydataset" mydataset

Enter the following command to change the description of mydataset to
"Description of mydataset." The dataset is in myotherproject, not your
default project.

Updating default table expiration times

To update a dataset's default table expiration time, use the BigQuery web UI, the
bq update CLI command, or the datasets.patch
API method.

You can set a default table expiration time at the dataset level, or you can set
a table's expiration time when the table is created. If you set the expiration
when the table is created, the dataset's default table expiration is ignored. If
you do not set a default table expiration at the dataset level, and you do not
set a table expiration when the table is created, the table never expires and
you must delete the table manually.

When you update a dataset's default table expiration setting:

If you change the value from Never to a defined expiration time, any tables
that already exist in the dataset will not expire unless the expiration time was
set on the table when it was created.

If you are changing the value for the default table expiration, any tables
that already exist expire according to the original table expiration setting.
Any new tables created in the dataset have the new table expiration setting
applied unless you specify a different table expiration on the table when it is
created.

The value for default table expiration is expressed differently depending
on where the value is set. Use the method that gives you the appropriate
level of granularity:

In the BigQuery web UI, expiration is expressed in days.

In the command-line tool, expiration is expressed in seconds.

In the API, expiration is expressed in milliseconds.

To update the default expiration time for a dataset:

Web UI

To update the default expiration time using the web UI:

In the navigation pane, select your dataset.

On the Dataset Details page, in the Details section, to the right
of Default Table Expiration, click Edit.

In the Update Expiration dialog, for Data expiration, click In
and enter the expiration time in days. The default value is Never.

CLI

To update the default expiration time for newly created tables in a dataset,
enter the bq update command with the --default_table_expiration flag.
If you are updating a dataset in a project other than your default project,
add the project ID to the dataset name in the following format:
[PROJECT_ID]:[DATASET].

bq update --default_table_expiration [INTEGER] [PROJECT_ID]:[DATASET]

Where:

[INTEGER] is the default lifetime (in seconds) for newly-created
tables. The minimum value is 3600 seconds (one hour). The expiration time
evaluates to the current time plus the integer value. Specify 0 to remove
the existing expiration time. Any table created in the dataset is deleted
after [INTEGER] seconds from its creation time. This value is applied if
you do not set a table expiration when the table is
created.

[PROJECT_ID] is your project ID.

[DATASET] is the name of the dataset you're updating.

Examples:

Enter the following command to set the default table expiration for
new tables created in mydataset to two hours (7200 seconds) from the
current time. The dataset is in your default project.

bq update --default_table_expiration 7200 mydataset

Enter the following command to set the default table expiration for
new tables created in mydataset to two hours (7200 seconds) from the
current time. The dataset is in myotherproject, not your default project.

bq update --default_table_expiration 7200 myotherproject:mydataset

API

Call datasets.patch and
use the defaultTableExpirationMs
property to apply your default table expiration in milliseconds. Because the
datasets.update method replaces the entire dataset resource, the
datasets.patch method is preferred.

Updating dataset access controls

The process for updating a dataset's access controls is very similar to the
process for assigning access controls to a dataset. Access controls cannot be
applied during dataset creation using the BigQuery web UI or the command-line tool.
You must create the dataset first and then update the dataset's access controls.
The API allows you to update dataset access controls by calling the
datasets.patch method.

Required permissions

To assign or update dataset access controls, you must have OWNER
access at the dataset level, or you must be assigned a project-level IAM role
that includes bigquery.datasets.update permissions. The following predefined,
project-level IAM roles include bigquery.datasets.update permissions:

In addition, because the bigquery.user role has bigquery.datasets.create
permissions, a user assigned to the bigquery.user role can update
any dataset that user creates. When a user assigned to the bigquery.user
role creates a dataset, that user is given OWNER access to the dataset.
OWNER access to a dataset gives the user full control over it.

Web UI

Click the drop-down arrow to the right of the dataset and choose Share
Dataset.

In the Share Dataset dialog, to modify existing entries:

Remove existing entries by clicking the X icon to the right of the user,
group, or service account.

Change permissions for a user, group, or service account by clicking the
permissions button and choosing an appropriate access level: Is owner
(OWNER), Can edit (WRITER), or Can view (READER). For more
information on dataset-level roles, see
Primitive roles for datasets.

In the Share Dataset dialog, to add new entries:

Click the drop-down to the left of the Add People field and choose
the appropriate option.

Type a value in the text box. For example, if you chose User by e-mail,
type the user's email address.

To the right of the Add People field, click Can view and
choose the appropriate role from the list.

Verify your access controls by clicking the drop-down arrow to the right of
the dataset and choosing Share Dataset. You can confirm the settings in
the Share Dataset dialog.

Command-line

Write the existing dataset information (including access controls) to a JSON
file using the show command. If the dataset is in a project other than your
default project, add the project ID to the dataset name in the following format:
[PROJECT_ID]:[DATASET].

bq show --format=prettyjson [PROJECT_ID]:[DATASET] > [PATH_TO_FILE]

Where:

[PROJECT_ID] is your project ID.

[DATASET] is the name of your dataset.

[PATH_TO_FILE] is the path to the JSON file on your local machine.

Examples:

Enter the following command to write the access controls for
mydataset to a JSON file. mydataset is in your default project.

bq show --format=prettyjson mydataset > /tmp/mydataset.json

Enter the following command to write the access controls for
mydataset to a JSON file. mydataset is in myotherproject.

Make your changes to the "access" section of the JSON file. You can add
or remove any of the specialGroup entries: projectOwners, projectWriters,
projectReaders, and allAuthenticatedUsers. You can also add, remove, or
modify any of the following: userByEmail, groupByEmail, and domain.

For example, the access section of a dataset's JSON file would look like
the following:

When your edits are complete, use the update command and include the
JSON file using the --source flag. If the dataset is in a project other than
your default project, add the project ID to the dataset name in the following
format: [PROJECT_ID]:[DATASET].

Caution: When you apply the JSON file that contains the access controls,
the existing access controls are overwritten.

bq update --source [PATH_TO_FILE] [PROJECT_ID]:[DATASET]

Where:

[PATH_TO_FILE] is the path to the JSON file on your local machine.

[PROJECT_ID] is your project ID.

[DATASET] is the name of your dataset.

Examples:

Enter the following command to update the access controls for
mydataset. mydataset is in your default project.

bq update --source /tmp/mydataset.json mydataset

Enter the following command to update the access controls for
mydataset. mydataset is in myotherproject.

bq update --source /tmp/mydataset.json myotherproject:mydataset

To verify your access control changes, enter the show command again without
writing the information to a file.

bq show --format=prettyjson [DATASET]

or

bq show --format=prettyjson [PROJECT_ID]:[DATASET]

API

Call the datasets.patch and
use the access property to update your access controls. For
more information, see Datasets.

Because the datasets.update method replaces the entire dataset resource,
datasets.patch is the preferred method for updating access controls.

Deleting datasets

You can delete a dataset using the BigQuery web UI, the bq rm CLI command, or the
datasets.delete
API method.

Required permissions

To delete a dataset, you must have OWNER
access at the dataset level, or you must be assigned a project-level IAM role
that includes bigquery.datasets.delete permissions. If the
dataset contains tables, bigquery.tables.delete is also required. The
following predefined, project-level IAM roles include both
bigquery.datasets.delete and bigquery.tables.delete permissions:

In addition, because the bigquery.user role has bigquery.datasets.create
permissions, a user assigned to the bigquery.user role can delete
any dataset that user creates. When a user assigned to the bigquery.user
role creates a dataset, that user is given OWNER access to the dataset.
OWNER access to a dataset gives the user full control over it.

Deleting a dataset

When you delete a dataset using the web UI, tables in the dataset (and the data
they contain) are deleted. When you delete a dataset using the CLI, you must use
the -r flag to delete the dataset's tables.

After you delete a dataset, it cannot be recovered, restored, or undeleted.
Deleting a dataset is permanent.

To delete a dataset:

Web UI

Caution: Deleting a dataset cannot be undone.

Click the down arrow icon
next to your dataset name in the navigation, and then click
Delete dataset.

In the Delete Dataset dialog:

For Dataset ID, enter the name of the dataset to delete.

Click OK.

Note: When you delete a dataset using the web UI, the tables are automatically
removed.

Command-line

Caution: Deleting a dataset cannot be undone.

Use the bq rm command with the (optional) --dataset or -d shortcut flag to
delete a dataset. When you use the CLI to remove a dataset, you must confirm the
command. You can use the -f flag to skip confirmation.

In addition, if the dataset contains tables, you must use the -r flag to
remove all tables in the dataset. 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]

Where:

[PROJECT_ID] is your project ID.

[DATASET] is the name of the dataset you're deleting.

Examples:

Enter the following command to remove mydataset and all the tables in it from
your default project. The command uses the optional -d shortcut.

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 shortcut. The
-f flag is used to skip confirmation.

bq rm -r -f myotherproject:mydataset

Note: You can enter the bq ls command to confirm that the dataset was
deleted.