Gerenciar recomendações de partição e cluster

Este documento descreve como o recomendador de partição e cluster funciona, como visualizar suas recomendações e insights e como aplicar recomendações de partição e cluster.

Como o recomendador funciona

O recomendador de particionamento e clustering do BigQuery gera recomendações de partição ou cluster para otimizar as tabelas do BigQuery. O recomendador analisa os fluxos de trabalho nas tabelas do BigQuery e oferece recomendações para otimizar melhor seus fluxos de trabalho e custos de consulta usando o particionamento de tabelas ou o clustering de tabelas.

Para mais informações sobre o serviço do recomendador, consulte a Visão geral do recomendador.

O recomendador de particionamento e clustering usa os dados de execução da carga de trabalho do projeto dos últimos 30 dias para analisar cada tabela do BigQuery para configurações de particionamento e clustering abaixo do ideal. O recomendador também usa o machine learning para prever quanto a execução da carga de trabalho pode ser otimizada com diferentes configurações de particionamento ou clustering. Se o recomendador descobrir que o particionamento ou clustering de uma tabela gera economias significativas, ele vai gerar uma recomendação. O recomendador de particionamento e clustering gera os seguintes tipos de recomendações:

Tipo de tabela existente	Subtipo de recomendação	Exemplo de recomendação
Não particionado, sem cluster	Partição	"Economize cerca de 64 horas de slot por mês ao particionar em column_C por DAY"
Não particionado, sem cluster	Cluster	"Economize cerca de 64 horas de slot por mês ao fazer clustering em column_C"
Particionada, sem cluster	Cluster	"Economize cerca de 64 horas de slot por mês ao fazer clustering em column_C"

Cada recomendação tem três partes:

• Orientação para particionar ou fazer cluster de uma tabela específica
• A coluna específica em uma tabela para particionar ou fazer cluster
• Estimativa de economia mensal para aplicar a recomendação

Para calcular possíveis economias de carga de trabalho, o recomendador considera que os dados históricos de execução dos últimos 30 dias representam a carga de trabalho futura.

A API Recommender também retorna informações de carga de trabalho na tabela na forma de insights. Insights são descobertas que ajudam você a entender a carga de trabalho do seu projeto, fornecendo mais contexto sobre como uma recomendação de partição ou cluster pode melhorar os custos da carga de trabalho.

Limitações

• O recomendador de particionamento e clustering não oferece suporte a tabelas do BigQuery com SQL legado. Ao gerar uma recomendação, o recomendador exclui todas as consultas de SQL legadas na análise. Além disso, aplicar recomendações de partição nas tabelas do BigQuery com SQL legado interrompe os fluxos de trabalho do SQL legado nessa tabela.

  Antes de aplicar recomendações de partição, migre os fluxos de trabalho do SQL legado para o GoogleSQL.

• O BigQuery não é compatível com a alteração do esquema de particionamento de uma tabela. Só é possível mudar o particionamento de uma tabela em uma cópia dela. Para mais informações, consulte Aplicar recomendações de partição.

Locais

O recomendador de particionamento e clustering está disponível nos locais de processamento:

	Descrição da região	Nome da região	Detalhes
Ásia-Pacífico
	Délhi	asia-south2
	Hong Kong	asia-east2
	Jacarta	asia-southeast2
	Mumbai	asia-south1
	Osaka	asia-northeast2
	Seul	asia-northeast3
	Singapura	asia-southeast1
	Sydney	australia-southeast1
	Taiwan	asia-east1
	Tóquio	asia-northeast1
Europa
	Bélgica	europe-west1	Baixo CO2
	Berlim	europe-west10	Baixo CO2
	UE multirregião	eu
	Frankfurt	europe-west3	Baixo CO2
	Londres	europe-west2	Baixo CO2
	Países Baixos	europe-west4	Baixo CO2
	Zurique	europe-west6	Baixo CO2
América
	Iowa	us-central1	CO2 baixo
	Las Vegas	us-west4
	Los Angeles	us-west2
	Montreal	northamerica-northeast1	CO2 baixo
	Norte da Virgínia	us-east4
	Oregon	us-west1	CO2 baixo
	Salt Lake City	us-west3
	São Paulo	southamerica-east1	Baixo CO2
	Toronto	northamerica-northeast2	Baixo CO2
	EUA multirregião	us

