BigQuery default connection for Looker (Google Cloud core)

Looker (Google Cloud core) must be connected to a database to enable data exploration. A default connection to a BigQuery Standard SQL database can be created using the BigQuery QuickStart Connection.

The BigQuery QuickStart tile on a home page.

Before you begin

Configuring a BigQuery QuickStart Connection requires the following permissions.

Looker permissions

You can view and edit theBigQuery QuickStart Connection page on your Looker (Google Cloud core) instanceHome page if you have one of the followingLooker permissions:

IAM permissions

Looker (Google Cloud core) instances can useApplication Default Credentials (ADC) to authenticate when you'resetting up a connection to BigQuery. When you use ADC, the connection will authenticate to the database by using the credentials of theLooker (Google Cloud core) service account. The service account must have the following IAM permissions to access the BigQuery dataset:

If the Looker (Google Cloud core) service account doesn't already have the necessary IAM roles, use the service account's email address when granting roles in that project. Tofind the service account's email address, go to theIAM page in the Google Cloud console and select theInclude Google-provided role grants checkbox. The email will have the formatservice-<project number>@gcp-sa-looker.iam.gserviceaccount.com. Use that email togrant the proper roles to the service account.

Configure a BigQuery QuickStart Connection

The BigQuery QuickStart Connection can be viewed and edited by users who have the correct permissions either from theHome page or from theConnections page in theAdmin panel. On theConnections page, the BigQuery QuickStart Connection appears under the nameDefault BigQuery Connection. On a new instance, theStorage project ID andBilling project ID fields will default toNone.

From theHome page, click theReview connection button to manage the connection. You can dismiss theHome page tile by clicking thex or by toggling theBigQuery Quick Start option in theDiscover sidebar.

The BigQuery QuickStart Connection contains the following sections:

Billing Project ID

Theproject ID serves as a unique identifier for the Google Cloud billing project. The billing project is the Google Cloudproject that gets billed for BigQuery usage, but you can still query datasets in a different Google Cloud project if your LookML developers specify fully scoped table names in thesql_table_name parameter of your LookMLviews,Explores, orjoins. This is a required field.

To authenticate to a BigQuery database using OAuth: For BigQuery connections, Looker (Google Cloud core) can automatically use the OAuth application credentials that your Looker (Google Cloud core) admin used when they created the instance. See theCreate OAuth authorization credentials for a Looker (Google Cloud core) instance page for more information.

Expand theStatus Details section to test the settings for your connection.

Primary Dataset

ThePrimary Dataset page contains the following settings.

Storage Project ID

In theStorage Project ID field, enter theproject ID for the project that contains the BigQuery dataset to which you want to connect, even if it's the same project that contains the Looker (Google Cloud core) instance. This is a required field.

Primary Dataset

The primary dataset is where BigQuery will look for tables if their location is not specified in the SQL query text. Note that Looker (Google Cloud core) queries can reference tables in any project or dataset, as long as the queries use fully scoped table names with the formatproject_id.dataset_name.table_name. The Looker (Google Cloud core) service account will also need the appropriateIAM permissions to access the tables in that location. This is a required field.

To learn more about datasets, see theConnecting Looker to BigQuery documentation page.

Expand theStatus Details section to test the settings for your connection.

Configure optional settings for your BigQuery connection

