Visão geral da conexão padrão

Para simplificar seu fluxo de trabalho, configure 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 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 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):

• 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 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 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 é 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 dessas funções se for um administrador 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 a função apropriada concedida à 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 os papéis adequados à 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 de administrador do Storage ou administrador do IAM do projeto, conforme apropriado. O usuário de conexão padrão precisa da função "Usuário de conexão do BigQuery".

• Crie uma conexão e defina 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 da função de administrador do BigQuery. O usuário da conexão padrão precisa do papel de usuário da conexão do BigQuery e do papel de administrador do armazenamento ou 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 adequados à conta de serviço da conexão e define a conexão como padrão.

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

Definir a conexão padrão para um projeto

Defina a conexão padrão de recursos do Cloud 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 os prefixos de ID do projeto e 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

Ao usar a conexão padrão para criar uma tabela externa ou um modelo remoto, oTrusted Cloud by S3NS concede à conta de serviço da conexão padrão as funções adequadas, caso ela ainda não as tenha. 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 BigLake do 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 do BigLake Iceberg no BigQuery com uma conexão padrão

A expressão SQL a seguir cria tabelas do 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 usando 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 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.