O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Introdução às rotinas

Ao criar rotinas no BigQuery, é possível encapsular lógicas complexas usando funções reutilizáveis e procedimentos armazenados. Escolher a rotina certa para sua carga de trabalho permite agregar dados de maneira eficiente, automatizar tarefas de gerenciamento e integrar serviços externos diretamente das suas consultas.

Rotinas compatíveis

O BigQuery é compatível com as seguintes rotinas:

Como escolher uma rotina

Nesta seção, descrevemos os fatores a serem considerados ao escolher uma rotina e comparamos as rotinas por tarefa.

Fatores a considerar

Para escolher uma rotina, considere os seguintes fatores, 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ária ou persistente.
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
Criar funções que realizam tarefas de uso geral no BigQuery.	UDF em SQL ou JavaScript UDAF em SQL ou JavaScript
Crie funções que executam tarefas de uso geral no BigQuery e que se comunicam com sistemas externos Google Cloud usando uma conexão a recursos do Cloud.	UDF do Python
Criar funções que agregam dados.	UDAFs
Criar uma tabela usando parâmetros.	Funções de tabela
Criar funções que usam linguagens, bibliotecas ou serviços que não sã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 processual. É 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)

Uma UDF permite criar uma função usando uma expressão SQL, um código JavaScript ou um código Python. As UDFs 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 criada, a rotina de mascaramento personalizada 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 SQL também podem retornar o valor de uma subconsulta escalar.
As UDFs baseadas em JavaScript permitem chamar o código escrito em JavaScript a partir 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 essas UDFs, é possível implementar uma função em Python e usá-la em uma consulta SQL.
- É possível acessar um serviço do Google Cloud ou um serviço externo de uma UDF do Python usando a conta de serviço de conexão a recursos do Cloud.
- Também é possível instalar bibliotecas de terceiros do índice de pacotes do Python (PyPI).

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 de agregação definidas pelo usuário (UDAFs)

Uma UDAF permite criar uma função de agregação usando uma expressão que contém código SQL ou JavaScript. Uma 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 SQL

As UDAFs do SQL normalmente agregam parâmetros de função em todas as linhas de um grupo. No entanto, é possível 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 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 normalmente usam mais recursos, consulte estas dicas de desempenho.

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 entre uma UDF e uma UDAF depende da tarefa específica que você está tentando realizar.

Para realizar 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 do Python não são compatíveis com o VPC Service Controls ou com as 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 as UDAFs têm as seguintes diferenças:

Atributo	UDFs	UDAFs
Definição	As funções definidas pelo usuário (UDFs) aceitam colunas de entrada, executam 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, em seguida, 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.	Pode ser temporário ou permanente. É 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âmetro que estão em conformidade 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 fornece uma dica ao BigQuery sobre se o resultado da consulta pode ser armazenado em cache.	As UDAFs em SQL e JavaScript aceitam valores de parâmetros que estão em conformidade com os tipos de dados do GoogleSQL para BigQuery. Os parâmetros de função podem ser agregados ou não.
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, na sigla em inglês), é uma UDF que retorna uma tabela. É possível usar uma função de tabela em qualquer lugar em que uma tabela possa ser usada. As funções de tabela se comportam de maneira semelhante às visualizações, mas uma função de tabela pode assumir parâmetros.

É possível fazer o seguinte com as funções de tabela:

Transmita vários parâmetros.
Chame uma função de tabela em qualquer contexto em que uma tabela seja válida.
Mesclar a saída de uma função de tabela com 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

As funções remotas permitem 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 as UDFs do BigQuery.

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

As tarefas a seguir são exemplos do que você pode fazer com as funções remotas:

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

Crie o endpoint HTTP no Cloud Run functions ou no Cloud Run.
Crie uma função remota no BigQuery usando o tipo de conexão CLOUD_RESOURCE.
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:

Recebe argumentos de entrada e retorna valores como saída.
Acessar ou modificar dados em vários conjuntos de dados por vários usuários.
Contém 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 compatíveis. Esses procedimentos têm cotas e limites.

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

Usar rotinas com agentes de IA

Se você criar agentes de IA que funcionam com dados do BigQuery, eles poderão recuperar metadados de rotina do Knowledge Catalog, incluindo os argumentos, o tipo de retorno e o código-fonte da rotina, para entender o que uma rotina faz e como chamá-la. Para mais informações, consulte Recuperar contexto para rotinas.