Google utilizza la tecnologia AI per tradurre i contenuti nella tua lingua preferita. Le traduzioni generate dall'AI potrebbero contenere errori.

Introduzione alle routine

La creazione di routine in BigQuery ti consente di incapsulare una logica complessa utilizzando funzioni e stored procedure riutilizzabili. La scelta della routine giusta per il tuo workload ti consente di aggregare i dati in modo efficiente, automatizzare le attività di gestione e l'integrazione con i servizi esterni direttamente dalle tue query.

Routine supportate

BigQuery supporta le seguenti routine:

Funzioni definite dall'utente (UDF)
Funzioni aggregate definite dall'utente (UDAF)
Funzioni tabella
Funzioni remote
Stored procedure

Come scegliere una routine

Questa sezione descrive i fattori da considerare quando scegli una routine e confronta le routine in base all'attività.

Fattori da considerare

Per scegliere una routine, considera i seguenti fattori, descritti nelle sezioni relative a ogni tipo di routine:

Il tipo di attività da implementare.
Il linguaggio di programmazione da utilizzare.
Il tipo di persistenza da implementare per la routine: temporanea o persistente.
Il tipo di riutilizzo richiesto per la routine: per query singole o multiple.
Considerazioni sulle prestazioni.
Accesso a servizi esterni.
Condivisione della routine con gli utenti.

Confronta le routine per attività

La tabella seguente mostra il tipo di attività che puoi eseguire per ogni tipo di routine:

Attività	Tipo di risorsa della routine
Crea funzioni che eseguono attività per uso generico in BigQuery.	UDF SQL o JavaScript UDAF SQL o JavaScript
Crea funzioni che eseguono attività per uso generico in BigQuery e che comunicano con sistemi Google Cloud esterni utilizzando una connessione alle risorse Cloud.	UDF Python
Creare funzioni che aggregano i dati.	UDAF
Crea una tabella utilizzando i parametri.	Funzioni tabella
Creare funzioni che utilizzano linguaggi, librerie o servizi non supportati in BigQuery. Queste funzioni si integrano direttamente con Cloud Run Functions e Cloud Run.	Funzioni remote
Esegui più istruzioni in una query come query con più istruzioni utilizzando il linguaggio procedurale. Puoi utilizzare una query con più istruzioni per: Eseguire più istruzioni in una sequenza, con stato condiviso. Automatizzare le attività di gestione, come la creazione o l'eliminazione di tabelle. Implementa una logica complessa utilizzando costrutti di programmazione come `IF` e `WHILE`. Crea e chiama stored procedure per Apache Spark in BigQuery.	Stored procedure

Funzioni definite dall'utente

Una funzione definita dall'utente consente di creare una funzione utilizzando un'espressione SQL, il codice JavaScript o il codice Python. Le funzioni definite dall'utente accettano colonne di input, eseguono azioni sull'input e restituiscono il risultato di queste azioni sotto forma di un valore.

Puoi definire le funzioni definite dall'utente come permanenti o temporanee. Puoi riutilizzare le funzioni definite dall'utente permanenti per più query, mentre le funzioni definite dall'utente temporanee esistono solo nell'ambito di una singola query.

Puoi creare UDF da utilizzare con le routine di mascheramento personalizzate, che restituiscono il valore di una colonna dopo aver applicato una UDF alla colonna. Dopo aver creato la routine di mascheramento personalizzata, questa è disponibile come regola di mascheramento in Crea policy dati.

Per saperne di più sulle funzioni definite dall'utente, consulta le seguenti risorse:

UDF basate su linguaggio

Le UDF basate su SQL supportano i parametri UDF basati su modelli, che possono corrispondere a più di un tipo di argomento quando viene chiamata l'UDF. Le funzioni definite dall'utente SQL possono anche restituire il valore di una subquery scalare.
Le UDF basate su JavaScript consentono di chiamare il codice scritto in JavaScript da una query SQL.
- Le funzioni definite dall'utente JavaScript in genere consumano più risorse slot rispetto alle query SQL standard, riducendo le prestazioni dei job.
- Se la funzione può essere espressa in SQL, spesso è più ottimale eseguire il codice come job di query SQL standard.
Le funzioni definite dall'utente basate su Python vengono create ed eseguite su risorse gestite di BigQuery. Queste funzioni definite dall'utente ti consentono di implementare una funzione in Python e utilizzarla in una query SQL.
- Puoi accedere a un servizio Google Cloud o a un servizio esternoda una funzione definita dall'utente Python utilizzando il account di servizio della connessione alle risorse Cloud.
- Puoi anche installare librerie di terze parti da Python Package Index (PyPI).

