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 a 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 oferece suporte às 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 serem considerados

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 consultas únicas ou múltiplas.
Considerações sobre a performance.
Como acessar serviços externos.
Como compartilhar a rotina com os usuários.

Comparar rotinas por tarefa

A tabela a seguir mostra o tipo de tarefas que podem ser realizadas para cada tipo de rotina:

Tarefa	Tipo de recurso de rotina
Criar funções que realizam tarefas de uso geral no BigQuery.	UDF SQL ou JavaScript UDAF SQL ou JavaScript
Criar funções que realizam tarefas de uso geral em BigQuery e que se comunicam com sistemas Google Cloud externos usando uma conexão a recursos do Cloud.	UDF 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 não compatíveis com o BigQuery. Essas funções se integram diretamente ao Cloud Run functions e ao Cloud Run.	Funções remotas
Executar várias instruções em uma consulta como uma consulta de várias instruções usando linguagem processual. É possível usar uma consulta de várias instruções para fazer o seguinte: 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 em 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.

É possível criar UDFs para uso com rotinas de mascaramento personalizadas, que retornam o valor de uma coluna depois de aplicar uma UDF à coluna. 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 oferecem suporte a 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 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. Essas UDFs permitem implementar uma função em Python e usá-la em uma consulta SQL.
- É possível acessar um Google Cloud serviço ou um serviço externo serviço de uma UDF Python usando a conta de serviço de conexão a recursos do Cloud.
- Também é possível instalar bibliotecas de terceiros no índice de pacotes do Python (PyPI).

UDFs com contribuição da comunidade

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

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

Um UDAF permite criar uma função agregada 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 SQL

As UDAFs 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. As UDAFs SQL podem conter parâmetros agregados e não agregados.

UDAFs JavaScript

As UDAFs 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, consultar estas dicas de performance pode ser útil.

As UDAFs 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 realizar um cálculo ou 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 Python, que podem acessar serviços externos usando uma conexão a recursos do Cloud. No entanto, as UDFs Python não oferecem suporte a controles de serviço de VPC ou 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, executam ações na entrada e retornam o resultado dessas ações como um valor.	As funções agregadas 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	Pode ser temporário ou permanente. É possível usar UDFs permanentes em várias consultas. É possível usar UDFs temporárias apenas para uma única consulta. As UDFs 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. As UDAFs permanentes são seguras para serem chamadas quando são compartilhadas entre proprietários.
Argumentos e tipos de dados	As UDFs aceitam valores de parâmetros que estão em conformidade com o GoogleSQL para BigQuery tipos de dados. Alguns tipos de SQL têm um mapeamento direto para tipos de JavaScript, mas outros não. Consulte os tipos compatíveis com JavaScript. Para uma UDF SQL, os valores de parâmetro podem ser `ANY TYPE`, que pode corresponder a mais de um tipo de argumento quando a função é chamada. Somente as UDFs 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 SQL e JavaScript aceitam valores de parâmetros que estão em conformidade com GoogleSQL para tipos de dados do 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 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 funções de tabela:

Transmitir 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.
Usar 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 a 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 SQL do Google com Cloud Run Functions e Cloud Run usando qualquer linguagem compatível e, em seguida, invoca essas funções em consultas SQL do Google.

As tarefas a seguir são exemplos do que é possível fazer com funções remotas:

Analisar dados não estruturados em tabelas de objetos.
Realizar a tradução de conteúdo.

A criação de uma função remota exige as seguintes 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 do 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 processual.

Um procedimento armazenado pode fazer o seguinte:

Aceitar 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, e é possível saber mais sobre eles em Referência de procedimentos do sistema.

Os procedimentos armazenados para 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 em SQL.

Usar rotinas com agentes de IA

Se você criar agentes de IA que funcionam com dados do BigQuery, os agentes 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.