Esecuzione di query con parametri
BigQuery supporta parametri di ricerca per prevenire l'iniezione SQL quando le query vengono create utilizzando l'input utente'utente. Questa funzionalità è disponibile solo con la sintassi di GoogleSQL. I parametri di query possono essere utilizzati come sostituti di espressioni arbitrarie. I parametri non possono essere utilizzati come sostituti di identificatori, nomi di colonna, nomi di tabella o altre parti della query.
Per specificare un parametro denominato, utilizza il carattere @
seguito da un
identificatore, come
@param_name
. In alternativa, utilizza il valore segnaposto ?
per specificare un
parametro di posizionamento. Tieni presente che una query può utilizzare parametri
posizionali o denominati, ma non entrambi.
Puoi eseguire una query con parametri in BigQuery nei seguenti modi:
- il comando
bq query
dello strumento a riga di comando bq - l'API
- le librerie client
L'esempio seguente mostra come passare i valori dei parametri a una query con parametri:
Console
Le query con parametri non sono supportate dalla console Google Cloud.
bq
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Utilizza
--parameter
per fornire i valori per i parametri nel moduloname:type:value
. Un nome vuoto produce un parametro posizionale. Il tipo può essere omesso per presupporreSTRING
.Il flag
--parameter
deve essere utilizzato insieme al flag--use_legacy_sql=false
per specificare la sintassi GoogleSQL.(Facoltativo) Specifica la tua località utilizzando il flag
--location
.bq query \ --use_legacy_sql=false \ --parameter=corpus::romeoandjuliet \ --parameter=min_word_count:INT64:250 \ 'SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC;'
API
Per utilizzare parametri denominati, imposta parameterMode
su NAMED
nella configurazione del job di query
.
Completa queryParameters
con l'elenco dei parametri nella configurazione del job di query
. Imposta il name
di ogni parametro con il valore @param_name
utilizzato nella
query.
Attiva la sintassi GoogleSQL
impostando useLegacySql
su false
.
{
"query": "SELECT word, word_count FROM `bigquery-public-data.samples.shakespeare` WHERE corpus = @corpus AND word_count >= @min_word_count ORDER BY word_count DESC;",
"queryParameters": [
{
"parameterType": {
"type": "STRING"
},
"parameterValue": {
"value": "romeoandjuliet"
},
"name": "corpus"
},
{
"parameterType": {
"type": "INT64"
},
"parameterValue": {
"value": "250"
},
"name": "min_word_count"
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
Provalo nell'Explorer API di Google.
Per utilizzare i parametri posizionali, imposta parameterMode
su POSITIONAL
nella
configurazione del job query
.
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per utilizzare parametri denominati:Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per utilizzare i parametri posizionali:Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per utilizzare parametri denominati:Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per utilizzare parametri denominati:Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per utilizzare parametri denominati:Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Per utilizzare parametri denominati:Utilizzo di array nelle query con parametri
Per utilizzare un tipo di array in un parametro di query, imposta il tipo su ARRAY<T>
, dove T
è il tipo degli elementi nell'array. Crea il valore come un elenco separato da virgole di elementi racchiusi tra parentesi quadre, ad esempio [1, 2,
3]
.
Per saperne di più sul tipo di array, consulta la documentazione sui tipi di dati di riferimento.
Console
Le query con parametri non sono supportate dalla console Google Cloud.
bq
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Questa query seleziona i nomi più popolari per i bambini nati negli stati USA che iniziano con la lettera W:
bq query \ --use_legacy_sql=false \ --parameter='gender::M' \ --parameter='states:ARRAY<STRING>:["WA", "WI", "WV", "WY"]' \ 'SELECT name, SUM(number) AS count FROM `bigquery-public-data.usa_names.usa_1910_2013` WHERE gender = @gender AND state IN UNNEST(@states) GROUP BY name ORDER BY count DESC LIMIT 10;'
Assicurati di racchiudere la dichiarazione del tipo di array tra virgolette singole in modo che l'output comando non venga reindirizzato accidentalmente a un file dal carattere
>
.
API
Per utilizzare un parametro con valori di array, imposta parameterType
su ARRAY
nella configurazione del job query
.
Se i valori dell'array sono scalari, imposta parameterType
sul tipo dei valori, ad esempio STRING
. Se i valori dell'array sono strutture, imposta questo valore su STRUCT
e aggiungi le definizioni dei campi necessarie a structTypes
.
Ad esempio, questa query seleziona i nomi più popolari per i bambini nati negli Stati Uniti che iniziano con la lettera W.
{
"query": "SELECT name, sum(number) as count\nFROM `bigquery-public-data.usa_names.usa_1910_2013`\nWHERE gender = @gender\nAND state IN UNNEST(@states)\nGROUP BY name\nORDER BY count DESC\nLIMIT 10;",
"queryParameters": [
{
"parameterType": {
"type": "STRING"
},
"parameterValue": {
"value": "M"
},
"name": "gender"
},
{
"parameterType": {
"type": "ARRAY",
"arrayType": {
"type": "STRING"
}
},
"parameterValue": {
"arrayValues": [
{
"value": "WA"
},
{
"value": "WI"
},
{
"value": "WV"
},
{
"value": "WY"
}
]
},
"name": "states"
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Utilizzare i timestamp nelle query con parametri
Per utilizzare un timestamp in un parametro di query, l'API REST sottostante utilizza un valore di tipo TIMESTAMP
nel formato YYYY-MM-DD HH:MM:SS.DDDDDD time_zone
. Se utilizzi le librerie client, crei un oggetto data integrato in quella lingua e la libreria lo converte nel formato corretto. Per ulteriori informazioni, consulta i seguenti esempi specifici per la lingua.
Per maggiori informazioni sul tipo TIMESTAMP
, consulta la
documentazione di riferimento sui tipi di dati.
Console
Le query con parametri non sono supportate dalla console Google Cloud.
bq
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Questa query aggiunge un'ora al valore parametro timestamp:
bq query \ --use_legacy_sql=false \ --parameter='ts_value:TIMESTAMP:2016-12-07 08:00:00' \ 'SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);'
API
Per utilizzare un parametro del timestamp, imposta parameterType
su TIMESTAMP
nella configurazione del job di query.
Questa query aggiunge un'ora al valore parametro timestamp.
{
"query": "SELECT TIMESTAMP_ADD(@ts_value, INTERVAL 1 HOUR);",
"queryParameters": [
{
"name": "ts_value",
"parameterType": {
"type": "TIMESTAMP"
},
"parameterValue": {
"value": "2016-12-07 08:00:00"
}
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
C#
Prima di provare questo esempio, segui le istruzioni di configurazione di C# disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery C#.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Utilizzo di struct nelle query con parametri
Per utilizzare uno struct in un parametro di query, imposta il tipo su STRUCT<T>
, dove T
definisce i campi e i tipi all'interno dello struct. Le definizioni dei campi sono separate da virgole e hanno il formato field_name TF
, dove TF
è il tipo di campo. Ad esempio, STRUCT<x INT64, y STRING>
definisce uno struct con un
campo denominato x
di tipo INT64
e un secondo campo denominato y
di tipo STRING
.
Per ulteriori informazioni sul tipo STRUCT
, consulta la
documentazione di riferimento sui tipi di dati .
Console
Le query con parametri non sono supportate dalla console Google Cloud.
bq
-
Nella console Google Cloud, attiva Cloud Shell.
Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell che mostra un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installato e con valori già impostati per il progetto attuale. L'inizializzazione della sessione può richiedere alcuni secondi.
Questa query banale dimostra l'uso dei tipi strutturati restituendo il valore parametro:
bq query \ --use_legacy_sql=false \ --parameter='struct_value:STRUCT<x INT64, y STRING>:{"x": 1, "y": "foo"}' \ 'SELECT @struct_value AS s;'
API
Per utilizzare un parametro di struct, imposta parameterType
su STRUCT
nella configurazione del job di query.
Aggiungi un oggetto per ogni campo dello struct a structTypes
nel queryParameters
del job.
Se i valori dello struct sono scalari, imposta type
sul tipo dei valori, ad esempio STRING
. Se i valori struct sono array, imposta questo valore su ARRAY
e imposta il campo arrayType
nidificato sul tipo appropriato. Se i valori dello struct sono strutture, imposta type
su STRUCT
e aggiungi
il structTypes
necessario.
Questa query banale dimostra l'uso dei tipi strutturati restituendo il valore parametro.
{
"query": "SELECT @struct_value AS s;",
"queryParameters": [
{
"name": "struct_value",
"parameterType": {
"type": "STRUCT",
"structTypes": [
{
"name": "x",
"type": {
"type": "INT64"
}
},
{
"name": "y",
"type": {
"type": "STRING"
}
}
]
},
"parameterValue": {
"structValues": {
"x": {
"value": "1"
},
"y": {
"value": "foo"
}
}
}
}
],
"useLegacySql": false,
"parameterMode": "NAMED"
}
C#
La libreria client BigQuery per .NET non supporta i parametri struct.
Go
Prima di provare questo esempio, segui le istruzioni di configurazione di Go disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python disponibili nella guida rapida di BigQuery sull'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura Credenziali predefinite dell'applicazione. Per maggiori informazioni, consulta Configurare l'autenticazione per le librerie client.