Antes de começar

• Verifique se o Gemini no BigQuery está ativado para seu projeto do Google Cloud.
• Ative a API Recommender.

Permissões necessárias

Para receber as permissões necessárias para acessar as recomendações de partição e cluster, peça ao administrador para conceder a você o papel de Leitor do recomendador de clustering de particionamento do BigQuery (roles/recommender.bigqueryPartitionClusterViewer) do IAM. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para acessar as recomendações de partição e cluster. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para acessar as recomendações de partição e cluster:

• recommender.bigqueryPartitionClusterRecommendations.get
• recommender.bigqueryPartitionClusterRecommendations.list

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

Para mais informações sobre os papéis e as permissões do IAM no BigQuery, consulte Introdução ao IAM.

Ver recomendações

Nesta seção, descrevemos como visualizar recomendações e insights de cluster e partição usando o console do Google Cloud, a CLI do Google Cloud ou a API Recommender.

Observação: também é possível exportar recomendações para o BigQuery usando o serviço de transferência de dados do BigQuery. Saiba mais em Exportar recomendações para o BigQuery.

Selecione uma das seguintes opções:

Console

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. Para abrir a guia de recomendações, clique em Recomendações > Ver todas as recomendações.

   

   A guia de recomendações lista todas as recomendações disponíveis para o projeto.

3. No painel Otimizar o custo da carga de trabalho do BigQuery, clique em Ver tudo.

   A tabela de recomendações de custos lista todas as recomendações geradas para o projeto atual. Por exemplo, a captura de tela a seguir mostra que o recomendador analisou a tabela example_table e, em seguida, recomendo o clustering da coluna example_column para economizar uma quantidade aproximada de bytes e slots.

   

4. Para mais informações sobre o insight e a recomendação da tabela, clique em uma recomendação.

gcloud

Para conferir recomendações de partição ou cluster para um projeto específico, use o comando gcloud recommender recommendations list:

gcloud recommender recommendations list \
    --project=PROJECT_NAME \
    --location=REGION_NAME \
    --recommender=google.bigquery.table.PartitionClusterRecommender \
    --format=FORMAT_TYPE \

Substitua:

• PROJECT_NAME: o nome do projeto que contém sua tabela do BigQuery.
• REGION_NAME: a região em que o projeto está.
• FORMAT_TYPE: um formato de saída da CLI gcloud com suporte. Por exemplo, JSON

A tabela a seguir descreve os campos importantes da resposta da API do recomendador:

Propriedade	Relevante para o subtipo	Descrição
recommenderSubtype	Partição ou cluster	Indica o tipo de recomendação.
content.overview.partitionColumn	Partição	Nome da coluna de particionamento recomendado.
content.overview.partitionTimeUnit	Partição	Unidade de tempo de particionamento recomendada. Por exemplo, DAY significa que a recomendação é ter partições diárias na coluna recomendada.
content.overview.clusterColumns	Cluster	Nomes das colunas de clustering recomendados.

• Para saber mais sobre outros campos na resposta do recomendador, consulte Recurso REST: projects.locations.recommendersrecommendation.
• Para mais informações sobre o uso da API Recommender, consulte Como usar a API - Recomendações.

Para visualizar insights de tabela usando a CLI gcloud, use o comando gcloud recommender insights list:

gcloud recommender insights list \
    --project=PROJECT_NAME \
    --location=REGION_NAME \
    --insight-type=google.bigquery.table.StatsInsight \
    --format=FORMAT_TYPE \

Substitua:

• PROJECT_NAME: o nome do projeto que contém sua tabela do BigQuery.
• REGION_NAME: a região em que o projeto está.
• FORMAT_TYPE: um formato de saída da CLI gcloud com suporte. Por exemplo, JSON

A tabela a seguir descreve os campos importantes da resposta da API Insights:

Propriedade	Relevante para o subtipo	Descrição
content.existingPartitionColumn	Cluster	Coluna de particionamento atual, se houver
content.tableSizeTb	Todos	Tamanho da tabela em terabytes
content.bytesReadMonthly	Todos	Bytes mensais lidos na tabela
content.slotMsConsumedMonthly	Todos	Milissegundos mensais de slot consumidos pela carga de trabalho em execução na tabela
content.queryJobsCountMonthly	Todos	Contagem mensal de jobs em execução na tabela

