Se usó la API de Cloud Translation para traducir esta página.

Descripción general de la conexión predeterminada

Para simplificar tu flujo de trabajo, puedes configurar una conexión de recursos de Cloud predeterminada en BigQuery para crear tablas externas y modelos remotos de BigQuery ML. Un administrador configura la conexión predeterminada y, luego, los usuarios pueden hacer referencia a ella durante la creación de recursos en lugar de tener que especificar detalles de la conexión.

BigQuery admite conexiones predeterminadas en los siguientes recursos:

Para usar la conexión predeterminada, especifica la palabra clave DEFAULT en las siguientes cláusulas SQL:

La cláusula WITH CONNECTION de una sentencia CREATE EXTERNAL TABLE
La cláusula REMOTE WITH CONNECTION de una declaración CREATE MODEL para un modelo remoto

Antes de comenzar

Enable the BigQuery Connection API.

Enable the API

Roles y permisos requeridos

Para trabajar con conexiones predeterminadas, usa los siguientes roles de Identity and Access Management (IAM):

Usa la conexión predeterminada: Usuario de conexión de BigQuery (roles/bigquery.connectionUser) en tu proyecto
Establece la conexión predeterminada: Administrador de BigQuery (roles/bigquery.admin) en tu proyecto
Si es necesario otorgar permisos a la cuenta de servicio de una conexión predeterminada, haz lo siguiente:
- Si se usa la conexión predeterminada para crear tablas externas, Administrador de almacenamiento (roles/storage.admin) en cualquier buckets de Cloud Storage que usen las tablas externas
- Si se usa la conexión predeterminada para crear modelos remotos: Administrador de IAM del proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto que contiene el extremo de Vertex AI Para los siguientes tipos de modelos remotos, este es el proyecto actual:
  - Modelos remotos a través de los servicios de Cloud AI
  - Modelos remotos sobre modelos de Google o socios que creaste especificando el nombre del modelo como un extremo
  Para todos los demás modelos remotos, este es el proyecto que contiene el extremo de Vertex AI en el que se implementa el modelo de destino.
  
  Si usas el modelo remoto para analizar datos no estructurados de una tabla de objetos y el bucket de Cloud Storage que usas en la tabla de objetos está en un proyecto diferente al extremo de Vertex AI, también debes tener el rol de administrador de almacenamiento (roles/storage.admin) en el bucket de Cloud Storage que usa la tabla de objetos.
Solo necesitas estos roles si eres un administrador que configura una conexión para usarla como la conexión predeterminada o un usuario que usa una conexión predeterminada a la que aún no se le otorgó el rol adecuado a su cuenta de servicio. Para obtener más información, consulta Cómo configurar la conexión predeterminada.

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas de este documento. Para ver los permisos exactos que son necesarios, expande la sección Permisos necesarios:

Permisos necesarios

Usa la conexión predeterminada: bigquery.connections.use
Crea una conexión: bigquery.connections.*
Establece la conexión predeterminada: bigquery.config.*
Establece permisos de cuenta de servicio para una conexión predeterminada que se usa para crear tablas externas: storage.buckets.getIamPolicy y storage.buckets.setIamPolicy
Establece los permisos de la cuenta de servicio para una conexión predeterminada que se usa para crear modelos remotos:
- resourcemanager.projects.getIamPolicy y resourcemanager.projects.setIamPolicy
- Si se usa la conexión predeterminada con un modelo remoto que procesa datos no estructurados de una tabla de objetos, storage.buckets.getIamPolicy y storage.buckets.setIamPolicy

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Configura la conexión predeterminada

Para configurar la conexión predeterminada por primera vez, usa uno de los siguientes métodos:

Crea una conexión, otorga los roles adecuados a la cuenta de servicio de la conexión y, luego, configúrala como la conexión predeterminada.

El usuario que crea y configura la conexión predeterminada necesita el rol de administrador de BigQuery y el rol de administrador de IAM del proyecto o de almacenamiento, según corresponda. El usuario de conexión predeterminado necesita el rol de Usuario de conexión de BigQuery.
Crea una conexión y, luego, configúrala como la predeterminada. El servicio otorga los roles adecuados a la cuenta de servicio de la conexión predeterminada cuando se usa la conexión predeterminada.

El usuario que crea y configura la conexión predeterminada necesita el rol de administrador de BigQuery. El usuario de conexión predeterminado necesita el rol de usuario de conexión de BigQuery y el rol de administrador de almacenamiento o administrador de IAM del proyecto, según corresponda.
Especifica la palabra clave DEFAULT en una sentencia compatible. El servicio crea una conexión, otorga los roles adecuados a la cuenta de servicio de la conexión y, luego, establece la conexión como la predeterminada.

El usuario de conexión predeterminado necesita el rol de administrador de BigQuery y el rol de administrador de IAM del proyecto o de almacenamiento, según corresponda.

Cómo establecer la conexión predeterminada de un proyecto

Configura la conexión de recursos de Cloud predeterminada del proyecto con la declaración DDL ALTER PROJECT SET OPTIONS.

En el siguiente ejemplo, se establece la conexión predeterminada del proyecto:

  ALTER PROJECT PROJECT_ID
  SET OPTIONS (
    `region-REGION.default_cloud_resource_connection_id` = CONNECTION_ID);

Reemplaza lo siguiente:

