Default connection overview

To simplify your workflow, you can configure a defaultCloud resource connection in BigQuery for creating external tables and BigQuery MLremote models. An administrator configures the default connection, and thenusers can reference it during resource creation instead of having to specifyconnection details.

BigQuery supports default connections in the following resources:

• Cloud Storage BigLake tables
• Object tables
• BigLake tables for Apache Iceberg in BigQuery
• Remote models

To use the default connection, specify theDEFAULT keyword in the followingSQL clauses:

• TheWITH CONNECTION clause of aCREATE EXTERNAL TABLE statement
• TheREMOTE WITH CONNECTION clause of aCREATE MODEL statement for a remote model

Before you begin

Enable the BigQuery Connection API.

Enable the API

Required roles and permissions

To work with default connections, use the following Identity and Access Management (IAM)roles:

• Use the default connection: BigQuery Connection User(roles/bigquery.connectionUser) on your project
• Set the default connection: BigQuery Admin (roles/bigquery.admin) on yourproject

• If it is necessary to grant permissions to the service account of a defaultconnection:

  • If the default connection is used to create external tables: StorageAdmin (roles/storage.admin) on any Cloud Storage buckets used by theexternal tables.

  • If the default connection is used to create remote models: Project IAMAdmin (roles/resourcemanager.projectIamAdmin) on the project that containsthe Vertex AI endpoint. For the following types of remote models,this is the current project:

    • Remote models over Cloud AI services.
    • Remote models over Google or partner models that you created byspecifying the model name as an endpoint.

    For all other remote models, this is the project that contains theVertex AI endpoint to which the target model is deployed.

    If you use the remote model to analyze unstructured data from an objecttable, and the Cloud Storage bucket that you use in the objecttable is in a different project than your Vertex AIendpoint, you must also have Storage Admin (roles/storage.admin) on theCloud Storage bucket used by the object table.

  You only need these roles if you are an administrator configuring aconnection for use as the default connection, or a user who is using adefault connection that has not yet had the appropriate role granted to itsservice account. For more information, seeConfigure the defaultconnection.

These predefined roles contain the permissions required to perform the tasks inthis document. To see the exact permissions that are required, expand theRequired permissions section:

You might also be able to get these permissions withcustom rolesor otherpredefined roles.

Configure the default connection

To configure the default connection for the first time, use one of thefollowing methods:

• Create a connection, grant appropriate roles to the connection's serviceaccount, and then set the connection as the default connection.

  The user creating and configuring the default connection needs the BigQueryAdmin role and the Storage Admin or Project IAM Admin role, asappropriate. The default connection user needs the BigQuery Connection Userrole.

• Create a connection and then set it as the default connection. The servicegrants appropriate roles to the defaultconnection's service account when the default connection is used.

  The user creating and setting the default connection needs the BigQuery Adminrole. The default connection user needs the BigQuery Connection User roleand the Storage Admin or Project IAM Admin role, as appropriate.

• Specify theDEFAULT keyword in a supported statement. The servicecreates a connection, grants appropriate roles to the connection's serviceaccount, and then sets the connection as the default connection.

  The default connection user needs the BigQuery Admin role and the StorageAdmin or Project IAM Admin role, as appropriate.

Set the default Cloud resource connection for the project by using theALTER PROJECT SET OPTIONS DDL statement.

The following example sets the default connection for the project:

ALTERPROJECTPROJECT_IDSETOPTIONS(`region-REGION.default_cloud_resource_connection_id`=CONNECTION_ID);

Replace the following:

• PROJECT_ID: the ID of the project where you're settingthe default connection.
• REGION: the region of the connection.
• CONNECTION_ID: the ID or name of the connection to useas the default for tables and models. Only specify the connectionID or name, and exclude the project ID and region prefixes attached to thename or ID.

For more information about configuring a default connection for a project, seeManage default configurations.

Permissions provisioning for the default connection

When you use the default connection to create an external table or remote model,Google Cloud grants the default connection's service account theappropriate roles if the service account doesn't already have them. This actionfails if you don't have administrative privileges on the Cloud Storage orVertex AI resource used by the external table or remote model.

The following roles are granted to the default connection's service account:

Create external tables usingCONNECTION DEFAULT

The following examples show how to create external tables by specifyingWITH CONNECTION DEFAULT in BigQuery.

Example: Create a Cloud Storage BigLake table

The following SQL expression creates aCloud Storage BigLake table with a default connection:

CREATEEXTERNALTABLEPROJECT_ID.DATASET.EXTERNAL_TABLE_NAMEWITHCONNECTIONDEFAULTOPTIONS(format='TABLE_FORMAT',uris=['BUCKET_PATH']);

Example: Create an object table with a default connection

The following SQL expression creates anobject table with a defaultconnection:

CREATEEXTERNALTABLEPROJECT_ID.DATASET.EXTERNAL_TABLE_NAMEWITHCONNECTIONDEFAULTOPTIONS(object_metadata='SIMPLE'uris=['BUCKET_PATH']);

Example: Create a BigLake Iceberg tables in BigQuery with a default connection

The following SQL expression creates aBigLake Iceberg tables in BigQuery with a default connection:

CREATETABLE`myproject.tpch_clustered.nation`(n_nationkeyinteger,n_namestring,n_regionkeyinteger,n_commentstring)CLUSTERBYn_nationkeyWITHCONNECTIONDEFAULTOPTIONS(file_format='PARQUET',table_format='ICEBERG',storage_uri='gs://mybucket/warehouse/nation');

Create remote models usingREMOTE WITH CONNECTION DEFAULT

The following examples show how to create remote models by specifyingREMOTE WITH CONNECTION DEFAULT in BigQuery.

Example: Create a remote model over a Vertex AI model

The following SQL expression creates aremote model with a default connection:

CREATEORREPLACEMODEL`mydataset.flash_model`REMOTEWITHCONNECTIONDEFAULTOPTIONS(ENDPOINT='gemini-2.0-flash');

Example: Create a remote model over a Cloud AI service

The following SQL expression creates aremote model over a Cloud AIservice with a default connection:

CREATEMODEL`project_id.mydataset.mymodel`REMOTEWITHCONNECTIONDEFAULTOPTIONS(REMOTE_SERVICE_TYPE='CLOUD_AI_VISION_V1')

Example: Create a remote model with an HTTPS endpoint

The following SQL expression creates aremote model with an HTTPS endpoint and a default connection:

CREATEMODEL`project_id.mydataset.mymodel`INPUT(f1INT64,f2FLOAT64,f3STRING,f4ARRAY)OUTPUT(out1INT64,out2INT64)REMOTEWITHCONNECTIONDEFAULTOPTIONS(ENDPOINT='https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

What's next

• Learn aboutdefault configuration in BigQuery.