Introdução às rotinas

Este documento descreve como escolher uma rotina, que é um tipo de recurso usado para criar funções ou procedimentos armazenados no BigQuery.

Rotinas compatíveis

O BigQuery é compatível com as seguintes rotinas:

Como escolher uma rotina

Esta seção descreve os fatores a serem considerados ao escolher uma rotina e compara as rotinas por tarefa.

Fatores a considerar

Para escolher uma rotina, considere os seguintes fatores, que são descritos nas seções de cada tipo de rotina:

  • O tipo de tarefa a ser implementada.
  • A linguagem de programação a ser usada.
  • O tipo de persistência a ser implementado para a rotina: temporário ou permanente.
  • O tipo de reutilização necessário para a rotina: em uma ou várias consultas.
  • Considerações sobre performance.
  • Como acessar serviços externos.
  • Compartilhar a rotina com os usuários.

Comparar rotinas por tarefa

A tabela a seguir mostra o tipo de tarefa que você pode realizar para cada tipo de rotina:

Tarefa

Tipo de recurso de rotina

Crie funções que realizam tarefas de uso geral no BigQuery.

UDF em SQL ou JavaScript

UDAF SQL ou JavaScript

Crie funções que realizam tarefas de uso geral no BigQuery e que se comunicam com sistemas Google Cloud externos usando uma conexão a recursos do Cloud.

UDF em Python

Crie funções que agreguem dados.

UDAFs

Crie uma tabela usando parâmetros.

Funções de tabela

Crie funções que usam linguagens, bibliotecas ou serviços não compatíveis com o BigQuery. Essas funções se integram diretamente ao Cloud Run functions e ao Cloud Run.

Funções remotas

Execute várias instruções em uma consulta como uma consulta de várias instruções usando a linguagem de procedimentos. É possível usar uma consulta de várias instruções para:

  • Executar várias instruções em uma sequência, com estado compartilhado.
  • Automatizar tarefas de gerenciamento, como criar ou descartar tabelas.
  • Implementar uma lógica complexa usando construções de programação, como IF e WHILE.

Criar e chamar procedimentos armazenados para o Apache Spark no BigQuery.

Procedimentos armazenados

Funções definidas pelo usuário (UDFs)

Com uma UDF, é possível criar uma função usando uma expressão SQL, um código JavaScript ou um código Python. Elas aceitam colunas de entrada, executam ações na entrada e retornam o resultado dessas ações como um valor.

É possível definir UDFs como permanentes ou temporárias. É possível reutilizar UDFs permanentes em várias consultas, enquanto as UDFs temporárias só existem no escopo de uma única consulta.

Crie UDFs para usar com rotinas de mascaramento personalizadas, que retornam o valor de uma coluna depois de aplicar uma UDF a ela. Depois de criar a rotina de mascaramento personalizada, ela estará disponível como uma regra de mascaramento em Criar políticas de dados.

Para mais informações sobre UDFs, consulte os seguintes recursos:

UDFs baseadas em linguagem

  • As UDFs baseadas em SQL são compatíveis com parâmetros de UDF com modelo, que podem corresponder a mais de um tipo de argumento quando a UDF é chamada. As UDFs do SQL também podem retornar o valor de uma subconsulta escalar.
  • As UDFs baseadas em JavaScript permitem chamar o código escrito em JavaScript de uma consulta SQL.
    • As UDFs de JavaScript normalmente consomem mais recursos de slot do que as consultas SQL padrão, diminuindo o desempenho do job.
    • Se a função puder ser expressa em SQL, geralmente é mais conveniente executar o código como um job de consulta SQL padrão.
  • As UDFs baseadas em Python são criadas e executadas em recursos gerenciados do BigQuery. Com elas, é possível implementar uma função em Python e usá-la em uma consulta SQL.

UDFs fornecidas pela comunidade

Além das UDFs que você cria, as UDFs com contribuição da comunidade estão disponíveis no conjunto de dados públicos bigquery-public-data.persistent_udfs e no repositório do bigquery-utils do GitHub (em inglês) de código aberto.

Funções agregadas definidas pelo usuário (UDAFs)

Um UDAF permite criar uma função de agregação usando uma expressão que contém código SQL ou JavaScript. Um UDAF aceita colunas de entrada, realiza um cálculo em um grupo de linhas por vez e, em seguida, retorna o resultado desse cálculo como um único valor.

As UDAFs não podem modificar dados, se comunicar com sistemas externos ou enviar registros para o Google Cloud Observability ou aplicativos semelhantes.

Para saber mais, acesse os recursos a seguir:

UDAFs de SQL

As UDAFs do SQL normalmente agregam parâmetros de função em todas as linhas de um grupo. No entanto, você pode especificar um parâmetro de função como não agregado usando a palavra-chave NOT AGGREGATE. Um parâmetro de função não agregada é um parâmetro de função escalar com um valor constante para todas as linhas em um grupo. Os UDAFs do SQL podem conter parâmetros agregados e não agregados.

UDAFs em JavaScript

As UDAFs em JavaScript podem incluir bibliotecas JavaScript. O corpo da função JavaScript pode incluir código JavaScript personalizado, como variáveis globais JavaScript e funções personalizadas.

Como as funções baseadas em JavaScript geralmente usam mais recursos, consultar estas dicas de desempenho pode ser útil.

As UDAFs em JavaScript têm algumas restrições. Apenas codificações de tipo específicas são permitidas, e há requisitos para serialização e desserialização.

Comparar UDFs e UDAFs

A escolha de uma UDF em vez de uma UDAF depende da tarefa específica que você está tentando realizar.

  • Para fazer um cálculo ou uma transformação em valores de dados individuais, use uma UDF.
  • Para fazer o mesmo em grupos de valores de dados, use uma UDAF.

