Personalizza le funzioni Python per BigQuery DataFrames

BigQuery DataFrames ti consente di trasformare le tue funzioni Python personalizzate in artefatti BigQuery che puoi eseguire su oggetti BigQuery DataFrames su larga scala. Questo supporto dell'estensibilità ti consente di eseguire operazioni che vanno oltre quelle possibili con le API BigQuery DataFrames e SQL, in modo da poter sfruttare potenzialmente le librerie open source.

Esistono due varianti di questo meccanismo di estensibilità: funzioni definite dall'utente e funzioni remote.

Ruoli obbligatori

Per ottenere le autorizzazioni necessarie per completare le attività descritte in questo documento, chiedi all'amministratore di concederti i seguenti ruoli IAM nel tuo progetto:

Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Funzioni definite dall'utente

Con le funzioni definite dall'utente (anteprima), puoi trasformare la tua funzione Python personalizzata in una funzione definita dall'utente Python. Per un esempio di utilizzo, consulta Crea una UDF Python persistente.

La creazione di una funzione definita dall'utente in BigQuery DataFrames crea una routine BigQuery come funzione definita dall'utente Python nel set di dati specificato. Per un insieme completo di parametri supportati, consulta bigframes.pandas.udf.

Requisiti

Per utilizzare una UDF BigQuery DataFrames, abilita l'API BigQuery nel tuo progetto. Se fornisci il parametro bigquery_connection nel tuo progetto, devi anche abilitare l'API BigQuery Connection.

Esegui la pulizia

Oltre a ripulire gli artefatti cloud direttamente nella console Google Cloud o con altri strumenti, puoi ripulire le funzioni definite dall'utente (UDF) di BigQuery DataFrames create con un argomento nome esplicito utilizzando il comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitazioni

  • Il codice nella UDF deve essere autonomo, ovvero non deve contenere riferimenti a un'importazione o a una variabile definita al di fuori del corpo della funzione.
  • Il codice nella UDF deve essere compatibile con Python 3.11, poiché questo è l' ambiente in cui il codice viene eseguito nel cloud.
  • La riesecuzione del codice di definizione della UDF dopo modifiche banali nel codice della funzione, ad esempio la ridenominazione di una variabile o l'inserimento di una nuova riga, comporta la ricreazione della UDF, anche se queste modifiche sono irrilevanti per il comportamento della funzione.
  • Il codice utente è visibile agli utenti con accesso in lettura alle routine BigQuery, pertanto devi includere contenuti sensibili solo con cautela.
  • Un progetto può avere fino a 1000 funzioni Cloud Run contemporaneamente in una località BigQuery.

La UDF BigQuery DataFrames esegue il deployment di una funzione Python BigQuery definita dall'utente e si applicano le limitazioni correlate.

Funzioni remote

BigQuery DataFrames consente di trasformare le funzioni scalari personalizzate in funzioni remote BigQuery. Per un esempio di utilizzo, consulta Crea una funzione remota. Per un insieme completo di parametri supportati, consulta remote_function.

La creazione di una funzione remota in BigQuery DataFrames crea quanto segue:

  • Una funzione Cloud Run.

  • Una connessione BigQuery.

    Per impostazione predefinita, viene utilizzata una connessione denominata bigframes-default-connection. Se preferisci, puoi utilizzare una connessione BigQuery preconfigurata, nel qual caso la creazione della connessione viene ignorata. Al account di servizio per la connessione predefinita viene concesso il ruolo Cloud Run (roles/run.invoker).

  • Una funzione remota BigQuery che utilizza la funzione Cloud Run creata con la connessione BigQuery.

Requisiti

Per utilizzare le funzioni remote di BigQuery DataFrames, devi abilitare le seguenti API:

Quando utilizzi le funzioni remote di BigQuery DataFrames, hai bisogno del ruolo Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) se utilizzi una connessione BigQuery predefinita o del ruolo Browser (roles/browser) se utilizzi una connessione preconfigurata. Puoi evitare questo requisito impostando l'opzione bigframes.pandas.options.bigquery.skip_bq_connection_check su True, nel qual caso la connessione (predefinita o preconfigurata) viene utilizzata così com'è senza alcun controllo di esistenza o autorizzazione. Se utilizzi la connessione preconfigurata e salti il controllo della connessione, verifica quanto segue:

  • La connessione viene creata nella posizione corretta.
  • Se utilizzi le funzioni remote di BigQuery DataFrames, il service account dispone del ruolo Cloud Run Invoker (roles/run.invoker) nel progetto.

Visualizzare e gestire le connessioni

Le connessioni BigQuery vengono create nella stessa posizione della sessione BigQuery DataFrames, utilizzando il nome fornito nella definizione della funzione personalizzata. Per visualizzare e gestire le connessioni:

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Seleziona il progetto in cui hai creato la funzione remota.

  3. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

  4. Nel riquadro Explorer, espandi il progetto e poi fai clic su Connessioni.

Le funzioni remote BigQuery vengono create nel set di dati specificato oppure in un set di dati anonimo, che è un tipo di set di dati nascosto. Se non imposti un nome per una funzione remota durante la creazione, BigQuery DataFrames applica un nome predefinito che inizia con il prefisso bigframes. Per visualizzare e gestire le funzioni remote create in un set di dati specificato dall'utente:

  1. Nella console Google Cloud , vai alla pagina BigQuery.

    Vai a BigQuery

  2. Seleziona il progetto in cui hai creato la funzione remota.

  3. Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

    Pulsante evidenziato per il riquadro Spazio di esplorazione.

  4. Nel riquadro Explorer, espandi il progetto e fai clic su Set di dati.

  5. Fai clic sul set di dati in cui hai creato la funzione remota.

  6. Fai clic sulla scheda Routine.

Per visualizzare e gestire le funzioni Cloud Run:

  1. Vai alla pagina Cloud Run.

    Vai a Cloud Run

  2. Seleziona il progetto in cui hai creato la funzione.

  3. Nell'elenco dei servizi disponibili, filtra in base a Tipo di deployment della funzione.

  4. Per identificare le funzioni create da BigQuery DataFrames, cerca i nomi delle funzioni con il prefisso bigframes.

Esegui la pulizia

Oltre a ripulire gli artefatti cloud direttamente nella Google Cloud console o con altri strumenti, puoi ripulire le funzioni remote BigQuery create senza un argomento nome esplicito e le relative funzioni Cloud Run nei seguenti modi:

  • Per una sessione BigQuery DataFrames, utilizza il comando session.close().
  • Per la sessione predefinita di BigQuery DataFrames, utilizza il comando bigframes.pandas.close_session().
  • Per una sessione precedente con session_id, utilizza il comando bigframes.pandas.clean_up_by_session_id(session_id).

Puoi anche eliminare le funzioni remote BigQuery create con un argomento nome esplicito e le relative funzioni Cloud Run utilizzando il comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitazioni

  • Le funzioni remote impiegano circa 90 secondi per diventare utilizzabili dopo la creazione. Dipendenze aggiuntive del pacchetto potrebbero aumentare la latenza.
  • Se esegui di nuovo il codice di definizione della funzione remota dopo modifiche banali nel codice della funzione e intorno a questo, ad esempio rinominando una variabile, inserendo una nuova riga o una nuova cella nel blocco note, la funzione remota potrebbe essere ricreata, anche se queste modifiche sono irrilevanti per il comportamento della funzione.
  • Il codice utente è visibile agli utenti con accesso in lettura alle funzioni Cloud Run, pertanto devi includere contenuti sensibili solo con cautela.
  • Un progetto può avere fino a 1000 funzioni Cloud Run contemporaneamente in una regione. Per scoprire di più, consulta Quote.

Passaggi successivi