Personalizzare le funzioni Python per BigQuery DataFrames

BigQuery DataFrames consente di trasformare le funzioni Python personalizzate in artefatti BigQuery che puoi eseguire sugli oggetti BigQuery DataFrames su larga scala. Questo supporto per l'estensibilità consente di eseguire operazioni oltre a 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 per il 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 Creare una funzione definita dall'utente Python permanente.

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 funzione definita dall'utente 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.

Libera spazio

Oltre a liberare spazio dagli artefatti cloud direttamente nella Cloud de Confiance console o con altri strumenti, puoi liberare spazio dalle funzioni definite dall'utente BigQuery DataFrames che sono state create con un argomento name esplicito utilizzando ilbigframes.pandas.get_global_session().bqclient.delete_routine(routine_id)comando.

Limitazioni

  • Il codice nella funzione definita dall'utente 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 funzione definita dall'utente deve essere compatibile con Python 3.11, poiché è l'ambiente in cui il codice viene eseguito nel cloud.
  • Se esegui di nuovo il codice di definizione della funzione definita dall'utente dopo modifiche banali nel codice della funzione, ad esempio rinominando una variabile o inserendo una nuova riga, la funzione definita dall'utente viene ricreata, anche se queste modifiche non sono rilevanti 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 funzione definita dall'utente 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 Creare 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 BigQuery DataFrames, devi abilitare le seguenti API:

Quando utilizzi le funzioni remote BigQuery DataFrames, hai bisogno del ruolo Amministratore IAM progetto (roles/resourcemanager.projectIamAdmin) se utilizzi una connessione BigQuery predefinita o del ruolo Visualizzatore (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 BigQuery DataFrames, il service account ha il ruolo Invocatore Cloud Run (roles/run.invoker) nel progetto.

Visualizzare e gestire le connessioni

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

  1. Nella Cloud de Confiance console, 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 Spazio di esplorazione , espandi il progetto e fai clic su Connessioni.

Le funzioni remote BigQuery vengono create nel set di dati specificato, oppure vengono create 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 Cloud de Confiance console, 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 Spazio di esplorazione , 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.

Libera spazio

Oltre a liberare spazio dagli artefatti cloud direttamente nella Cloud de Confiance console o con altri strumenti, puoi liberare spazio dalle funzioni remote BigQuery create senza un argomento name esplicito e dalle funzioni Cloud Run associate nei seguenti modi:

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

Puoi anche liberare spazio dalle funzioni remote BigQuery create con un argomento name esplicito e dalle funzioni Cloud Run associate utilizzando il comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitazioni

  • Le funzioni remote diventano utilizzabili dopo circa 90 secondi dalla prima creazione. Le dipendenze di pacchetti aggiuntivi potrebbero aumentare la latenza.
  • Se esegui di nuovo il codice di definizione della funzione remota dopo modifiche banali nel codice della funzione, ad esempio rinominando una variabile, inserendo una nuova riga o inserendo una nuova cella nel notebook, la funzione remota potrebbe essere ricreata, anche se queste modifiche non sono rilevanti 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