Listing datasets
This document describes how to list datasets in BigQuery.
You can list datasets in the following ways:
- Using the console.
- Using the
INFORMATION_SCHEMA
SQL query. - Using the
bq ls
command in thebq
command-line tool. - Calling the
datasets.list
API method. - Using the client libraries.
Before you begin
Grant Identity and Access Management (IAM) roles that give users the necessary permissions to perform each task in this document.
Required permissions
To list datasets, you need the bigquery.datasets.get
IAM permission.
Each of the following predefined IAM roles includes the permissions that you need in order to create a view:
roles/bigquery.user
roles/bigquery.dataOwner
roles/bigquery.dataEditor
roles/bigquery.admin
Additionally, roles/bigquery.metadataViewer
and roles/bigquery.dataViewer
, when applied at the project or organization level, can list all the datasets in the project.
For more information on IAM roles and permissions in BigQuery, see Predefined roles and permissions.
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.
SQL
Query the INFORMATION_SCHEMA.SCHEMATA
view:
In the console, go to the BigQuery page.
In the query editor, enter the following statement:
SELECT schema_name FROM PROJECT_ID.INFORMATION_SCHEMA.SCHEMATA;
Replace the following:
- PROJECT_ID: the ID of the project for which to list available datasets
Click
Run.
For more information about how to run queries, see Running interactive queries.
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: a label key and value
- integer: an integer representing the number of datasets to list
- project_id: 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.
Dataset security
To control access to datasets in BigQuery, see Controlling access to datasets. For information about data encryption, see Encryption at rest.
Next steps
- For more information on creating datasets, see Creating datasets.
- For more information on dataset metadata, see Getting information about datasets.
- For more information on changing dataset properties, see Updating dataset properties.
- For more information on creating and managing labels, see Creating and managing labels.