Personalizar funções do Python para BigQuery DataFrames

Ao personalizar funções do Python para o BigQuery DataFrames, é possível transformar seu código em artefatos escalonáveis do BigQuery, como funções definidas pelo usuário (UDFs) ou funções remotas. É possível implantar essas funções personalizadas para aproveitar as bibliotecas de código aberto e realizar operações além dos recursos das APIs SQL padrão.

Funções exigidas

Para receber as permissões necessárias para realizar as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

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

Com as UDFs (pré-lançamento), é possível transformar sua função personalizada do Python em uma UDF do Python. Para ver um exemplo de uso, consulte Criar uma UDF persistente em Python.

A criação de uma UDF no BigQuery DataFrames cria uma rotina do BigQuery como a UDF do Python no conjunto de dados especificado. Para ver um conjunto completo de parâmetros compatíveis, consulte bigframes.pandas.udf.

Requisitos

Para usar uma UDF do BigQuery DataFrames, ative a API BigQuery no seu projeto. Se você fornecer o parâmetro bigquery_connection no projeto, também será necessário ativar a API BigQuery Connection.

Limpar

Além de limpar os artefatos de nuvem diretamente no console do Google Cloud ou com outras ferramentas, é possível limpar as UDFs do BigQuery DataFrames que foram criadas com um argumento de nome explícito usando o comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitações

  • O código na UDF precisa ser autônomo, ou seja, não pode conter referências a uma importação ou variável definida fora do corpo da função.
  • O código na UDF precisa ser compatível com o Python 3.11, já que esse é o ambiente em que o código é executado na nuvem.
  • Executar novamente o código de definição da UDF após alterações triviais no código da função, como renomear uma variável ou inserir uma nova linha, faz com que a UDF seja recriada, mesmo que essas alterações não tenham consequências para o comportamento da função.
  • O código do usuário fica visível para usuários com acesso de leitura nas rotinas do BigQuery. Portanto, inclua conteúdo confidencial apenas com cuidado.
  • Um projeto pode ter até 1.000 funções do Cloud Run por vez em um local do BigQuery.

A UDF do BigQuery DataFrames implanta uma função do BigQuery em Python definida pelo usuário, e as limitações relacionadas se aplicam.

Funções remotas

Com o BigQuery DataFrames, é possível transformar as funções escalares personalizadas em funções remotas do BigQuery. Para ver um exemplo de uso, consulte Criar uma função remota. Para ver um conjunto completo de parâmetros compatíveis, consulte remote_function.

Ao criar uma função remota no BigQuery DataFrames, você cria o seguinte:

  • Uma função do Cloud Run.

  • Uma conexão com o BigQuery

    Por padrão, uma conexão com o nome bigframes-default-connection é usada. Se preferir, use uma conexão pré-configurada do BigQuery. Nesse caso, a criação da conexão é ignorada. A conta de serviço da conexão padrão recebe o papel do Cloud Run (roles/run.invoker).

  • Uma função remota do BigQuery que usa a função do Cloud Run criada com a conexão do BigQuery.

Requisitos

Para usar as funções remotas do BigQuery DataFrames, ative as seguintes APIs:

Ao usar as funções remotas do BigQuery DataFrames, você precisa do papel de Administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) se estiver usando uma conexão padrão do BigQuery ou do papel de Navegador (roles/browser) se estiver usando uma conexão pré-configurada. Para evitar esse requisito, defina a opção bigframes.pandas.options.bigquery.skip_bq_connection_check como True. Nesse caso, a conexão (padrão ou pré-configurada) será usada no estado em que se encontra, sem qualquer existência ou verificação de permissão. Se você estiver usando a conexão pré-configurada e pulando a verificação de conexão, verifique o seguinte:

  • A conexão é criada no local certo.
  • Se você estiver usando as funções remotas do BigQuery DataFrames, a conta de serviço terá o papel de invocador do Cloud Run (roles/run.invoker) no projeto.

Ver e gerenciar conexões

As conexões do BigQuery são criadas no mesmo local que a sessão do BigQuery DataFrames, usando o nome que você informou na definição da função personalizada. Para visualizar e gerenciar conexões, faça o seguinte:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. Selecione o projeto em que você criou a função remota.

  3. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

  4. No painel Explorer, expanda o projeto e clique em Conexões.

As funções remotas do BigQuery são criadas no conjunto de dados que você especificar ou em um conjunto de dados anônimo, que é um tipo de conjunto de dados oculto. Se você não definir um nome para uma função remota durante a criação, o BigQuery DataFrames vai aplicar um nome padrão que começa com o prefixo bigframes. Para visualizar e gerenciar funções remotas criadas em um conjunto de dados especificado pelo usuário, faça o seguinte:

  1. No console do Google Cloud , acesse a página BigQuery.

    Acessar o BigQuery

  2. Selecione o projeto em que você criou a função remota.

  3. No painel à esquerda, clique em Explorer:

    Botão destacado para o painel "Explorer".

  4. No painel Explorer, expanda o projeto e clique em Conjuntos de dados.

  5. Clique no conjunto de dados em que você criou a função remota.

  6. Clique na guia Rotinas.

Para conferir e gerenciar as funções do Cloud Run, faça o seguinte:

  1. Acessar a página Cloud Run

    Acessar o Cloud Run

  2. Selecione o projeto em que você criou a função.

  3. Na lista de serviços disponíveis, filtre por Tipo de implantação de função.

  4. Para identificar funções criadas pelo BigQuery DataFrames, procure nomes de funções com o prefixo bigframes.

Limpar

Além de limpar os artefatos de nuvem diretamente no console do Google Cloud ou com outras ferramentas, é possível limpar as funções remotas do BigQuery que foram criadas sem um argumento de nome explícito e as funções do Cloud Run associadas das seguintes maneiras:

  • Para uma sessão do BigQuery DataFrames, use o comando session.close().
  • Para a sessão padrão do BigQuery DataFrames, use o comando bigframes.pandas.close_session().
  • Para uma sessão anterior com session_id, use o comando bigframes.pandas.clean_up_by_session_id(session_id).

Também é possível limpar as funções remotas do BigQuery que foram criadas com um argumento de nome explícito e as funções do Cloud Run associadas usando o comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitações

  • As funções remotas levam cerca de 90 segundos para ficar disponíveis quando você as cria pela primeira vez. Outras dependências de pacotes podem aumentar a latência.
  • Executar novamente o código de definição da função remota após alterações triviais no código da função e ao redor dele, como renomear uma variável, inserir uma nova linha ou inserir uma nova célula no notebook, pode fazer com que a função remota seja recriada, mesmo que essas alterações não sejam importantes para o comportamento da função.
  • O código do usuário fica visível para usuários com acesso de leitura às funções do Cloud Run. Portanto, inclua conteúdo sensível com cautela.
  • Um projeto pode ter até 1.000 funções do Cloud Run por vez em uma região. Para mais informações, consulte Cotas.

A seguir