Questa pagina è stata tradotta dall'API Cloud Translation.

Creare un file di definizione della tabella per un'origine dati esterna

Questa pagina descrive come creare un file di definizione della tabella per un'origine dati esterna. Un'origine dati esterna è un'origine dati in cui puoi eseguire query direttamente anche se i dati non vengono archiviati in BigQuery.

Un file di definizione della tabella contiene la definizione dello schema e i metadati di una tabella esterna, ad esempio il formato dei dati della tabella e le proprietà correlate. Quando crei un file di definizione della tabella, puoi utilizzare il rilevamento automatico dello schema per definire lo schema per un'origine dati esterna. Puoi fornire lo schema inline o un file JSON contenente la definizione dello schema.

I file di definizione delle tabelle vengono utilizzati con lo strumento a riga di comando bq. Le proprietà in un file di definizione della tabella si applicano anche alla creazione di un ExternalDataConfiguration quando utilizzi l'API REST. Non utilizzi i file di definizione della tabella quando crei una tabella esterna utilizzando la console Google Cloud .

Puoi creare file di definizione della tabella per descrivere una tabella esterna permanente o temporanea per le seguenti origini dati esterne:

Cloud Storage
- Valori separati da virgola (CSV)
- JSON delimitato da nuova riga
- File Avro
- File di esportazione Datastore
- File ORC
- File Parquet
- File di esportazione di Firestore
Google Drive
- Valori separati da virgola (CSV)
- JSON delimitato da nuova riga
- File Avro
- Fogli Google
Bigtable

Prima di iniziare

Per creare un file di definizione della tabella, devi disporre dell'URI dell'origine dati:

Per un'origine dati Drive, devi specificare l'URI di Drive.
Per un'origine dati Cloud Storage, devi disporre dell'URI Cloud Storage.
Per un'origine dati Bigtable, devi disporre dell'URI Bigtable.

Creare un file di definizione per file CSV, JSON o Fogli Google

Utilizza uno dei seguenti metodi per creare un file di definizione della tabella per i file CSV, JSON o Fogli Google in Cloud Storage o Drive:

Utilizzare il flag autodetect
Utilizzare uno schema in linea
Utilizzare un file di schema JSON

Utilizza il flag `autodetect`

Se specifichi un file CSV, JSON o Fogli Google senza includere una descrizione dello schema incorporata o un file di schema, puoi utilizzare il flag --autodetect per impostare l'opzione "autodetect" su true nel file di definizione della tabella. Quando il rilevamento automatico è attivato, BigQuery tenta di dedurre automaticamente lo schema. Per saperne di più, consulta la sezione Rilevamento automatico dello schema per le origini dati esterne.

Utilizzare il rilevamento automatico con un'origine dati Cloud Storage

Crea un file di definizione della tabella per un'origine dati Cloud Storage:

Utilizza il comando bq mkdef con il flag --autodetect per creare un file di definizione della tabella. Il comando mkdef genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file: /tmp/file_name.
```
bq mkdef \
  --autodetect \
  --source_format=SOURCE_FORMAT \
  "URI" > /tmp/FILE_NAME
```
Sostituisci quanto segue:
- SOURCE_FORMAT: il formato del file
- FILE_NAME: il nome del file di definizione della tabella
- URI: l'URI Cloud Storage
  
  Ad esempio, gs://mybucket/myfile.

