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 los detalles de la conexión.

BigQuery admite conexiones predeterminadas en los siguientes recursos:

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

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

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

Antes de comenzar

Habilita la API de conexión de BigQuery.

Habilitar la API

Roles y permisos requeridos

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

• Usar la conexión predeterminada: Usuario de conexión de BigQuery (roles/bigquery.connectionUser) en tu proyecto
• Establecer 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 la conexión predeterminada se usa para crear tablas externas: Administrador de Storage (roles/storage.admin) en cualquier buckets de Cloud Storage que usen las tablas externas

  • Si la conexión predeterminada se usa 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 IA de Cloud
    • Modelos remotos a través de modelos de Google o de 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 Administrador de Storage (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 Configura 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:

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, establece la conexión 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 Storage o de administrador de IAM del proyecto, según corresponda. El usuario de la conexión predeterminada necesita el rol de usuario de conexión de BigQuery.

• Crea una conexión y, luego, establécela como la conexión 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 establece la conexión predeterminada necesita el rol de administrador de BigQuery. El usuario de la conexión predeterminada necesita el rol de usuario de conexión de BigQuery y el rol de administrador de Storage o de administrador de IAM del proyecto, según corresponda.

• Especifica la palabra clave DEFAULT en una instrucción 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 conexión predeterminada.

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

• Cuando falta la conexión predeterminada, BigQuery crea una conexión nueva con las siguientes propiedades:

  • Región: La misma región que el conjunto de datos
  • Nombre: __default_cloudresource_connection__
  • Tipo: CLOUD_RESOURCE

Establece la conexión predeterminada para un proyecto

Para establecer la conexión de recursos de Cloud predeterminada para el proyecto, usa la ALTER PROJECT SET OPTIONS instrucción DDL.

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

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

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto en el que estableces la conexión predeterminada.
• REGION: Es la región de la conexión.
• CONNECTION_ID: Es 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 los prefijos de ID del proyecto y 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, Cloud de Confiance by S3NS le otorga a la cuenta de servicio de la conexión predeterminada los roles adecuados si la cuenta de servicio aún no los tiene. Esta acción falla si no tienes privilegios administrativos 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:

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 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: 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 administradas de Iceberg con una conexión predeterminada

La siguiente expresión de SQL crea tablas administradas de Iceberg 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 a través de 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 a través de un servicio de IA de Cloud

La siguiente expresión de SQL crea un modelo remoto a través de 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: 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.