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 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), você pode 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 BigQuery DataFrames 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 Cloud de Confiance ou com outras ferramentas, é possível limpar as UDFs do BigQuery DataFrames que foram criadas com um argumento de nome explícito usando o comandobigframes.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 BigQuery DataFrames, 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 BigQuery DataFrames, 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. É possível evitar esse requisito definindo 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á 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 Cloud de Confiance , 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 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 Cloud de Confiance , 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 Cloud de Confiance 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 às 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