Visão geral da conexão padrão

Para simplificar seu fluxo de trabalho, configure uma conexão de recursos 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 especificar os detalhes da conexão.

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

• Tabelas do BigLake do Cloud Storage
• Tabelas de objetos
• Tabelas do BigLake para 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 instrução CREATE EXTERNAL TABLE
• A cláusula REMOTE WITH CONNECTION de uma instrução CREATE MODEL para um modelo remoto

Antes de começar

Enable the BigQuery Connection API.

Enable the 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):

• Use a conexão padrão: usuário de conexão do BigQuery (roles/bigquery.connectionUser) no seu projeto
• Defina 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 Cloud Storage (roles/storage.admin) em qualquer bucket do Cloud Storage usado 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, este é o projeto atual:

    • Modelos remotos em serviços de IA do Cloud.
    • Modelos remotos no Google ou modelos de parceiros que você criou ao especificar 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 é 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 estiver em um projeto diferente do endpoint da Vertex AI, também será necessário ter o administrador do Storage (roles/storage.admin) no bucket do Cloud Storage usado pela tabela de objetos.

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

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 as funções adequadas à 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 ter o papel de administrador do BigQuery e o papel de administrador do IAM do projeto ou do Storage, conforme apropriado. O usuário de conexão padrão precisa ter a função de usuário de conexão do BigQuery.

• Crie uma conexão e defina-a como padrão. O serviço concede papéis adequados à 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 ter o papel de administrador do BigQuery. O usuário de conexão padrão precisa ter o papel de usuário de conexão do BigQuery e o papel de administrador do IAM do projeto ou do armazenamento, conforme apropriado.

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

  O usuário de conexão padrão precisa ter a função de administrador do BigQuery e a função de administrador do IAM do projeto ou do Storage, conforme apropriado.

Definir a conexão padrão de um projeto

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

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 o nome da conexão e exclua o ID do projeto e os prefixos 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, Google Cloud concede à conta de serviço da conexão padrão as funções adequadas, se ela ainda não tiver. Essa ação falha 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 seguintes papéis 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 Cloud Storage para BigLake 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 do BigLake Iceberg no BigQuery com uma conexão padrão

A expressão SQL a seguir cria uma tabela BigLake Iceberg no BigQuery 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 do Cloud AI

A expressão SQL a seguir cria um modelo remoto em um serviço da Cloud AI 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.