Esta página foi traduzida pela API Cloud Translation.

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 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 implementado.
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ária para a rotina: em consultas únicas ou múltiplas.
Considerações sobre desempenho.
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 executam tarefas de uso geral no BigQuery.	UDF de SQL ou JavaScript UDAF do SQL ou JavaScript
Crie funções que executam tarefas de uso geral no BigQuery e se comunicam com sistemas Trusted Cloud by S3NS externos usando uma conexão de recursos do Cloud.	UDF em Python
Crie funções que agregam dados.	UDAFs
Crie uma tabela usando parâmetros.	Funções de tabela
Crie funções que usam linguagens, bibliotecas ou serviços que não têm suporte no BigQuery. Essas funções se integram diretamente às funções do Cloud Run 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`. Crie e chame 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. 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 existem apenas no escopo de uma única consulta.

É possível criar UDFs para usar com rotinas de mascaramento personalizadas, que retornam o valor de uma coluna após a aplicação de uma UDF. Depois de criar a rotina de mascaramento personalizada, ela fica disponível como uma regra de mascaramento em Criar políticas de dados.

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

UDFs com base na 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 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 essas UDFs, você pode implementar uma função no Python e usá-la em uma consulta SQL.
- É possível acessar um serviço Trusted Cloud ou um serviço externo em um UDF do Python usando a conta de serviço da conexão de recursos do Cloud.
- Também é possível instalar bibliotecas de terceiros no índice de pacotes do Python (PyPI).

UDFs enviadas 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 de código aberto bigquery-utils do GitHub.

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

Com uma UDAF, é possível criar uma função agregada 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 a Observabilidade do Google Cloud ou aplicativos semelhantes.

Para saber mais, acesse os recursos a seguir:

UDAFs do SQL

Os 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 do JavaScript

As UDAFs em JavaScript podem incluir bibliotecas em 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 performance pode ser útil.

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

Comparar UDFs e UDAFs

A escolha de um UDF em vez de um 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 um 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 letras maiúsculas, use um UDF.

As UDFs e as 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 a Observabilidade do Google Cloud ou aplicativos semelhantes. A exceção são os UDFs do Python, que podem acessar serviços externos usando uma conexão de recurso do Cloud. No entanto, os UDFs do Python não oferecem suporte a VPC Service Controls ou chaves de criptografia gerenciadas pelo cliente (CMEK, na sigla em inglês).
As UDAFs têm as mesmas limitações que as UDFs, além de algumas outras.
UDFs e UDAFs têm as mesmas cotas e limites.

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

Atributo	UDFs	UDAFs (link em inglês)
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	Podem ser temporárias 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 persistentes, não temporárias.	Podem ser temporárias ou permanentes. É possível usar UDAFs persistentes em várias consultas. É possível usar UDAFs temporários apenas para uma única consulta, script, sessão ou procedimento. UDAFs persistentes podem ser chamados com segurança quando compartilhados entre proprietários.
Argumentos e tipos de dados	As UDFs aceitam valores de parâmetro que estão em conformidade com o GoogleSQL para tipos de dados do 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 de 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, transformação e validação de dados.	As UDAFs são usadas geralmente 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 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.

É 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.
Junte 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

As funções remotas permitem implementar a função em outras linguagens além do SQL e do JavaScript ou usar bibliotecas ou serviços que não têm suporte nas UDFs do BigQuery.

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

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

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

Crie o endpoint HTTP nas funções do Cloud Run 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 SQL é um conjunto de instruções que podem ser chamadas de 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 procedural, que permitem fazer coisas como 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.
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 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 de SQL.