Personalizza le funzioni Python per BigQuery DataFrames

La personalizzazione delle funzioni Python per BigQuery DataFrames ti consente di trasformare il tuo codice in artefatti BigQuery scalabili, come funzioni definite dall'utente (UDF) o funzioni remote. Puoi eseguire il deployment di queste funzioni definite dall'utente per sfruttare le librerie open source ed eseguire operazioni che vanno oltre le funzionalità delle API SQL standard.

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 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 UDF (anteprima), puoi trasformare la tua funzione Python personalizzata in una UDF Python. Per un esempio di utilizzo, consulta Crea 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 di 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 pulire gli artefatti cloud direttamente nella console Google Cloud o con altri strumenti, puoi pulire le 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 funzione definita dall'utente deve essere autonomo, ovvero non deve contenere riferimenti a un'importazione o a una variabile definita all'esterno del corpo della funzione.
  • Il codice nella funzione definita dall'utente deve essere compatibile con Python 3.11, poiché questo è l'ambiente in cui il codice viene eseguito nel cloud.
  • La nuova esecuzione del codice di definizione della funzione definita dall'utente dopo modifiche di poco conto nel codice della funzione, ad esempio la ridenominazione di una variabile o l'inserimento di una nuova riga, comporta la nuova creazione della funzione definita dall'utente, anche se queste modifiche non influiscono sul 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 alla volta in una località BigQuery.

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

Funzioni remote

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

La creazione di una funzione remota in BigQuery DataFrames genera 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. In questo caso, la creazione della connessione viene saltata. Al account di servizio per la connessione predefinita viene concesso il ruolo Cloud Run (roles/run.invoker).

  • Una funzione remota di 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, devi disporre 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. In questo 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 località corretta.
  • Se utilizzi le funzioni remote di BigQuery DataFrames, il service account dispone del ruolo Cloud Run Invoker (roles/run.invoker) nel progetto.

Visualizza e gestisci i collegamenti

Le connessioni BigQuery vengono create nella stessa località della sessione di 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, quindi fai clic su Connessioni.

Le funzioni remote di BigQuery vengono create nel set di dati specificato o 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 sua 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, segui questi passaggi:

  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 Cloud Run Functions, segui questi passaggi:

  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 al 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 console Google Cloud o con altri strumenti, puoi ripulire le funzioni remote di BigQuery create senza un argomento del nome esplicito e le funzioni Cloud Run associate nei seguenti modi:

  • Per una sessione di 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 comando bigframes.pandas.clean_up_by_session_id(session_id).

Puoi anche eseguire la pulizia delle funzioni remote di BigQuery create con un argomento del nome esplicito e delle funzioni Cloud Run associate utilizzando il comando bigframes.pandas.get_global_session().bqclient.delete_routine(routine_id).

Limitazioni

  • Le funzioni remote impiegano circa 90 secondi per diventare utilizzabili quando le crei per la prima volta. Ulteriori dipendenze dei pacchetti potrebbero aumentare la latenza.
  • La nuova esecuzione del codice di definizione della funzione remota dopo modifiche di poco conto nel codice della funzione e nei suoi dintorni, ad esempio la ridenominazione di una variabile, l'inserimento di una nuova riga o l'inserimento di una nuova cella nel notebook, potrebbe causare la nuova creazione della funzione remota, anche se queste modifiche non influiscono sul comportamento della funzione.
  • Il codice utente è visibile agli utenti con accesso in lettura a Cloud Run Functions, pertanto devi includere contenuti sensibili solo con cautela.
  • Un progetto può avere fino a 1000 funzioni Cloud Run alla volta in una regione. Per scoprire di più, consulta Quote.

Passaggi successivi