Eseguire query su dati Cloud Storage in tabelle esterne
Questo documento descrive come eseguire query sui dati archiviati in un Tabella esterna di Cloud Storage.
Prima di iniziare
Assicurati di avere una tabella esterna di Cloud Storage.
Ruoli obbligatori
Per eseguire query sulle tabelle esterne di Cloud Storage, assicurati disponi dei seguenti ruoli:
- Visualizzatore dati BigQuery (
roles/bigquery.dataViewer
) - Utente BigQuery (
roles/bigquery.user
) - Visualizzatore oggetti Storage (
roles/storage.objectViewer
)
In base alle tue autorizzazioni, puoi concediti questi ruoli o chiedi all'amministratore per concederteli. Per ulteriori informazioni sulla concessione dei ruoli, consulta Visualizzazione dei ruoli assegnabili nelle risorse.
Per visualizzare le autorizzazioni BigQuery esatte necessarie per eseguire la query tabelle esterne, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
bigquery.jobs.create
bigquery.readsessions.create
(obbligatorio solo se sei tu leggi i dati con API BigQuery Storage Read)bigquery.tables.get
bigquery.tables.getData
Potresti anche riuscire a ottenere queste autorizzazioni con i ruoli personalizzati. o altri ruoli predefiniti.
Esegui query su tabelle esterne permanenti
Dopo aver creato una tabella esterna di Cloud Storage, puoi eseguire una query utilizzando
Sintassi GoogleSQL, come se
era una tabella BigQuery standard. Ad esempio, SELECT field1, field2
FROM mydataset.my_cloud_storage_table;
.
Eseguire query su tabelle esterne temporanee
È utile eseguire query su un'origine dati esterna utilizzando una tabella temporanea per query una tantum ad hoc su dati esterni o per l'estrazione, la trasformazione e il caricamento (ETL) i processi di machine learning.
Per eseguire una query su un'origine dati esterna senza creare una tabella permanente, fornisci una tabella definizione della tabella temporanea e poi utilizzarla in un comando o in una chiamata per eseguire una query sulla tabella temporanea. Puoi fornire la definizione della tabella in uno dei seguenti modi modi:
- Un file di definizione della tabella
- Definizione di uno schema in linea
- Un file di schema JSON
Il file di definizione della tabella o lo schema fornito vengono utilizzati per creare la tabella esterna temporanea. e la query viene eseguita sulla tabella esterna temporanea.
Quando utilizzi una tabella esterna temporanea, non ne crei una in una delle set di dati BigQuery. Poiché la tabella non è archiviata in modo permanente in un set di dati, non possono essere condivisi con altri.
Puoi creare ed eseguire query su una tabella temporanea collegata a un'origine dati esterna mediante lo strumento a riga di comando bq, l'API o le librerie client.
bq
Per eseguire query su una tabella temporanea collegata a un'origine dati esterna, puoi utilizzare
Comando bq query
con
Flag --external_table_definition
.
Quando usi lo strumento a riga di comando bq per eseguire query su una tabella temporanea collegata a un
origine dati, puoi identificare lo schema della tabella utilizzando:
- Un file di definizione della tabella (archiviato su dalla macchina locale)
- Definizione di uno schema in linea
- Un file di schema JSON (memorizzati sul computer locale)
(Facoltativo) Fornisci il flag --location
e imposta il valore su
località.
Per eseguire una query su una tabella temporanea collegata all'origine dati esterna utilizzando una tabella di definizione, inserisci il seguente comando.
bq --location=LOCATION query \ --external_table_definition=TABLE::DEFINITION_FILE \ 'QUERY'
Sostituisci quanto segue:
LOCATION
: il nome della tua località. Il flag--location
è facoltativo. Ad esempio, se utilizzi di BigQuery nella regione di Tokyo, puoi impostare il valore del flag aasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando nel file.bigqueryrc.TABLE
: il nome della tabella temporanea che stai creando.DEFINITION_FILE
: il percorso del file di definizione della tabella sul tuo computer locale.QUERY
: la query che stai inviando alla tabella temporanea.
Ad esempio, il seguente comando crea ed esegue una query su una tabella temporanea
denominato sales
mediante un file di definizione della tabella denominato sales_def
.
bq query \
--external_table_definition=sales::sales_def \
'SELECT
Region,
Total_sales
FROM
sales'
Per eseguire query su una tabella temporanea collegata alla tua origine dati esterna utilizzando un per la definizione dello schema incorporato, inserisci il comando seguente.
bq --location=LOCATION query \ --external_table_definition=TABLE::SCHEMA@SOURCE_FORMAT=BUCKET_PATH \ 'QUERY'
Sostituisci quanto segue:
LOCATION
: il nome della tua località. Il flag--location
è facoltativo. Ad esempio, se utilizzi di BigQuery nella regione di Tokyo, puoi impostare il valore del flag aasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando nel file.bigqueryrc.TABLE
: il nome della tabella temporanea che stai creando.SCHEMA
: la definizione dello schema incorporato nel formatofield:data_type,field:data_type
.SOURCE_FORMAT
: il formato dell'origine dati esterna, ad esempioCSV
.BUCKET_PATH
: il percorso bucket Cloud Storage che contiene i dati per nel formatogs://bucket_name/[folder_name/]file_pattern
.Puoi selezionare più file dal bucket specificando un asterisco (
*
) carattere jolly nel campofile_pattern
. Ad esempio:gs://mybucket/file00*.parquet
. Per maggiori informazioni le informazioni, vedi Supporto dei caratteri jolly per gli URI Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi di addestramento.I seguenti esempi mostrano valori
uris
validi:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
,gs://bucket1/path1/*
Se specifichi i valori
uris
che hanno come target più file, questi i file devono condividere uno schema compatibile.Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in per BigQuery, consulta Percorso della risorsa di Cloud Storage.
QUERY
: la query che stai inviando alla tabella temporanea.
Ad esempio, il seguente comando crea ed esegue una query su una tabella temporanea
denominato sales
collegato a un file CSV archiviato in Cloud Storage con
seguente definizione di schema:
Region:STRING,Quarter:STRING,Total_sales:INTEGER
.
bq query \
--external_table_definition=sales::Region:STRING,Quarter:STRING,Total_sales:INTEGER@CSV=gs://mybucket/sales.csv \
'SELECT
Region,
Total_sales
FROM
sales'
Per eseguire una query su una tabella temporanea collegata all'origine dati esterna utilizzando un file JSON del file di schema, inserisci il comando seguente.
bq --location=LOCATION query \ --external_table_definition=SCHEMA_FILE@SOURCE_FORMAT=BUCKET_PATH \ 'QUERY'
Sostituisci quanto segue:
LOCATION
: il nome della tua località. Il flag--location
è facoltativo. Ad esempio, se utilizzi di BigQuery nella regione di Tokyo, puoi impostare il valore del flag aasia-northeast1
. Puoi impostare un valore predefinito per la località utilizzando nel file.bigqueryrc.SCHEMA_FILE
: il percorso del file di schema JSON sul tuo server in una macchina virtuale.SOURCE_FORMAT
: il formato dell'origine dati esterna, ad esempioCSV
.BUCKET_PATH
: il percorso bucket Cloud Storage che contiene i dati per nel formatogs://bucket_name/[folder_name/]file_pattern
.Puoi selezionare più file dal bucket specificando un asterisco (
*
) carattere jolly nel campofile_pattern
. Ad esempio:gs://mybucket/file00*.parquet
. Per maggiori informazioni le informazioni, vedi Supporto dei caratteri jolly per gli URI Cloud Storage.Puoi specificare più bucket per l'opzione
uris
fornendo più percorsi di addestramento.I seguenti esempi mostrano valori
uris
validi:gs://bucket/path1/myfile.csv
gs://bucket/path1/*.parquet
gs://bucket/path1/file1*
,gs://bucket1/path1/*
Se specifichi i valori
uris
che hanno come target più file, questi i file devono condividere uno schema compatibile.Per ulteriori informazioni sull'utilizzo degli URI Cloud Storage in per BigQuery, consulta Percorso della risorsa di Cloud Storage.
QUERY
: la query che stai inviando alla tabella temporanea.
Ad esempio, il seguente comando crea ed esegue una query su una tabella temporanea
denominato sales
e collegato a un file CSV archiviato in Cloud Storage utilizzando
/tmp/sales_schema.json
file di schema.
bq query \ --external_table_definition=sales::/tmp/sales_schema.json@CSV=gs://mybucket/sales.csv \ 'SELECT Region, Total_sales FROM sales'
API
Per eseguire una query utilizzando l'API, segui questi passaggi:
- Crea un oggetto
Job
. - Compila la sezione
configuration
dell'oggettoJob
con un oggettoJobConfiguration
. - Compila la sezione
query
dell'oggettoJobConfiguration
con un oggettoJobConfigurationQuery
. - Compila la sezione
tableDefinitions
dell'oggettoJobConfigurationQuery
con un oggettoExternalDataConfiguration
. - Chiama il metodo
jobs.insert
per eseguire la query in modo asincronojobs.query
metodo da eseguire la query in modo sincrono, passando l'oggettoJob
.
Java
Prima di provare questo esempio, segui le istruzioni per la configurazione di Java nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Java BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni per la configurazione di Node.js nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Node.js BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Python
Prima di provare questo esempio, segui le istruzioni per la configurazione di Python nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Python BigQuery documentazione di riferimento.
Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.
Esegui una query sulla pseudocolonna _FILE_NAME
Le tabelle basate su origini dati esterne forniscono una pseudocolonna denominata _FILE_NAME
. Questo
contiene il percorso completo del file a cui appartiene la riga. Questa colonna è
disponibile solo per le tabelle che fanno riferimento a dati esterni archiviati in
Cloud Storage, Google Drive,
Amazon S3 e Archiviazione BLOB di Azure.
Il nome della colonna _FILE_NAME
è riservato, il che significa che non puoi creare una colonna
con lo stesso nome in qualsiasi tabella. Per selezionare il valore di _FILE_NAME
, devi utilizzare
un alias. La seguente query di esempio dimostra la selezione di _FILE_NAME
assegnando
l'alias fn
alla pseudocolonna.
bq query \
--project_id=PROJECT_ID \
--use_legacy_sql=false \
'SELECT
name,
_FILE_NAME AS fn
FROM
`DATASET.TABLE_NAME`
WHERE
name contains "Alex"'
Sostituisci quanto segue:
-
PROJECT_ID
è un ID progetto valido (questo flag non è obbligatorio se utilizzi Cloud Shell o se imposti un progetto predefinito in Google Cloud CLI) -
DATASET
è il nome del set di dati in cui è archiviato l'elemento esterno permanente tavola -
TABLE_NAME
è il nome della tabella esterna permanente
Quando la query ha un predicato di filtro nella pseudocolonna _FILE_NAME
,
BigQuery tenta di saltare la lettura dei file che non soddisfano il filtro. Simile
consigli per
eseguire query su tabelle partizionate in fase di importazione utilizzando pseudocolonne
.
si applicano quando si creano predicati di query con la pseudocolonna _FILE_NAME
.
Passaggi successivi
- Scopri di più sull'utilizzo di SQL in BigQuery.
- Scopri di più sulle tabelle esterne.
- Scopri di più sulle quote di BigQuery.