Información general sobre 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, a continuación, los usuarios pueden hacer referencia a ella durante la creación de recursos en lugar de tener que especificar los detalles de la conexión.

BigQuery admite conexiones predeterminadas en los siguientes recursos:

• Tablas de BigLake de Cloud Storage
• Tablas de objetos
• Tablas de BigLake para Apache Iceberg en BigQuery
• Modelos remotos

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

• La cláusula WITH CONNECTION de una instrucción CREATE EXTERNAL TABLE
• La cláusula REMOTE WITH CONNECTION de una instrucción CREATE MODEL de un modelo remoto

Antes de empezar

Enable the BigQuery Connection API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Roles y permisos necesarios

Para trabajar con conexiones predeterminadas, usa los siguientes roles de Gestión de Identidades y Accesos (IAM):

• Usar la conexión predeterminada: usuario de conexión de BigQuery (roles/bigquery.connectionUser) en tu proyecto
• Define la conexión predeterminada: administrador de BigQuery (roles/bigquery.admin) en tu proyecto.

• Si es necesario conceder permisos a la cuenta de servicio de una conexión predeterminada, sigue estos pasos:

  • Si se usa la conexión predeterminada para crear tablas externas, se necesita el rol Administrador de Storage (roles/storage.admin) en los segmentos de Cloud Storage que usen las tablas externas.

  • Si se usa la conexión predeterminada para crear modelos remotos: administrador de gestión de identidades y accesos del proyecto (roles/resourcemanager.projectIamAdmin) en el proyecto que contiene el endpoint de Vertex AI. En los siguientes tipos de modelos remotos, este es el proyecto actual:

    • Modelos remotos a través de los servicios de IA de Cloud.
    • Modelos remotos de Google o modelos de partners que hayas creado especificando el nombre del modelo como endpoint.

    En el caso de todos los demás modelos remotos, se trata del proyecto que contiene el endpoint de Vertex AI en el que se ha desplegado el modelo de destino.

    Si usas el modelo remoto para analizar datos sin estructurar de una tabla de objetos y el segmento de Cloud Storage que usas en la tabla de objetos está en un proyecto diferente al de tu endpoint de Vertex AI, también debes tener el rol Administrador de Storage (roles/storage.admin) en el segmento de Cloud Storage que usa la tabla de objetos.

  Solo necesitas estos roles si eres un administrador que está configurando una conexión para usarla como conexión predeterminada o un usuario que está usando una conexión predeterminada a la que aún no se le ha concedido el rol adecuado a su cuenta de servicio. Para obtener más información, consulta Configurar la conexión predeterminada.

Estos roles predefinidos contienen los permisos necesarios para realizar las tareas descritas en este documento. Para ver los permisos exactos que se necesitan, despliega la sección Permisos necesarios:

Permisos obligatorios

• Usar la conexión predeterminada: bigquery.connections.use
• Crea una conexión: bigquery.connections.*
• Definir la conexión predeterminada: bigquery.config.*
• Define los permisos de la cuenta de servicio para una conexión predeterminada que se use para crear tablas externas: storage.buckets.getIamPolicy y storage.buckets.setIamPolicy.
• Define los permisos de la cuenta de servicio de 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 u otros roles predefinidos.

Configurar la conexión predeterminada

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

• Crea una conexión, asigna los roles adecuados a la cuenta de servicio de la conexión y, a continuación, establece la conexión como predeterminada.

  El usuario que cree y configure la conexión predeterminada debe tener el rol Administrador de BigQuery y el rol Administrador de almacenamiento o Administrador de gestión de identidades y accesos del proyecto, según corresponda. El usuario de la conexión predeterminada necesita el rol Usuario de conexión de BigQuery.

• Crea una conexión y, a continuación, configúrala como conexión predeterminada. La cuenta de servicio concede los roles adecuados a la cuenta de servicio de la conexión predeterminada cuando se usa esta conexión.

  El usuario que cree y defina la conexión predeterminada debe tener el rol Administrador de BigQuery. El usuario de conexión predeterminado necesita el rol Usuario de conexión de BigQuery y el rol Administrador de Storage o Administrador de gestión de identidades y accesos del proyecto, según corresponda.

• Especifica la palabra clave DEFAULT en una instrucción admitida. El servicio crea una conexión, asigna los roles adecuados a la cuenta de servicio de la conexión y, a continuación, establece la conexión como conexión predeterminada.

  El usuario de conexión predeterminado necesita el rol Administrador de BigQuery y el rol Administrador de almacenamiento o Administrador de gestión de identidades y accesos del proyecto, según corresponda.

Importante: El uso de una conexión predeterminada puede conceder privilegios adicionales a los usuarios. Por ejemplo, si un administrador usa la conexión predeterminada para crear una tabla de objetos, se le concederán a la cuenta de servicio de la conexión predeterminada los roles Lector de segmentos antiguos de Storage y Lector de objetos antiguos de Storage en el segmento de Cloud Storage correspondiente. Cualquier usuario al que se le haya concedido acceso para usar la conexión también podrá acceder a ese contenedor de Cloud Storage con los permisos concedidos a estos roles.

Definir la conexión predeterminada de un proyecto

Define la conexión predeterminada de recursos de Cloud del proyecto mediante la instrucción DDL ALTER PROJECT SET OPTIONS.

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

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

Haz los cambios siguientes:

• PROJECT_ID: el ID del proyecto en el que vas a definir la conexión predeterminada.
• REGION: la región de la conexión.
• CONNECTION_ID: el ID o el nombre de la conexión que se va a usar como predeterminada para las tablas y los modelos. Solo debe especificar el ID o el nombre de la conexión, y excluir los prefijos de ID de proyecto y de región asociados al nombre o al ID.

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

Provisionamiento de permisos para la conexión predeterminada

Cuando usas la conexión predeterminada para crear una tabla externa o un modelo remoto,Google Cloud asigna a la cuenta de servicio de la conexión predeterminada los roles adecuados si 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.

Se conceden los siguientes roles 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 Iceberg de BigLake en BigQuery	Cloud Storage	roles/storage.legacyBucketWriter roles/storage.legacyObjectOwner
Modelos remotos de BigQuery ML sobre modelos de Vertex AI	Modelos propiedad de Google	roles/aiplatform.user
	Se puede desplegar en un endpoint desde Model Garden
	Modelos de usuario
	Modelos optimizados	roles/aiplatform.serviceAgent
Modelos remotos de BigQuery ML en servicios de IA de Cloud	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

Crear tablas externas con CONNECTION DEFAULT

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

Ejemplo: Crear una tabla de BigLake de Cloud Storage

La siguiente expresión de SQL crea una tabla de 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: Crear 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: Crear tablas de Iceberg de BigLake en BigQuery con una conexión predeterminada

La siguiente expresión de SQL crea tablas de Iceberg de BigLake 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');

Crear 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: crear un modelo remoto a partir de un modelo de Vertex AI

La siguiente expresión 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: crear un modelo remoto en un servicio de IA de Cloud

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

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

Ejemplo: crear un modelo remoto con un endpoint HTTPS

La siguiente expresión SQL crea un modelo remoto con un endpoint 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')

Siguientes pasos

• Consulta información sobre la configuración predeterminada en BigQuery.