TheOptional Settings section contains the following options:

  • Maximum Connections per Node: The maximum number of connections to the database that are allowed at one time.Note: This setting is per each node in the Looker (Google Cloud core) deployment. The value must be between 5 and 100 and can be left at the default value initially. Read more about this setting in theMax connections per node section of theConnecting Looker to your database documentation page.

  • Connection Pool Timeout: The number of seconds that a query will wait before timing out when the connection pool is full. Can be left at the default value initially. Read more about this setting in theConnection Pool Timeout section of theConnecting Looker to your database documentation page.

  • Additional JDBC Parameters: Add any additional JDBC parameters, such as BigQuery labels (see theJob labels and context comments for BigQuery connections section on this page for more information).

  • Maintenance Schedule: Cron expression that indicates the maximum frequency of datagroup trigger checks and PDT maintenance. Read more about this setting in theMaintenance Schedule documentation.

  • SSL: Choose whether you want to use SSL encryption to protect data as it passes between Looker (Google Cloud core) and your database. SSL is only one option that can be used to protect your data; other secure options are described on theEnabling secure database access documentation page.

  • Verify SSL: Choose whether you want to require verification of the SSL certificate used by the connection. Read more about this setting in theVerify SSL section of theConnecting Looker to your database documentation page.

  • Precache tables and columns: In SQL Runner, all table information is pre-loaded as soon as you select a connection and schema. This enables SQL Runner to quickly display table columns as soon as you click a table name. However, for connections and schema with many tables or with very large tables, you may not want SQL Runner to pre-load all the information.

  • Fetch and cache schema: For some SQL-writing features such as aggregate awareness, Looker (Google Cloud core) uses your database's information schema to optimize SQL writing. Read more about this setting in theFetch Information Schema For SQL Writing section of theConnecting Looker to your database documentation page.

  • Enable PDTs: Turn on theEnable PDTs toggle to enablepersistent derived tables. When PDTs are enabled, theOptional Settings window reveals additional PDT fields and thePDT Overrides section.

  • Temp database: Enter the dataset in BigQuery where Looker (Google Cloud core) will createpersistent derived tables. You should configure this dataset ahead of time, with theappropriate write permissions. This field is required to use PDTs.

  • Max Number of PDT Builder Connections: TheMax number of PDT builder connections setting defaults to1 but may be set as high as100. However, the value cannot be higher than the value set in theMax connections per node. Read more about this setting in theMax Number of PDT Builder Connections section of theConnecting Looker to your database documentation page. Set this value carefully. If the value is too high, you may overwhelm your database. If the value is low, then long-running PDTs or aggregate tables can delay the creation of other persistent tables or slow down other queries on the connection.

  • Retry failed PDT builds: TheRetry failed PDT builds toggle configures how theLooker (Google Cloud core) regenerator attempts to rebuild trigger-persisted tables that failed in the previous regenerator cycle. Read more about this setting in theRetry failed PDT builds section of theConnecting Looker to your database documentation page.

  • PDT API Control: ThePDT API Control toggle determines whether thestart_pdt_build,check_pdt_build, andstop_pdt_build API calls can be used for this connection. When thePDT API Control toggle is disabled, these API calls will fail when they reference PDTs on this connection.

  • PDT Overrides: If your database supports persistent derived tables, and you have turned on theEnable PDTs toggle in the connection settings, Looker (Google Cloud core) displays thePDT Overrides section. In thePDT Overrides section, you can enter separate JDBC parameters (host, port, database, username, password, schema, additional parameters, and after connect statements) that are specific to PDT processes. Read more about this setting in thePDT Overrides section of theConnecting Looker to your database documentation page.

  • Database Time Zone: The time zone in which your database stores time-based information. Looker (Google Cloud core) needs to know this so that it can convert time values for users, making it easier to understand and use time-based data. See theUsing time zone settings documentation page for more information.

  • Query Time Zone: TheQuery Time Zone option is visible only if you have disabledUser Specific Time Zones. See theUsing time zone settings documentation page for more information.

Expand theStatus Details section to test the settings for your connection.

Review

Review and modify the connection details that you entered in the previous sections in theReview section.

Expand theStatus Details section to test the settings for your connection. Click the edit icon next to each section to be taken back to that section to change your settings.

Save and test the connection

To save any changes made to the BigQuery QuickStart Connection, clickSave.

You can test your connection settings from a couple of places in the Looker (Google Cloud core) UI:

  • Expand theStatus Details section at the bottom of any of the QuickStart Connection pages, and clickTest Connection.
  • From theHome page, expand theStatus Details section at the bottom of the QuickStart Connection tile, and clickTest Connection.
  • On theConnections Admin page, select theTest button next to the connection's listing, as described on theConnections documentation page.

Once you've entered the connection settings, clickTest to verify that the information is correct and the database is able to connect.

If your connection does not pass one or more tests, here are some troubleshooting options:

What's next

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.