• Para saber mais sobre outros campos na resposta de insights, consulte Recurso REST: projects.locations.insightTypes.insights.
• Para mais informações sobre o uso de insights, consulte Como usar a API - Insights.

API REST

Para ver as recomendações de partição ou cluster para um projeto específico, use a API REST. Com cada comando, é necessário fornecer um token de autenticação, que é possível receber usando a CLI gcloud. Para mais informações sobre como receber um token de autenticação, consulte Métodos para receber um token de ID.

Use a solicitação curl list para ver todas as recomendações de um projeto específico:

curl
    -H "Authorization: Bearer $GCLOUD_AUTH_TOKEN"
    -H "x-goog-user-project: PROJECT_NAME" https://recommender.googleapis.com/v1/projects/my-project/locations/us/recommenders/google.bigquery.table.PartitionClusterRecommender/recommendations

Substitua:

• GCLOUD_AUTH_TOKEN: o nome de um token de acesso válido da CLI do gcloud
• PROJECT_NAME: o nome do projeto que contém a tabela do BigQuery

A tabela a seguir descreve os campos importantes da resposta da API do recomendador:

Propriedade	Relevante para o subtipo	Descrição
recommenderSubtype	Partição ou cluster	Indica o tipo de recomendação.
content.overview.partitionColumn	Partição	Nome da coluna de particionamento recomendado.
content.overview.partitionTimeUnit	Partição	Unidade de tempo de particionamento recomendada. Por exemplo, DAY significa que a recomendação é ter partições diárias na coluna recomendada.
content.overview.clusterColumns	Cluster	Nomes das colunas de clustering recomendados.

• Para saber mais sobre outros campos na resposta do recomendador, consulte Recurso REST: projects.locations.recommendersrecommendation.
• Para mais informações sobre o uso da API Recommender, consulte Como usar a API - Recomendações.

Para visualizar os insights da tabela usando a API REST, execute o seguinte comando:

curl
-H "Authorization: Bearer $GCLOUD_AUTH_TOKEN"
-H "x-goog-user-project: PROJECT_NAME" https://recommender.googleapis.com/v1/projects/my-project/locations/us/insightTypes/google.bigquery.table.StatsInsight/insights

Substitua:

• GCLOUD_AUTH_TOKEN: o nome de um token de acesso válido da CLI do gcloud
• PROJECT_NAME: o nome do projeto que contém a tabela do BigQuery

A tabela a seguir descreve os campos importantes da resposta da API Insights:

Propriedade	Relevante para o subtipo	Descrição
content.existingPartitionColumn	Cluster	Coluna de particionamento atual, se houver
content.tableSizeTb	Todos	Tamanho da tabela em terabytes
content.bytesReadMonthly	Todos	Bytes mensais lidos na tabela
content.slotMsConsumedMonthly	Todos	Milissegundos mensais de slot consumidos pela carga de trabalho em execução na tabela
content.queryJobsCountMonthly	Todos	Contagem mensal de jobs em execução na tabela

• Para saber mais sobre outros campos na resposta de insights, consulte Recurso REST: projects.locations.insightTypes.insights.
• Para mais informações sobre o uso de insights, consulte Como usar a API - Insights.

Aplicar recomendações de clusters

Para aplicar as recomendações de cluster, faça o seguinte:

• Aplicar clusters diretamente à tabela original
• Aplicar clusters a uma tabela copiada
• Aplicar clusters em uma visualização materializada

Aplicar clusters diretamente à tabela original

É possível aplicar as recomendações do cluster diretamente a uma tabela atual do BigQuery. Esse método é mais rápido do que aplicar recomendações a uma tabela copiada, mas não preserva uma tabela de backup.

Siga estas etapas para aplicar uma nova especificação de clustering a tabelas não particionadas ou particionadas.