PROJECT_ID: El ID del proyecto en el que configuras la conexión predeterminada.
REGION: Es la región de la conexión.
CONNECTION_ID: El ID o el nombre de la conexión que se usará como predeterminada para las tablas y los modelos. Solo especifica el ID o el nombre de la conexión, y excluye el ID del proyecto y los prefijos de región adjuntos al nombre o al ID.

Para obtener más información sobre cómo configurar una conexión predeterminada para un proyecto, consulta Administra las configuraciones predeterminadas.

Aprovisionamiento de permisos para la conexión predeterminada

Cuando usas la conexión predeterminada para crear una tabla externa o un modelo remoto, Google Cloud otorga a la cuenta de servicio de la conexión predeterminada los roles apropiados si la cuenta de servicio aún no los tiene. Esta acción falla si no tienes privilegios de administrador en el recurso de Cloud Storage o Vertex AI que usa la tabla externa o el modelo remoto.

Los siguientes roles se otorgan a la cuenta de servicio de la conexión predeterminada:

Tipo de tabla o modelo	Recurso remoto	Roles asignados a la cuenta de servicio de la conexión
Tabla de BigLake de Cloud Storage	Cloud Storage	`roles/storage.legacyBucketReader` `roles/storage.legacyObjectReader`
Tabla de objetos	Cloud Storage	`roles/storage.legacyBucketReader` `roles/storage.legacyObjectReader`
Tablas de BigLake Iceberg en BigQuery	Cloud Storage	`roles/storage.legacyBucketWriter` `roles/storage.legacyObjectOwner`
Modelos remotos de BigQuery ML en lugar de modelos de Vertex AI	Modelos de Google	`roles/aiplatform.user`
	Se puede implementar en un extremo desde Model Garden
	Modelos de usuario
	Modelos ajustados	`roles/aiplatform.serviceAgent`
Modelos remotos de BigQuery ML a través de servicios de Cloud AI	Procesador de documentos	`roles/documentai.apiUser`
	Reconocedor de voz	`roles/speech.serviceAgent`
	PLN de Cloud	`roles/serviceusage.serviceUsageConsumer`
	Cloud Vision	`roles/serviceusage.serviceUsageConsumer`
	Cloud Translation	`roles/cloudtranslate.user`

Crea tablas externas con `CONNECTION DEFAULT`

En los siguientes ejemplos, se muestra cómo crear tablas externas especificando WITH CONNECTION DEFAULT en BigQuery.

Ejemplo: Crea una tabla de BigLake de Cloud Storage

La siguiente expresión SQL crea una tabla BigLake de Cloud Storage con una conexión predeterminada:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  format = 'TABLE_FORMAT',
  uris = ['BUCKET_PATH']);

Ejemplo: Crea una tabla de objetos con una conexión predeterminada

La siguiente expresión de SQL crea una tabla de objetos con una conexión predeterminada:

CREATE EXTERNAL TABLE PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME
WITH CONNECTION DEFAULT
OPTIONS (
  object_metadata = 'SIMPLE'
  uris = ['BUCKET_PATH']);

Ejemplo: Crea tablas de BigLake Iceberg en BigQuery con una conexión predeterminada

La siguiente expresión SQL crea una tabla de BigLake Iceberg en BigQuery con una conexión predeterminada:

CREATE TABLE `myproject.tpch_clustered.nation` (
  n_nationkey integer,
  n_name string,
  n_regionkey integer,
  n_comment string)
CLUSTER BY n_nationkey
WITH CONNECTION DEFAULT
OPTIONS (
  file_format = 'PARQUET',
  table_format = 'ICEBERG',
  storage_uri = 'gs://mybucket/warehouse/nation');

Crea modelos remotos con `REMOTE WITH CONNECTION DEFAULT`

En los siguientes ejemplos, se muestra cómo crear modelos remotos especificando REMOTE WITH CONNECTION DEFAULT en BigQuery.

Ejemplo: Crea un modelo remoto sobre un modelo de Vertex AI

La siguiente expresión de SQL crea un modelo remoto con una conexión predeterminada:

CREATE OR REPLACE MODEL `mydataset.flash_model`
  REMOTE WITH CONNECTION DEFAULT
  OPTIONS(ENDPOINT = 'gemini-2.0-flash');

Ejemplo: Crea un modelo remoto sobre un servicio de Cloud AI

La siguiente expresión SQL crea un modelo remoto a través de un servicio de Cloud AI con una conexión predeterminada:

CREATE MODEL `project_id.mydataset.mymodel`
REMOTE WITH CONNECTION DEFAULT
 OPTIONS(REMOTE_SERVICE_TYPE = 'CLOUD_AI_VISION_V1')

Ejemplo: Crea un modelo remoto con un extremo HTTPS

La siguiente expresión de SQL crea un modelo remoto con un extremo HTTPS y una conexión predeterminada:

CREATE MODEL `project_id.mydataset.mymodel`
 INPUT(f1 INT64, f2 FLOAT64, f3 STRING, f4 ARRAY)
 OUTPUT(out1 INT64, out2 INT64)
 REMOTE WITH CONNECTION DEFAULT
 OPTIONS(ENDPOINT = 'https://us-central1-aiplatform.googleapis.com/v1/projects/myproject/locations/us-central1/endpoints/1234')

¿Qué sigue?

Obtén información sobre la configuración predeterminada en BigQuery.