UDF fornite dalla community

Oltre alle UDF che crei, le UDF fornite dalla community sono disponibili nel set di dati pubblico bigquery-public-data.persistent_udfs e nel repository GitHub bigquery-utils open source.

Funzioni aggregate definite dall'utente (UDAF)

Una UDAF consente di creare una funzione di aggregazione utilizzando un'espressione che contiene codice SQL o JavaScript. Una funzione definita dall'utente aggregata accetta colonne di input, esegue un calcolo su un gruppo di righe alla volta e restituisce il risultato del calcolo sotto forma di un singolo valore.

Le UDAF non possono modificare i dati, comunicare con sistemi esterni o inviare log a Google Cloud Observability o ad applicazioni simili.

Per maggiori informazioni, consulta le seguenti risorse:

UDAF SQL

In genere, le funzioni definite dall'utente (UDAF) SQL aggregano i parametri della funzione in tutte le righe di un gruppo. Tuttavia, puoi specificare un parametro di funzione come non aggregato utilizzando la parola chiave NOT AGGREGATE. Un parametro di funzione non aggregata è un parametro di funzione scalare con un valore costante per tutte le righe di un gruppo. Le UDAF SQL possono contenere parametri aggregati e non aggregati.

UDAF JavaScript

Le UDAF JavaScript possono includere librerie JavaScript. Il corpo della funzione JavaScript può includere codice JavaScript personalizzato, come variabili globali JavaScript e funzioni personalizzate.

Poiché le funzioni basate su JavaScript in genere utilizzano più risorse, può essere utile consultare questi suggerimenti per le prestazioni.

Le funzioni UDAF JavaScript presentano alcuni vincoli. Sono consentite solo codifiche di tipo specifico e sono previsti requisiti per la serializzazione e la deserializzazione.

Confronta le funzioni definite dall'utente e le funzioni di aggregazione definite dall'utente

La scelta di una funzione definita dall'utente (UDF) o di una funzione di aggregazione definita dall'utente (UDAF) dipende dall'attività specifica che stai cercando di eseguire.

Per eseguire un calcolo o una trasformazione su singoli valori di dati, utilizza una funzione definita dall'utente.
Per fare lo stesso su gruppi di valori di dati, utilizza una funzione UDAF.

Ad esempio, se vuoi calcolare la media di una colonna di numeri, utilizza una UDAF. Se vuoi convertire una colonna di stringhe in lettere maiuscole, utilizza una funzione definita dall'utente.

Le funzioni definite dall'utente e le funzioni di aggregazione definite dall'utente hanno le seguenti somiglianze:

Le funzioni definite dall'utente e le funzioni di aggregazione definite dall'utente non possono modificare i dati, comunicare con sistemi esterni o inviare log a Google Cloud Observability o ad applicazioni simili. L'eccezione sono le funzioni definite dall'utente Python, che possono accedere ai servizi esterni utilizzando una connessione alle risorse Cloud. Tuttavia, le funzioni definite dall'utente Python non supportano i Controlli di servizio VPC o le chiavi di crittografia gestite dal cliente (CMEK).
Le UDAF hanno le stesse limitazioni delle UDF, oltre ad alcune altre.
Le funzioni definite dall'utente e le funzioni di aggregazione definite dall'utente hanno le stesse quote e gli stessi limiti.

Le funzioni definite dall'utente e le funzioni aggregate definite dall'utente presentano le seguenti differenze:

