Visão geral da conexão padrão

Para simplificar o fluxo de trabalho, você pode configurar uma conexão de recurso do Cloud padrão no BigQuery para criar tabelas externas e modelos remotos do BigQuery ML. Um administrador configura a conexão padrão, e os usuários podem fazer referência a ela durante a criação de recursos, em vez de precisar especificar os detalhes da conexão.

O BigQuery oferece suporte a conexões padrão nos seguintes recursos:

• Tabelas do BigLake no Cloud Storage
• Tabelas de objetos
• Tabelas gerenciadas do Apache Iceberg no BigQuery
• Modelos remotos

Para usar a conexão padrão, especifique a palavra-chave DEFAULT nas seguintes cláusulas SQL:

• A cláusula WITH CONNECTION de uma instru1ção CREATE EXTERNAL TABLE
• A cláusula REMOTE WITH CONNECTION de uma instrução CREATE MODEL para um modelo remoto

Antes de começar

Ative a API BigQuery Connection.

Ativar a API

Papéis e permissões necessárias

Para trabalhar com conexões padrão, use os seguintes papéis do Identity and Access Management (IAM):

• Usar a conexão padrão: Usuário de conexão do BigQuery (roles/bigquery.connectionUser) no seu projeto
• Definir a conexão padrão: Administrador do BigQuery (roles/bigquery.admin) no seu projeto

• Se for necessário conceder permissões à conta de serviço de uma conexão padrão:

  • Se a conexão padrão for usada para criar tabelas externas: Administrador do Storage (roles/storage.admin) em todos os buckets do Cloud Storage usados pelas tabelas externas.

  • Se a conexão padrão for usada para criar modelos remotos: Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) no projeto que contém o endpoint da Vertex AI. Para os seguintes tipos de modelos remotos, esse é o projeto atual:

    • Modelos remotos em serviços de IA do Google Cloud.
    • Modelos remotos em modelos do Google ou de parceiros que você criou especificando o nome do modelo como um endpoint.

    Para todos os outros modelos remotos, esse é o projeto que contém o endpoint da Vertex AI em que o modelo de destino está implantado.

    Se você usar o modelo remoto para analisar dados não estruturados de uma tabela de objetos e o bucket do Cloud Storage usado na tabela de objetos estiver em um projeto diferente do endpoint da Vertex AI, também será necessário ter o papel de Administrador do Storage (roles/storage.admin) no bucket do Cloud Storage usado pela tabela de objetos.

  Você só precisa desses papéis se for um administrador que está configurando uma conexão para uso como a conexão padrão ou um usuário que está usando uma conexão padrão que ainda não teve o papel apropriado concedido à conta de serviço. Para mais informações, consulte Configurar a conexão padrão connection.

Esses papéis predefinidos contêm as permissões necessárias para executar as tarefas neste documento. Para acessar as permissões exatas necessárias, expanda a seção Permissões necessárias:

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

Configurar a conexão padrão

Para configurar a conexão padrão pela primeira vez, use um dos seguintes métodos:

• Crie uma conexão, conceda os papéis apropriados à conta de serviço da conexão e defina a conexão como padrão.

  O usuário que cria e configura a conexão padrão precisa do papel de administrador do BigQuery e do papel de administrador do Storage ou administrador do IAM do projeto, conforme apropriado. O usuário da conexão padrão precisa do papel de usuário de conexão do BigQuery.

• Crie uma conexão e defina-a como padrão. O serviço concede os papéis apropriados à conta de serviço da conexão padrão quando ela é usada.

  O usuário que cria e define a conexão padrão precisa do papel de administrador do BigQuery. O usuário da conexão padrão precisa do papel de usuário de conexão do BigQuery e do papel de administrador do Storage ou administrador do IAM do projeto, conforme apropriado.

• Especifique a palavra-chave DEFAULT em uma instrução compatível. O serviço cria uma conexão, concede os papéis apropriados à conta de serviço da conexão e define a conexão como padrão.

  O usuário da conexão padrão precisa do papel de administrador do BigQuery e do papel de administrador do Storage ou administrador do IAM do projeto, conforme apropriado.

• Quando a conexão padrão está ausente, o BigQuery cria uma nova conexão com as seguintes propriedades:

  • Região:a mesma região do conjunto de dados.
  • Nome:__default_cloudresource_connection__
  • Tipo:CLOUD_RESOURCE

Definir a conexão padrão para um projeto

Defina a conexão a recursos do Cloud padrão para o projeto usando a ALTER PROJECT SET OPTIONS instrução DDL.

O exemplo a seguir define a conexão padrão para o projeto:

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

Substitua:

• PROJECT_ID: o ID do projeto em que você está definindo a conexão padrão.
• REGION: a região da conexão.
• CONNECTION_ID: o ID ou nome da conexão a ser usada como padrão para tabelas e modelos. Especifique apenas o ID ou nome da conexão e exclua os prefixos de ID do projeto e de região anexados ao nome ou ID.

Para mais informações sobre como configurar uma conexão padrão para um projeto, consulte Gerenciar configurações padrão.

Provisionamento de permissões para a conexão padrão

Quando você usa a conexão padrão para criar uma tabela externa ou um modelo remoto, Cloud de Confiance by S3NS concede à conta de serviço da conexão padrão os papéis apropriados se a conta de serviço ainda não os tiver. Essa ação falhará se você não tiver privilégios administrativos no recurso do Cloud Storage ou da Vertex AI usado pela tabela externa ou pelo modelo remoto.

Os papéis a seguir são concedidos à conta de serviço da conexão padrão:

Criar tabelas externas usando CONNECTION DEFAULT

Os exemplos a seguir mostram como criar tabelas externas especificando WITH CONNECTION DEFAULT no BigQuery.

Exemplo: criar uma tabela do BigLake no Cloud Storage

A expressão SQL a seguir cria uma tabela do BigLake no Cloud Storage com uma conexão padrão:

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

Exemplo: criar uma tabela de objetos com uma conexão padrão

A expressão SQL a seguir cria uma tabela de objetos com uma conexão padrão:

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

Exemplo: criar tabelas gerenciadas do Iceberg com uma conexão padrão

A expressão SQL a seguir cria tabelas gerenciadas do Iceberg com uma conexão padrão:

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');

Criar modelos remotos usando REMOTE WITH CONNECTION DEFAULT

Os exemplos a seguir mostram como criar modelos remotos especificando REMOTE WITH CONNECTION DEFAULT no BigQuery.

Exemplo: criar um modelo remoto em um modelo da Vertex AI

A expressão SQL a seguir cria um modelo remoto com uma conexão padrão:

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

Exemplo: criar um modelo remoto em um serviço de IA do Google Cloud

A expressão SQL a seguir cria um modelo remoto em um serviço de IA do Cloud com uma conexão padrão:

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

Exemplo: criar um modelo remoto com um endpoint HTTPS

A expressão SQL a seguir cria um modelo remoto com um endpoint HTTPS e uma conexão padrão:

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')

A seguir

• Saiba mais sobre a configuração padrão no BigQuery.