Personalizar funções do Python para o BigQuery DataFrames

Com o BigQuery DataFrames, é possível transformar suas funções personalizadas do Python em artefatos do BigQuery que podem ser executados em objetos do BigQuery DataFrames em grande escala. Com esse suporte à extensibilidade, é possível realizar operações além do que é possível com as APIs do BigQuery DataFrames e do SQL. Assim, você pode aproveitar as bibliotecas de código aberto.

Há duas variantes desse mecanismo de extensibilidade: funções definidas pelo usuário e funções remotas.

Funções exigidas

Para conseguir as permissões necessárias a fim de concluir as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM no 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évia), é possível transformar sua função personalizada do Python em uma UDF do Python. Para um exemplo de uso, consulte Criar uma UDF permanente em Python.

A criação de uma UDF nos DataFrames do BigQuery cria uma rotina do BigQuery como a UDF do Python no conjunto de dados especificado. Para um conjunto completo de parâmetros aceitos, 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 da nuvem diretamente no console Google Cloud ou com outras ferramentas, é possível limpar as UDFs do DataFrames do BigQuery 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 independente, 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 mudanças 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 mudanças sejam insignificantes para o comportamento da função.
  • O código do usuário fica visível para usuários com acesso de leitura às rotinas do BigQuery. Portanto, inclua conteúdo sensível com cautela.
  • 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 Python do BigQuery 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 um exemplo de uso, consulte Criar uma função remota. Para um conjunto completo de parâmetros compatíveis, consulte remote_function.

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

  • Uma função do Cloud Run.

  • Uma conexão com o BigQuery

    Por padrão, uma conexão chamada 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 DataFrames do BigQuery, ative as seguintes APIs:

Ao usar as funções remotas do BigQuery DataFrames, você precisa da função de administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) se estiver usando uma conexão padrão do BigQuery ou da função 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 sem alterações, sem qualquer verificação de existência ou 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 funções remotas do BigQuery DataFrames, a conta de serviço terá a função 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 DataFrames do BigQuery, 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 especificado 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 dela, o DataFrames do BigQuery 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 da nuvem diretamente no console 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 associadas do Cloud Run 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 associadas do Cloud Run 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 pacote podem aumentar a latência.
  • Executar novamente o código de definição da função remota após mudanças triviais no código da função e ao redor dele (por exemplo, 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 mudanças sejam insignificantes para o comportamento da função.
  • O código do usuário fica visível para usuários com acesso de leitura nas funções do Cloud Run. Portanto, inclua conteúdo sensível apenas 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