Attributo	UDF	UDAF
Definizione	Le funzioni definite dall'utente (UDF) accettano colonne di input, eseguono azioni sull'input e restituiscono il risultato di queste azioni sotto forma di un valore.	Le funzioni aggregate definite dall'utente (UDAF) accettano colonne di input, eseguono un calcolo su un gruppo di righe alla volta e restituiscono il risultato del calcolo sotto forma di un singolo valore.
Lingue supportate	SQL, JavaScript e Python	SQL e JavaScript
Persistenza	Può essere temporaneo o permanente. Puoi utilizzare le funzioni definite dall'utente permanenti in più query. Puoi utilizzare le funzioni definite dall'utente temporanee solo per una singola query. Le funzioni definite dall'utente in Python possono essere solo permanenti, non temporanee.	Può essere temporaneo o permanente. Puoi utilizzare le UDAF permanenti in più query. Puoi utilizzare le UDAF temporanee solo per una singola query, uno script, una sessione o una procedura. Le UDAF permanenti possono essere chiamate in sicurezza quando vengono condivise tra i proprietari.
Argomenti e tipi di dati	Le funzioni definite dall'utente accettano valori parametro conformi ai tipi di dati GoogleSQL per BigQuery. Alcuni tipi SQL hanno una mappatura diretta ai tipi JavaScript, ma altri no. Consulta i tipi supportati per JavaScript. Per una funzione definita dall'utente SQL, i valori parametro possono essere `ANY TYPE`, che possono corrispondere a più di un tipo di argomento quando viene chiamata la funzione. Solo le funzioni definite dall'utente JavaScript hanno un identificatore di determinismo che fornisce un suggerimento a BigQuery per stabilire se il risultato della query può essere memorizzato nella cache.	Le UDAF SQL e JavaScript accettano valori dei parametri conformi ai tipi di dati GoogleSQL per BigQuery. I parametri della funzione possono essere aggregati o non aggregati.
Utilizzo	Le funzioni definite dall'utente vengono comunemente utilizzate per la pulizia, la trasformazione e la convalida dei dati.	Le UDAF sono di uso comune per calcolare statistiche di riepilogo, come medie, somme e conteggi.

Funzioni tabella

Una funzione di tabella, chiamata anche funzione con valori di tabella (TVF), è una funzione definita dall'utente che restituisce una tabella. Puoi utilizzare una funzione di tabella ovunque sia possibile utilizzare una tabella. Le funzioni di tabella si comportano in modo simile alle viste, ma una funzione di tabella può accettare parametri.

Con le funzioni con tabella puoi:

Passa più parametri.
Chiama una funzione di tabella in qualsiasi contesto in cui una tabella è valida.
Unire l'output di una funzione di tabella con un'altra tabella.
Utilizza una funzione di tabella in una subquery.

Per saperne di più sulle funzioni tabella, consulta Funzioni tabella, Limitazioni e Quote e limiti.

Funzioni remote

Le funzioni remote consentono di implementare la funzione in linguaggi diversi da SQL e JavaScript o di utilizzare librerie o servizi non supportati nelle UDF di BigQuery.

Una funzione remota di BigQuery integra la tua funzione Google SQL con Cloud Run Functions e Cloud Run utilizzando qualsiasi linguaggio supportato, quindi richiama queste funzioni dalle query SQL.

Le seguenti attività sono esempi di ciò che puoi fare con le funzioni remote:

Per creare una funzione remota, segui questi passaggi:

Crea l'endpoint HTTP in Cloud Run Functions o Cloud Run.
Crea una funzione remota in BigQuery utilizzando il tipo di connessione CLOUD_RESOURCE.
Utilizza la funzione remota in una query come qualsiasi altra funzione definita dall'utente per BigQuery.

Per saperne di più sulle funzioni remote, consulta Funzioni remote, Limitazioni e Quote e limiti.

Stored procedure

Una stored procedure SQL è una raccolta di istruzioni che possono essere chiamate da altre query o da altre stored procedure. Puoi assegnare un nome a una procedura e archiviarla in un set di dati BigQuery.

Le stored procedure supportano le istruzioni del linguaggio procedurale, che ti consentono di eseguire operazioni come la definizione di variabili e l'implementazione del flusso di controllo. Puoi scoprire di più sulle istruzioni del linguaggio procedurale nel riferimento del linguaggio procedurale.

Una stored procedure può:

Accettano argomenti di input e restituiscono valori come output.
Accedere ai dati o modificarli in più set di dati da parte di più utenti.
Contenere una query con più istruzioni.

Alcune stored procedure sono integrate in BigQuery e non devono essere create. Queste sono chiamate procedure di sistema e puoi scoprire di più su di esse nel Riferimento per le procedure di sistema.

Sono supportate anche le stored procedure per Spark in BigQuery. Queste procedure hanno quote e limiti.

Per scoprire di più sulle stored procedure, consulta Stored procedure SQL.

Utilizza le routine con gli agenti AI

Se crei agenti AI che utilizzano i dati di BigQuery, questi possono recuperare i metadati della routine da Knowledge Catalog, inclusi gli argomenti, il tipo restituito e il codice sorgente della routine, per capire cosa fa una routine e come chiamarla. Per saperne di più, consulta Recupera il contesto per le routine.