(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando nano /tmp/file_name apre il file in nano. Il file dovrebbe avere il seguente aspetto per un'origine dati esterna CSV. La notifica "autodetect" è impostata su true.

{
"autodetect": true,
"csvOptions": {
  "allowJaggedRows": false,
  "allowQuotedNewlines": false,
  "encoding": "UTF-8",
  "fieldDelimiter": ",",
  "quote": "\"",
  "skipLeadingRows": 0
},
"sourceFormat": "CSV",
"sourceUris": [
  "URI"
]
}

(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come maxBadRecords e ignoreUnknownValues. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni che si applicano ai file CSV e Fogli Google. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.

Utilizzare il rilevamento automatico con un'origine dati di Drive

Crea un file di definizione della tabella per un'origine dati di Drive:

Utilizza il comando bq mkdef con il flag --autodetect per creare una definizione di tabella. Il comando mkdef genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file: /tmp/file_name.
```
bq mkdef \
   --autodetect \
   --source_format=SOURCE_FORMAT \
   "URI" > /tmp/FILE_NAME
```
Sostituisci quanto segue:
- SOURCE_FORMAT: il formato del file
- FILE_NAME: il nome del file di definizione della tabella
- URI: l'URI di Drive
  
  Ad esempio, https://drive.google.com/open?id=123ABCD123AbcD123Abcd.
Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando nano /tmp/file_name apre il file in nano. Il file dovrebbe avere il seguente aspetto per un'origine dati esterna di Fogli Google. Avviso "autodetect" è impostato su true.
```
{
"autodetect": true,
"sourceFormat": "GOOGLE_SHEETS",
"sourceUris": [
  "URI"
]
}
```
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come maxBadRecords e ignoreUnknownValues. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni che si applicano ai file CSV e Fogli Google. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.
Per specificare un foglio o un intervallo di celle particolare in un file Fogli Google, aggiungi la proprietà range all'oggetto GoogleSheetsOptions nel file di definizione della tabella. Per eseguire una query su un foglio specifico, specifica il nome del foglio. Per eseguire una query su un intervallo di celle, specifica l'intervallo nel formato: sheet_name!top_left_cell_id:bottom_right_cell_id, ad esempio, "Sheet1!A1:B20". Se il parametro range non è specificato, viene utilizzato il primo foglio del file.

Utilizzare uno schema incorporato

Se non vuoi utilizzare il rilevamento automatico dello schema, puoi creare un file di definizione della tabella fornendo una definizione dello schema incorporata. Per fornire una definizione dello schema in linea, elenca i campi e i tipi di dati nella riga di comando nel seguente formato: FIELD:DATA_TYPE,FIELD:DATA_TYPE.

Utilizzare uno schema incorporato con un'origine dati Cloud Storage o Drive

Crea una definizione di tabella per un'origine dati Cloud Storage o Drive utilizzando una definizione di schema incorporata:

Utilizza il comando bq mkdef con il flag --noautodetect per creare una definizione di tabella. Il comando mkdef genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file: /tmp/file_name.
```
bq mkdef \
  --noautodetect \
  --source_format=SOURCE_FORMAT \
  "URI" \
  FIELD:DATA_TYPE,FIELD:DATA_TYPE > /tmp/FILE_NAME
```
Sostituisci quanto segue
- SOURCE_FORMAT: il formato del file sorgente
- URI: l'URI Cloud Storage o l'URI Drive
  
  Ad esempio, gs://mybucket/myfile per Cloud Storage o https://drive.google.com/open?id=123ABCD123AbcD123Abcd per Drive.
- FIELD:DATA_TYPE,FIELD:DATA_TYPE: la definizione dello schema
  
  Ad esempio, Name:STRING,Address:STRING, ....
- FILE_NAME: il nome del file di definizione della tabella

(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando nano /tmp/file_name apre il file in nano. Il file dovrebbe avere il seguente aspetto. Nota che "autodetect" non è attivato e le informazioni sullo schema vengono scritte nel file di definizione della tabella.

{
"schema": {
  "fields": [
    {
      "name": "FIELD",
      "type": "DATA_TYPE"
    },
    {
      "name": "FIELD",
      "type": "DATA_TYPE"
    }
    ...
  ]
},
"sourceFormat": "NEWLINE_DELIMITED_JSON",
"sourceUris": [
  "URI"
]
}

(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come maxBadRecords e ignoreUnknownValues. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni che si applicano ai file CSV e Fogli Google. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.

Utilizzare un file di schema JSON

Se non vuoi utilizzare il rilevamento automatico o fornire una definizione dello schema incorporata, puoi creare un file dello schema JSON e farvi riferimento quando crei il file di definizione della tabella. Crea manualmente il file dello schema JSON sulla macchina locale. Il riferimento a un file di schema JSON archiviato in Cloud Storage o in Drive non è supportato.

Utilizzare un file di schema con un'origine dati Cloud Storage

Crea una definizione di tabella per un'origine dati Cloud Storage utilizzando un file schema JSON:

Utilizza il comando bq mkdef con il flag --noautodetect per creare una definizione di tabella. Il comando mkdef genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file: /tmp/file_name.
```
bq mkdef \
   --noautodetect \
   --source_format=SOURCE_FORMAT \
   "URI" \
  PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
```
Sostituisci quanto segue:
- SOURCE_FORMAT: il formato del file
- FILE_NAME: il nome del file di definizione della tabella
- URI: l'URI Cloud Storage
  
  Ad esempio, gs://mybucket/myfile.
- PATH_TO_SCHEMA_FILE: la posizione del file dello schema JSON sulla macchina locale

(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando nano /tmp/file_name apre il file in
nano. Il file dovrebbe avere il seguente aspetto. Nota che "autodetect" non è attivato e le informazioni sullo schema vengono scritte nel file di definizione della tabella.

{
"schema": {
  "fields": [
    {
      "name": "FIELD",
      "type": "DATA_TYPE"
    },
    {
      "name": "FIELD",
      "type": "DATA_TYPE"
    }
    ...
  ]
},
"sourceFormat": "NEWLINE_DELIMITED_JSON",
"sourceUris": [
  "URI"
]
}

(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come maxBadRecords e ignoreUnknownValues. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni che si applicano ai file CSV e Fogli Google. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.

Utilizzare un file di schema con un'origine dati Drive

Crea una definizione di tabella per un'origine dati di Drive utilizzando un file di schema JSON:

Utilizza il comando bq mkdef con il flag --noautodetect per creare una definizione di tabella. Il comando mkdef genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file: /tmp/file_name.
```
bq mkdef \
   --noautodetect \
   --source_format=source_format \
   "URI" \
   PATH_TO_SCHEMA_FILE > /tmp/FILE_NAME
```
Sostituisci quanto segue:
- SOURCE_FORMAT: il formato del file sorgente
- URI: l'URI di Drive
  
  Ad esempio, https://drive.google.com/open?id=123ABCD123AbcD123Abcd.
- PATH_TO_SCHEMA_FILE: la posizione del file dello schema JSON sulla macchina locale
- FILE_NAME: il nome del file di definizione della tabella

Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando nano /tmp/file_name apre il file in nano. Il file dovrebbe avere il seguente aspetto. La notifica "autodetect" non è abilitata e le informazioni sullo schema vengono scritte nel file di definizione della tabella.

{
"schema": {
  "fields": [
    {
      "name": "FIELD",
      "type": "DATA_TYPE"
    },
    {
      "name": "FIELD",
      "type": "DATA_TYPE"
    }
    ...
  ]
},
"sourceFormat": "GOOGLE_SHEETS",
"sourceUris": [
  "URI"
]
}

(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare le impostazioni generali come maxBadRecords e ignoreUnknownValues. Non esistono impostazioni di configurazione specifiche per i file di origine JSON, ma esistono impostazioni che si applicano ai file CSV e Fogli Google. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.
Per specificare un foglio o un intervallo di celle particolare in un file Fogli Google, aggiungi la proprietà range all'oggetto GoogleSheetsOptions nel file di definizione della tabella. Per eseguire una query su un foglio specifico, specifica il nome del foglio. Per eseguire una query su un intervallo di celle, specifica l'intervallo nel formato: sheet_name!top_left_cell_id:bottom_right_cell_id, ad esempio, "Sheet1!A1:B20". Se il parametro range non è specificato, viene utilizzato il primo foglio del file.

Crea un file di definizione per i formati autodescrittivi

Avro, Parquet e ORC sono formati autodescrittivi. I file di dati in questi formati contengono le proprie informazioni sullo schema. Se utilizzi uno di questi formati come origine dati esterna, BigQuery recupera automaticamente lo schema utilizzando i dati di origine. Quando crei una definizione di tabella, non devi utilizzare il rilevamento automatico dello schema e non devi fornire una definizione di schema incorporata o un file di schema.

Puoi creare un file di definizione della tabella per i dati Avro, Parquet o ORC archiviati in Cloud Storage o Drive:

Utilizza il comando bq mkdef per creare una definizione di tabella.
```
bq mkdef \
    --source_format=FORMAT \
    "URI" > FILE_NAME
```
Sostituisci quanto segue:
- FORMAT: il formato di origine
- URI: l'URI Cloud Storage o l'URI Drive
  
  Ad esempio, gs://mybucket/myfile per Cloud Storage o https://drive.google.com/open?id=123ABCD123AbcD123Abcd per Drive.
- FILE_NAME: il nome del file di definizione della tabella
(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Il file avrà un aspetto simile al seguente:
```
{
   "sourceFormat": "AVRO",
   "sourceUris": [
   "URI"
    ]
}
```
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare impostazioni generali come maxBadRecords e ignoreUnknownValues. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.

Crea un file di definizione per i dati partizionati in Hive

Utilizza il comando bq mkdef con i flag hive_partitioning_mode e hive_partitioning_source_uri_prefix per creare un file di definizione per i dati partizionati di Hive archiviati in Cloud Storage, Amazon Simple Storage Service (Amazon S3) o Azure Blob Storage.

Crea un file di definizione per Datastore e Firestore

Se utilizzi un'esportazione Datastore o Firestore come origine dati esterna, BigQuery recupera automaticamente lo schema utilizzando i dati di origine autodescrittivi. Quando crei una definizione della tabella, non devi fornire una definizione dello schema incorporata o un file di schema.

Puoi creare un file di definizione della tabella per i dati di esportazione di Datastore e Firestore archiviati in Cloud Storage:

Utilizza il comando bq mkdef per creare una definizione di tabella. Non è necessario utilizzare il flag --noautodetect con i file di backup di Datastore o Firestore. Il rilevamento automatico dello schema è disattivato per questi tipi di file. Il comando mkdef genera un file di definizione della tabella in formato JSON. L'esempio seguente crea una definizione di tabella e scrive l'output in un file: /tmp/file_name.
```
bq mkdef \
--source_format=DATASTORE_BACKUP \
"URI" > /tmp/FILE_NAME
```
Sostituisci quanto segue:
- URI: l'URI Cloud Storage
- FILE_NAME: il nome del file di definizione della tabella
Il formato di origine DATASTORE_BACKUP viene utilizzato sia per Datastore che per Firestore.
(Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio, il comando nano /tmp/file_name apre il file in nano. Il file dovrebbe avere il seguente aspetto. Tieni presente che non è necessaria l'impostazione "autodetect".
```
{
"sourceFormat": "DATASTORE_BACKUP",
"sourceUris": [
  "gs://URI"
]
}
```
(Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o eliminare impostazioni come maxBadRecords e ignoreUnknownValues. Non sono presenti impostazioni di configurazione specifiche per i file di esportazione di Datastore e Firestore. Per saperne di più, consulta ExternalDataConfiguration nel riferimento API.

Crea un file di definizione per Bigtable

Quando crei un file di definizione della tabella per Bigtable, generi manualmente il file in formato JSON. L'utilizzo del comando mkdef per creare una definizione di tabella non è attualmente supportato per le origini dati Bigtable. Il rilevamento automatico dello schema non è supportato anche per Bigtable. Per un elenco delle opzioni di definizione delle tabelle Bigtable, consulta BigtableOptions nel riferimento all'API REST.

Un file di definizione della tabella JSON per Bigtable è simile al seguente. Utilizzando questo file di definizione della tabella, BigQuery legge i dati da una singola famiglia di colonne, interpretando i valori come numeri interi codificati in formato binario.

{
    "sourceFormat": "BIGTABLE",
    "sourceUris": [
        "https://googleapis.com/bigtable/projects/PROJECT_ID/instances/INSTANCE_ID[/appProfiles/APP_PROFILE_ID]/tables/TABLE_NAME"
    ],
    "bigtableOptions": {
        "columnFamilies" : [
            {
                "familyId": "FAMILY_ID",
                "type": "INTEGER",
                "encoding": "BINARY"
            }
        ]
    }
}

Sostituisci quanto segue:

PROJECT_ID: il progetto contenente il cluster Bigtable
INSTANCE_ID: l'ID istanza Bigtable
APP_PROFILE_ID (facoltativo): l'ID del profilo app che vuoi utilizzare per leggere i dati Bigtable. Le impostazioni del profilo dell'app indicano se la tabella esterna utilizza Data Boost o nodi di cui è stato eseguito il provisioning per il calcolo.
TABLE_NAME: il nome della tabella che stai interrogando
FAMILY_ID: l'identificatore della famiglia di colonne

Per saperne di più, consulta Recuperare l'URI Bigtable.

Supporto dei caratteri jolly per i file di definizione della tabella

Se i dati sono suddivisi in più file, puoi utilizzare un carattere jolly asterisco (*) per selezionare più file. L'utilizzo del carattere jolly asterisco deve rispettare le seguenti regole:

L'asterisco può essere visualizzato all'interno del nome dell'oggetto o alla fine del nome dell'oggetto.
L'utilizzo di più asterischi non è supportato. Ad esempio, il percorso gs://mybucket/fed-*/temp/*.csv non è valido.
L'utilizzo di un asterisco con il nome del bucket non è supportato.

Esempi:

L'esempio seguente mostra come selezionare tutti i file in tutte le cartelle che iniziano con il prefisso gs://mybucket/fed-samples/fed-sample:
```
gs://mybucket/fed-samples/fed-sample*
```
L'esempio seguente mostra come selezionare solo i file con estensione .csv nella cartella denominata fed-samples e in qualsiasi sottocartella di fed-samples:
```
gs://mybucket/fed-samples/*.csv
```
L'esempio seguente mostra come selezionare i file con un pattern di denominazione fed-sample*.csv nella cartella denominata fed-samples. Questo esempio non seleziona i file nelle sottocartelle di fed-samples.
```
gs://mybucket/fed-samples/fed-sample*.csv
```

Quando utilizzi lo strumento a riga di comando bq, potresti dover eseguire l'escape dell'asterisco su alcune piattaforme.

Se utilizzi un carattere jolly asterisco, racchiudi il bucket e il nome file tra virgolette. Ad esempio, se hai due file denominati fed-sample000001.csv e fed-sample000002.csv e vuoi utilizzare un asterisco per selezionarli entrambi, l'URI del bucket sarà "gs://mybucket/fed-sample*".

Il carattere jolly * non è consentito durante la creazione di file di definizione delle tabelle per le seguenti origini dati:

Bigtable. Per i dati Bigtable, può essere specificata una sola origine dati. Il valore URI deve essere un URL HTTPS valido per una tabella Bigtable.
Datastore o Firestore. Esportazioni di Datastore o Firestore archiviate in Cloud Storage. Per i backup di Datastore, può essere specificata una sola origine dati. Il valore URI deve terminare con .backup_info o .export_metadata.
Drive. Dati archiviati in Drive.

Passaggi successivi

Scopri come eseguire query sui dati di Cloud Storage.
Scopri come eseguire query sui dati di Drive.
Scopri come eseguire query sui dati Bigtable.