1. Na ferramenta bq, atualize a especificação de clustering da tabela para corresponder ao novo clustering:

    bq update --clustering_fields=CLUSTER_COLUMN DATASET.ORIGINAL_TABLE 

   Substitua:

   • CLUSTER_COLUMN: a coluna que você está agrupando, por exemplo, mycolumn.
   • DATASET: o nome do conjunto de dados que contém a tabela. Por exemplo, mydataset
   • ORIGINAL_TABLE: o nome da tabela original, por exemplo, mytable

   Também é possível chamar o método de API tables.update ou tables.patch para modificar a especificação de clustering.

2. Para agrupar todas as linhas de acordo com a nova especificação de clustering, execute a seguinte instrução UPDATE:

   UPDATE DATASET.ORIGINAL_TABLE SET CLUSTER_COLUMN=CLUSTER_COLUMN WHERE true
   

   Observação: se uma nova especificação de clustering for aplicada a uma tabela que está em armazenamento de longo prazo, a tabela será revertida para o preço de armazenamento ativo. Para mais informações, consulte preços de armazenamento.

Aplicar clusters a uma tabela copiada

Ao aplicar recomendações de cluster a uma tabela do BigQuery, primeiro copie a tabela original e aplique a recomendação à tabela copiada. Esse método garante que os dados originais sejam preservados se você precisar reverter a alteração para a configuração do clustering.

É possível usar esse método para aplicar recomendações de cluster a tabelas não particionadas e particionadas.

1. No console do Google Cloud, acesse a página do BigQuery.

   Ir para o BigQuery

2. No editor de consultas, crie uma tabela vazia com os mesmos metadados (incluindo as especificações de clustering) da tabela original usando o operador LIKE:

   CREATE TABLE DATASET.COPIED_TABLE
   LIKE DATASET.ORIGINAL_TABLE
   

   Substitua:

   • DATASET: o nome do conjunto de dados que contém a tabela. Por exemplo, mydataset
   • COPIED_TABLE: um nome para a tabela copiada, por exemplo, copy_mytable
   • ORIGINAL_TABLE: o nome da tabela original, por exemplo, mytable

3. No console do Google Cloud, abra o editor do Cloud Shell.

   Ativar o Cloud Shell

4. No editor do Cloud Shell, atualize a especificação de cluster da tabela copiada para corresponder ao cluster recomendado usando o comando bq update:

    bq update --clustering_fields=CLUSTER_COLUMN DATASET.COPIED_TABLE 

   Substitua CLUSTER_COLUMN pela coluna em que você está agrupando, por exemplo, mycolumn.

   Também é possível chamar o método de API tables.update ou tables.patch para modificar a especificação de clustering.

5. No editor de consultas, recupere o esquema da tabela com a configuração de particionamento e clustering da tabela original, se houver algum particionamento ou clustering. É possível recuperar o esquema na visualização INFORMATION_SCHEMA.TABLES da tabela original:

   SELECT
     ddl
   FROM
     DATASET.INFORMATION_SCHEMA.TABLES
   WHERE
     table_name = 'DATASET.ORIGINAL_TABLE;'
   

   A saída é a instrução de linguagem de definição de dados (DDL, na sigla em inglês) completa de ORIGINAL_TABLE, incluindo a cláusula PARTITION BY. Para mais informações sobre os argumentos na saída DDL, consulte a instrução CREATE TABLE.

   A saída DDL indica o tipo de particionamento na tabela original:

   Tipo de particionamento	Exemplo de saída
   Não particionado	A cláusula PARTITION BY está ausente.
   Particionado por coluna da tabela	PARTITION BY c0
   	PARTITION BY DATE(c0)
   	PARTITION BY DATETIME_TRUNC(c0, MONTH)
   Particionado por tempo de processamento	PARTITION BY _PARTITIONDATE
   	PARTITION BY DATETIME_TRUNC(_PARTITIONTIME, MONTH)

