This document describes how to list datasets in BigQuery.
You can list datasets in the following ways:
- Using the Cloud Console.
- Using the
bq ls
command in thebq
command-line tool. - Calling the
datasets.list
API method. - Using the client libraries.
Required permissions
When you list datasets, only datasets for which you have bigquery.datasets.get
permissions are returned. The following predefined IAM roles
include bigquery.datasets.get
permissions:
bigquery.user
bigquery.metadataViewer
bigquery.dataViewer
bigquery.dataOwner
bigquery.dataEditor
bigquery.admin
For more information on IAM roles and permissions in BigQuery, see Access control.
Listing datasets in a project
To list the datasets in a project:
Console
In the navigation menu, click SQL workspace.
In the Explorer panel, expand a project name to see the datasets in that project, or use the search box to search by dataset name.
bq
Issue the bq ls
command to list datasets by dataset ID. The --format
flag can be used to control the output. If you are listing dataset in a
project other than your default project, add the --project_id
flag to the
command.
To list all datasets in a project, including anonymous datasets,
use the --all
flag or the -a
shortcut.
To list all datasets in a project, excluding anonymous datasets, use the
--datasets
flag or the -d
shortcut. This flag is optional. By default,
anonymous datasets are not listed.
Additional flags include:
--filter
: List datasets that match the filter expression. Use a space-separated list of label keys and values in the formlabels.key:value
. For more information on filtering datasets using labels, see Adding and using labels.--max_results
or-n
: An integer indicating the maximum number of results. The default value is50
.
bq ls --filter labels.key:value \ --max_results integer \ --format=prettyjson \ --project_id project_id
Replace the following:
- key:value is a label key and value.
- integer is an integer representing the number of datasets to list.
- project_id is the name of your project.
Examples:
Enter the following command to list datasets in your default project. --
format
is set to pretty to return a basic formatted table.
bq ls --format=pretty
Enter the following command to list datasets in myotherproject
. --format
is set to prettyjson
to return detailed results in JSON format.
bq ls --format=prettyjson --project_id myotherproject
Enter the following command to list all datasets including anonymous datasets in your default project. In the output, anonymous datasets begin with an underscore.
bq ls -a
Enter the following command to return more than the default output of 50 datasets from your default project.
bq ls --max_results 60
Enter the following command to list datasets in your default project with
the label org:dev
.
bq ls --filter labels.org:dev
API
To list datasets using the API, call the datasets.list
API method.
C#
Before trying this sample, follow the C# setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery C# API reference documentation.
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.
Java
Before trying this sample, follow the Java setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Java API reference documentation.
Node.js
Before trying this sample, follow the Node.js setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Node.js API reference documentation.
PHP
Before trying this sample, follow the PHP setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery PHP API reference documentation.
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.
Ruby
Before trying this sample, follow the Ruby setup instructions in the BigQuery Quickstart Using Client Libraries. For more information, see the BigQuery Ruby API reference documentation.
Next steps
- For more information on creating datasets, see Creating datasets.
- For more information on assigning access controls to datasets, see Controlling access to datasets.
- For more information on dataset metadata, see Getting information about datasets.
- For more information on changing dataset properties, see Updating datasets.
- For more information on creating and managing labels, see Creating and managing labels.