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

Introduzione alle routine

Questo documento descrive come scegliere una routine, un tipo di risorsa che utilizzi per creare funzioni o stored procedure in BigQuery.

Routine supportate

BigQuery supporta le seguenti routine:

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 per 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 permanente.
Il tipo di riutilizzo richiesto per la routine: in una o più query.
Considerazioni sulle prestazioni.
Accesso a servizi esterni.
Condivisione della routine con gli utenti.

Confronta le routine in base all'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
Crea funzioni che aggregano i dati.	UDAF
Crea una tabella utilizzando i parametri.	Funzioni tabella
Crea 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 sequenza, con stato condiviso. Automatizzare le attività di gestione, ad esempio la creazione o l'eliminazione di tabelle. Implementare 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 (UDF)

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

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

Puoi creare UDF da utilizzare con 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 sui dati.

Per saperne di più sulle UDF, consulta le seguenti risorse:

UDF basate sul linguaggio

Le UDF basate su SQL supportano i parametri UDF con modelli, che possono corrispondere a più tipi di argomenti quando viene chiamata la UDF. Le UDF SQL possono anche restituire il valore di una sottoquery scalare.
Le UDF basate su JavaScript consentono di chiamare il codice scritto in JavaScript da una query SQL.
- In genere, le UDF JavaScript consumano più risorse di 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 UDF basate su Python vengono create ed eseguite su risorse gestite da BigQuery. Queste UDF consentono di implementare una funzione in Python e utilizzarla in una query SQL.
- Puoi accedere a un Google Cloud servizio o a un servizio esternoda una UDF Python utilizzando l' account di servizio di connessione alla risorsa Cloud.
- Puoi anche installare librerie di terze parti da the Python Package Index (PyPI).

UDF fornite dalla community

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

Funzioni di aggregazione definite dall'utente (UDAF)

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

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

Per saperne di più, consulta le seguenti risorse:

UDAF SQL

Le UDAF SQL in genere aggregano i parametri delle funzioni 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 aggregato è 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, ad esempio 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 UDAF JavaScript hanno alcuni vincoli. Sono consentite solo codifiche di tipo specifiche e sono previsti requisiti per la serializzazione e la deserializzazione.

Confronta UDF e UDAF

La scelta di una UDF anziché di una UDAF dipende dall'attività specifica che stai cercando di eseguire.

Per eseguire un calcolo o una trasformazione su singoli valori di dati, utilizza una UDF.
Per eseguire la stessa operazione su gruppi di valori di dati, utilizza una UDAF.

Ad esempio, se vuoi calcolare la media di una colonna di numeri, utilizza una UDAF. Se vuoi convertire una colonna di stringhe in maiuscolo, utilizza una UDF.

Le UDF e le UDAF hanno le seguenti somiglianze:

Le UDF e le UDAF non possono modificare i dati, comunicare con sistemi esterni o inviare log a Google Cloud Observability o applicazioni simili. L'eccezione sono le UDF Python, che possono accedere a servizi esterni utilizzando una connessione alle risorse Cloud. Tuttavia, le UDF 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 a qualche altra.
Le UDF e le UDAF hanno le stesse quote e gli stessi limiti.

Le UDF e le UDAF hanno 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 di aggregazione definite dall'utente (UDAF) accettano colonne di input, eseguono un calcolo su un gruppo di righe alla volta e restituiscono il risultato di questo calcolo come un singolo valore.
Lingue supportate	SQL, JavaScript e Python	SQL e JavaScript
Persistenza	Può essere temporanea 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 UDF Python possono essere solo permanenti, non temporanee.	Può essere temporanea o permanente. Puoi utilizzare le UDAF permanenti in più query. Puoi utilizzare le UDAF temporanee solo per una singola query, script, sessione o procedura. Le UDAF permanenti sono sicure da chiamare quando vengono condivise tra i proprietari.
Argomenti e tipi di dati	Le UDF accettano valori parametro conformi a GoogleSQL per i tipi di dati BigQuery. Alcuni tipi SQL hanno un mapping diretto ai tipi JavaScript, ma altri no. Consulta i tipi supportati per JavaScript. Per una UDF SQL, i valori parametro possono essere `ANY TYPE`, che può corrispondere a più tipi di argomenti quando viene chiamata la funzione. Solo le UDF JavaScript hanno uno specificatore di determinismo che fornisce un suggerimento a BigQuery per indicare se il risultato della query può essere memorizzato nella cache.	Le UDAF SQL e JavaScript accettano valori di parametri conformi a GoogleSQL per i tipi di dati BigQuery. I parametri delle funzioni possono essere aggregati o non aggregati.
Utilizzo	Le UDF 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 tabella, chiamata anche funzione con valori di tabella (TVF), è una UDF che restituisce una tabella. Puoi utilizzare una funzione tabella ovunque tu possa utilizzare una tabella. Le funzioni tabella si comportano in modo simile alle viste, ma una funzione tabella può accettare parametri.

Con le funzioni tabella puoi:

Passare più parametri.
Chiamare una funzione tabella in qualsiasi contesto in cui una tabella è valida.
Unire l'output di una funzione tabella con un'altra tabella.
Utilizzare una funzione tabella in una sottoquery.

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 oppure di utilizzare librerie o servizi non supportati nelle UDF BigQuery.

Una funzione remota BigQuery integra la funzione GoogleSQL 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:

La creazione di una funzione remota richiede i seguenti 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 UDF 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 altre stored procedure. Dai un nome a una procedura e la memorizzi in un set di dati BigQuery.

Le stored procedure supportano le istruzioni del linguaggio procedurale, che consentono di eseguire operazioni come definire variabili e implementare il flusso di controllo. Puoi scoprire di più sulle istruzioni del linguaggio procedurale nel riferimento al linguaggio procedurale.

Una stored procedure può:

Accettare argomenti di input e restituire valori come output.
Accedere o modificare i dati 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 alle procedure di sistema.

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

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

Utilizzare le routine con gli agenti AI

Se crei agenti AI che funzionano con i dati BigQuery, gli agenti possono recuperare i metadati delle 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 Recuperare il contesto per le routine.