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.

Funções definidas pelo utilizador em Python

Uma função definida pelo utilizador (FDU) em Python permite-lhe implementar uma função escalar em Python e usá-la numa consulta SQL. As UDFs Python são semelhantes às UDFs SQL e Javascript, mas com capacidades adicionais. As UDFs Python permitem-lhe instalar bibliotecas de terceiros a partir do Python Package Index (PyPI) e aceder a serviços externos através de uma ligação de recursos do Google Cloud.

As UDFs Python são criadas e executadas em recursos geridos do BigQuery.

Limitações

python-3.11 é o único tempo de execução suportado.
Não pode criar uma UDF Python temporária.
Não pode usar uma UDF Python com uma vista materializada.
Os resultados de uma consulta que chama uma FDU Python não são colocados em cache porque se assume sempre que o valor de retorno de uma FDU Python é não determinístico.
As UDFs Python não são totalmente suportadas em INFORMATION_SCHEMA vistas.
Não pode criar nem atualizar uma UDF do Python através da API Routine.
Os VPC Service Controls não são suportados.
As chaves de encriptação geridas pelo cliente (CMEK) não são suportadas.
Estes tipos de dados não são suportados: JSON, RANGE, INTERVAL e GEOGRAPHY.
Os contentores que executam UDFs Python só podem ser configurados com até 2 vCPUs e 8 Gi.

Funções de IAM necessárias

As funções de IAM necessárias baseiam-se no facto de ser proprietário ou utilizador de uma UDF de Python. Normalmente, um proprietário de UDFs Python cria ou atualiza uma UDF. Um utilizador de UDFs Python invoca uma UDF criada por outra pessoa.

Também são necessárias funções adicionais se criar ou executar uma UDF Python que faça referência a uma ligação de recursos da nuvem.

Proprietários de FDU

Se estiver a criar ou atualizar uma FDU do Python, devem ser concedidas as seguintes funções do IAM predefinidas no recurso adequado:

Função	Autorizações necessárias	Recurso
Editor de dados do BigQuery (`roles/bigquery.dataEditor`)	`bigquery.routines.create` para criar uma FDU do Python com a declaração `CREATE FUNCTION`. `bigquery.routines.update` para atualizar uma FDU Python com a declaração `CREATE FUNCTION`.	O conjunto de dados onde a UDF Python é criada ou atualizada.
Utilizador de tarefas do BigQuery (`roles/bigquery.jobUser`)	`bigquery.jobs.create` para executar uma tarefa de consulta de declaração.`CREATE FUNCTION`	O projeto onde está a executar a declaração `CREATE FUNCTION`.
Administrador da ligação do BigQuery (`roles/bigquery.connectionAdmin`)	`bigquery.connections.create` só é necessário para criar uma nova ligação de recursos do Google Cloud. `bigquery.connections.delegate` para usar uma associação na declaração `CREATE FUNCTION`.	A ligação que está a dar acesso a um recurso externo. Esta ligação só é necessária se a sua FDU usar a cláusula `WITH CONNECTION` para aceder a um serviço externo.

Utilizadores de FDUs

Se estiver a invocar uma UDF Python, devem ser concedidos os seguintes papéis do IAM predefinidos no recurso adequado:

Função	Autorizações necessárias	Recurso
Utilizador do BigQuery (`roles/bigquery.user`)	`bigquery.jobs.create` para executar uma tarefa de consulta que faça referência à UDF.	O projeto onde está a executar uma tarefa de consulta que invoca a UDF do Python.
Visualizador de dados do BigQuery (`roles/bigquery.dataViewer`)	`bigquery.routines.get` para executar uma FDU criada por outra pessoa.	O conjunto de dados onde a UDF Python está armazenada.
Utilizador de ligação do BigQuery (`roles/bigquery.connectionUser`)	`bigquery.connections.use` para executar uma UDF Python que faça referência a uma ligação de recursos da nuvem.	A ligação de recursos da nuvem referenciada pela UDF Python. Esta ligação só é necessária se a sua FDU referenciar uma ligação.

Para mais informações sobre as funções no BigQuery, consulte o artigo Funções do IAM predefinidas.

Crie uma FDU Python persistente

Siga estas regras quando criar uma FDU do Python:

O corpo da UDF Python tem de ser um literal de string entre aspas que represente o código Python. Para saber mais sobre os literais de strings entre aspas, consulte Formatos para literais entre aspas.
O corpo da FDU Python tem de incluir uma função Python que é usada no argumento entry_point na lista de opções da FDU Python.
Tem de especificar uma versão de tempo de execução do Python na opção runtime_version. A única versão do tempo de execução do Python suportada é a python-3.11. Para ver uma lista completa das opções disponíveis, consulte a lista de opções de funções para a declaração CREATE FUNCTION.

Para criar uma FDU Python persistente, use a declaração CREATE FUNCTION sem a palavra-chave TEMP ou TEMPORARY. Para eliminar uma UDF Python persistente, use a declaração DROP FUNCTION.

Quando cria uma FDU Python com a declaração CREATE FUNCTION, o BigQuery cria ou atualiza uma imagem de contentor baseada numa imagem base. O contentor é criado na imagem de base com o seu código e todas as dependências de pacotes especificadas. A criação do contentor é um processo de longa duração. A primeira consulta após executar a declaração CREATE FUNCTION pode aguardar automaticamente que a imagem seja concluída. Sem dependências externas, a imagem do contentor deve ser criada, normalmente, em menos de um minuto.

Exemplo

Para ver um exemplo de criação de uma UDF Python persistente, escolha uma das seguintes opções:

Consola

O exemplo seguinte cria uma FDU Python persistente denominada multiplyInputs e chama a FDU a partir de uma declaração SELECT:

Aceda à página do BigQuery.

Aceda ao BigQuery

No editor de consultas, introduza a seguinte declaração CREATE FUNCTION:

CREATE FUNCTION `PROJECT_ID.DATASET_ID`.multiplyInputs(x FLOAT64, y FLOAT64)
RETURNS FLOAT64
LANGUAGE python
OPTIONS(runtime_version="python-3.11", entry_point="multiply")
AS r'''

def multiply(x, y):
  return x * y

''';

-- Call the Python UDF.
WITH numbers AS
  (SELECT 1 AS x, 5 as y
  UNION ALL
  SELECT 2 AS x, 10 as y
  UNION ALL
  SELECT 3 as x, 15 as y)
SELECT x, y,
`PROJECT_ID.DATASET_ID`.multiplyInputs(x