6. Processar dados na tabela copiada. O processo usado é baseado no tipo de partição.

   • Se a tabela original não estiver particionada ou particionada por uma coluna da tabela, faça o processamento dos dados da tabela original na tabela copiada:

     INSERT INTO DATASET.COPIED_TABLE
     SELECT * FROM DATASET.ORIGINAL_TABLE
     

   • Se a tabela original for particionada por tempo de processamento, siga estas etapas:

     1. Recupere a lista de colunas para formar a expressão de ingestão de dados usando a visualização INFORMATION_SCHEMA.COLUMNS:

        SELECT
        ARRAY_TO_STRING((
        SELECT
          ARRAY(
          SELECT
            column_name
          FROM
            DATASET.INFORMATION_SCHEMA.COLUMNS
          WHERE
            table_name = 'ORIGINAL_TABLE')), ", ")
        

        A saída é uma lista separada por vírgulas de nomes de colunas.

     2. Faça a ingestão dos dados da tabela original na tabela copiada:

        INSERT DATASET.COPIED_TABLE (COLUMN_NAMES, _PARTITIONTIME)
        SELECT *, _PARTITIONTIME FROM DATASET.ORIGINAL_TABLE
        

        Substitua COLUMN_NAMES pela lista de colunas que foram a saída da etapa anterior, separadas por vírgulas, por exemplo, col1, col2, col3.

   Agora você tem uma tabela de cópia em cluster com os mesmos dados da tabela original. Nas próximas etapas, você vai substituir a tabela original por uma nova em cluster.

7. Renomear a tabela original como uma tabela de backup:

   ALTER TABLE DATASET.ORIGINAL_TABLE
   RENAME TO DATASET.BACKUP_TABLE
   

   Substitua BACKUP_TABLE por um nome para sua tabela de backup, por exemplo, backup_mytable.

8. Renomeie a tabela de cópia como a tabela original:

   ALTER TABLE DATASET.COPIED_TABLE
   RENAME TO DATASET.ORIGINAL_TABLE
   

   Sua tabela original está agrupada de acordo com a recomendação do cluster.

Recomendamos que você analise a tabela em cluster para garantir que todas as funções dela funcionem conforme o esperado. Muitas funções de tabela provavelmente estão vinculadas ao ID da tabela, e não ao nome da tabela. Portanto, é recomendável revisar as seguintes funções antes de continuar:

• Acesso e permissões, como permissões do IAM, acesso no nível da linha ou acesso no nível da coluna.
• Artefatos da tabela, como clones de tabelas, snapshots de tabela ou índices de pesquisa.
• O status de qualquer processo de tabela em andamento, como visualizações materializadas ou jobs executados quando você copiou a tabela.
• Capacidade de acessar dados históricos da tabela usando a viagem no tempo.
• Todos os metadados associados à tabela original, por exemplo, table_option_list ou column_option_list. Para mais informações, consulte Instruções da linguagem de definição de dados.

Se surgirem problemas, migre manualmente os artefatos afetados para a nova tabela.

Depois de analisar a tabela em cluster, você tem a opção de excluí-la com o seguinte comando:

    DROP TABLE DATASET.BACKUP_TABLE
    

Aplicar clusters em uma visualização materializada

É possível criar uma visualização materializada da tabela para armazenar dados da tabela original com a recomendação aplicada. Usar visualizações materializadas para aplicar recomendações garante que os dados em cluster sejam atualizados usando atualizações automáticas. Há considerações de preço ao consultar, manter e armazenar visualizações materializadas. Para saber como criar uma visualização materializada em cluster, consulte Visualizações materializadas em cluster.

Aplicar recomendações de partição

Para aplicar recomendações de partição, é necessário aplicar a uma cópia da tabela original. O BigQuery não oferece suporte à alteração de um esquema de particionamento de uma tabela, como mudar uma tabela não particionada para uma tabela particionada, alterar o esquema de particionamento de uma tabela ou criar uma visualização materializada com um esquema de particionamento diferente da tabela base. Só é possível mudar o particionamento de uma tabela em uma cópia dela.

Cuidado: migre os fluxos de trabalho do SQL legado para o GoogleSQL antes de aplicar recomendações de partição. Saiba mais em Limitações.

Aplicar recomendações de partição a uma tabela copiada

Ao aplicar recomendações de partição a uma tabela do BigQuery, primeiro copie a tabela original e aplique a recomendação à tabela copiada. Essa abordagem garante que os dados originais sejam preservados se você precisar reverter uma partição.

O procedimento a seguir usa um exemplo de recomendação para particionar uma tabela pela unidade de tempo da partição DAY.