Por exemplo, se você quiser calcular a média de uma coluna de números, use uma UDAF. Se você quiser converter uma coluna de strings em maiúsculas, use uma UDF.

As UDFs e UDAFs têm as seguintes semelhanças:

  • As UDFs e UDAFs não podem modificar dados, se comunicar com sistemas externos ou enviar registros para o Google Cloud Observability ou aplicativos semelhantes. A exceção são as UDFs do Python, que podem acessar serviços externos usando uma conexão a recursos do Cloud. No entanto, as UDFs em Python não são compatíveis com VPC Service Controls nem com chaves de criptografia gerenciadas pelo cliente (CMEK).
  • As UDAFs têm as mesmas limitações que as UDFs, além de algumas outras.
  • As UDFs e UDAFs têm as mesmas cotas e limites.

As UDFs e UDAFs têm as seguintes diferenças:

Atributo

UDFs

UDAFs

Definição

As funções definidas pelo usuário (UDFs) aceitam colunas de entrada, realizam ações na entrada e retornam o resultado dessas ações como um valor.

As funções de agregação definidas pelo usuário (UDAFs) aceitam colunas de entrada, realizam um cálculo em um grupo de linhas por vez e retornam o resultado desse cálculo como um único valor.

Linguagens compatíveis

SQL, JavaScript e Python

SQL e JavaScript

Persistência
  • Podem ser temporários ou permanentes.
  • É possível usar UDFs permanentes em várias consultas.
  • As UDFs temporárias só podem ser usadas em uma única consulta.
  • As UDFs do Python só podem ser permanentes, não temporárias.
  • Podem ser temporários ou permanentes.
  • É possível usar UDAFs permanentes em várias consultas.
  • É possível usar UDAFs temporárias apenas para uma única consulta, script, sessão ou procedimento.
  • UDAFs persistentes podem ser chamados com segurança quando são compartilhados entre os proprietários.

Argumentos e tipos de dados

As UDFs aceitam valores de parâmetros que estão de acordo com os tipos de dados do GoogleSQL para BigQuery. Alguns tipos do SQL têm um mapeamento direto para os tipos do JavaScript, mas outros não. Consulte os tipos compatíveis com JavaScript.

Para uma UDF do SQL, os valores de parâmetro podem ser ANY TYPE, que podem corresponder a mais de um tipo de argumento quando a função é chamada.

Somente as UDFs em JavaScript têm um especificador de determinismo que indica ao BigQuery se o resultado da consulta pode ser armazenado em cache.

As UDAFs em SQL e JavaScript aceitam valores de parâmetros que estão de acordo com os tipos de dados do GoogleSQL para BigQuery.

Os parâmetros de função podem ser agregados ou não agregados.

Uso

As UDFs são usadas com frequência para limpeza de dados, transformação e validação.

As UDAFs são usadas com frequência para calcular estatísticas de resumo, como médias, somas e contagens.

Funções de tabela

Uma função de tabela, também chamada de função com valor de tabela (TVF), é uma UDF que retorna uma tabela. É possível usar uma função de tabela em qualquer lugar em que seja possível usar uma tabela. As funções de tabela se comportam de maneira semelhante às visualizações, mas uma função de tabela pode assumir parâmetros.

Com as funções de tabela, é possível fazer o seguinte:

  • Transmita vários parâmetros.
  • Chamar uma função de tabela em qualquer contexto em que uma tabela seja válida.
  • Unir a saída de uma função de tabela a outra tabela.
  • Use uma função de tabela em uma subconsulta.

Para mais informações sobre funções de tabela, consulte Funções de tabela, Limitações e Cotas e limites.

Funções remotas

Com as funções remotas, é possível implementar sua função em linguagens diferentes de SQL e JavaScript ou usar bibliotecas ou serviços que não são compatíveis com UDFs do BigQuery.

Uma função remota do BigQuery integra sua função do GoogleSQL com as funções do Cloud Run e o Cloud Run usando qualquer linguagem compatível e, em seguida, invoca essas funções em consultas SQL do Google.

Confira alguns exemplos de tarefas que você pode realizar com funções remotas:

Para criar uma função remota, siga estas etapas:

  1. Crie o endpoint HTTP nas funções do Cloud Run ou no Cloud Run.
  2. Crie uma função remota no BigQuery usando o tipo de conexão CLOUD_RESOURCE.
  3. Use a função remota em uma consulta como qualquer outra UDF para o BigQuery.

Para mais informações sobre funções remotas, consulte Funções remotas, Limitações e Cotas e limites.

Procedimentos armazenados

Um procedimento armazenado em SQL é um conjunto de instruções que podem ser chamadas em outras consultas ou outros procedimentos armazenados. Nomeie e armazene um procedimento em um conjunto de dados do BigQuery.

Os procedimentos armazenados são compatíveis com instruções de linguagem processual, que permitem definir variáveis e implementar o fluxo de controle. Saiba mais sobre declarações de linguagem processual na Referência de linguagem processual.

Um procedimento armazenado pode fazer o seguinte:

  • Receber argumentos de entrada e retornar valores como saída.
  • Acessar ou modificar dados em vários conjuntos de dados por vários usuários.
  • Conter uma consulta de várias instruções.

Alguns procedimentos armazenados são integrados ao BigQuery e não precisam ser criados. Eles são chamados de procedimentos do sistema. Saiba mais sobre eles na Referência de procedimentos do sistema.

Os procedimentos armazenados para o Spark no BigQuery também são aceitos. Esses procedimentos têm cotas e limites.

Para saber mais sobre procedimentos armazenados, consulte Procedimentos armazenados de SQL.