1. Crie uma tabela copiada usando as recomendações de partição:

   CREATE TABLE DATASET.COPIED_TABLE
   PARTITION BY DATE_TRUNC(PARTITION_COLUMN, DAY)
   AS SELECT * FROM DATASET.ORIGINAL_TABLE
   

   Substitua:

   • DATASET: o nome do conjunto de dados que contém a tabela. Por exemplo, mydataset
   • COPIED_TABLE: um nome para a tabela copiada, por exemplo, copy_mytable
   • PARTITION_COLUMN: a coluna que você está particionando, por exemplo, mycolumn.

   Para mais informações sobre como criar tabelas particionadas, consulte Como criar tabelas particionadas.

2. Renomear a tabela original como uma tabela de backup:

   ALTER TABLE DATASET.ORIGINAL_TABLE
   RENAME TO DATASET.BACKUP_TABLE
   

   Substitua BACKUP_TABLE por um nome para sua tabela de backup, por exemplo, backup_mytable.

3. Renomeie a tabela de cópia como a tabela original:

   ALTER TABLE DATASET.COPIED_TABLE
   RENAME TO DATASET.ORIGINAL_TABLE
   

   Sua tabela original agora está particionada de acordo com a recomendação do cluster.

Recomendamos que você revise a tabela particionada para garantir que todas as funções dela funcionem conforme o esperado. Muitas funções de tabela provavelmente estão vinculadas ao ID da tabela, e não ao nome da tabela. Portanto, é recomendável revisar as seguintes funções antes de continuar:

• Acesso e permissões, como permissões do IAM, acesso no nível da linha ou acesso no nível da coluna.
• Artefatos da tabela, como clones de tabelas, snapshots de tabela ou índices de pesquisa.
• O status de qualquer processo de tabela em andamento, como visualizações materializadas ou jobs executados quando você copiou a tabela.
• Capacidade de acessar dados históricos da tabela usando a viagem no tempo.
• Todos os metadados associados à tabela original, por exemplo, table_option_list ou column_option_list. Para mais informações, consulte Instruções da linguagem de definição de dados.
• Capacidade de usar o SQL legado para gravar os resultados da consulta em tabelas particionadas. O uso do SQL legado não é totalmente compatível com as tabelas particionadas. Uma solução é migrar seus fluxos de trabalho do SQL legado para o GoogleSQL antes de aplicar uma recomendação de partição.

Se surgirem problemas, migre manualmente os artefatos afetados para a nova tabela.

Depois de revisar a tabela particionada, você tem a opção de excluí-la com o seguinte comando:

    DROP TABLE DATASET.BACKUP_TABLE
    

Preços

Para saber mais sobre os preços desse recurso, consulte Visão geral dos preços do Gemini no BigQuery.

Quando você aplica uma recomendação a uma tabela, é possível que haja os seguintes custos:

• Custos de processamento. Ao aplicar uma recomendação, você executa uma consulta de linguagem de definição de dados (DDL, na sigla em inglês) ou linguagem de manipulação de dados (DML, na sigla em inglês) no seu projeto do BigQuery.
• Custos de armazenamento. Caso use o método de cópia de uma tabela, você usará armazenamento extra para a tabela copiada (ou de backup).

As cobranças padrão de processamento e armazenamento são aplicáveis dependendo da conta de faturamento associada ao projeto. Para mais informações, consulte preços do BigQuery.

Cotas e limites

Para informações sobre cotas e limites desse recurso, consulte Cotas do Gemini no BigQuery.

Solução de problemas

Problema: nenhuma recomendação é exibida para uma tabela específica.

As recomendações de particionamento e cluster podem não aparecer nas seguintes circunstâncias:

• A tabela tiver menos de 10 GB;
• A tabela tem um alto custo de gravação de operações de linguagem de manipulação de dados (DML, na sigla em inglês).
• A tabela não foi lida nos últimos 30 dias.
• A economia mensal estimada é muito insignificante (menos de 1 hora de slot de economia).
• A tabela já está em cluster.

Observação: as tabelas não em cluster e não particionadas podem receber recomendações de cluster e partição. As tabelas não em cluster, mas particionadas, só podem receber recomendações de cluster. As tabelas em cluster não recebem nenhuma recomendação.