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

In questa pagina viene descritto come creare un file di definizione della tabella per un dato esterno sorgente. Un'origine dati esterna è un'origine dati su cui puoi eseguire query direttamente anche se i dati non sono archiviati in BigQuery.

Un file di definizione della tabella contiene la definizione dello schema di una tabella esterna come il formato dei dati della tabella e le proprietà correlate. Quando Creare un file di definizione della tabella, puoi utilizzare lo schema di rilevamento automatico per definire lo schema per un'origine dati esterna. Puoi fornire lo schema in linea oppure puoi fornire un file JSON contenente la definizione dello schema.

I file di definizione delle tabelle vengono utilizzati con lo strumento a riga di comando bq. La in un file di definizione della tabella si applicano anche alla creazione ExternalDataConfiguration quando utilizzi l'API REST. I file di definizione delle tabelle non vengono utilizzati durante la creazione per creare una tabella esterna usando la console Google Cloud.

Puoi creare file di definizione delle tabelle per descrivere una situazione permanente o temporanea tabella esterna 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 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, ti occorre l'URI dell'origine dati:

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

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

Usa il flag autodetect

Se specifichi un file CSV, JSON o Fogli Google senza includere un file descrizione dello schema o di un file di schema, puoi utilizzare il flag --autodetect per impostare l'opzione "autodetect" su true nel file di definizione della tabella. Quando di rilevamento automatico sia abilitato, BigQuery fa il possibile automaticamente lo schema. Per ulteriori informazioni, vedi Rilevamento automatico dello schema per origini dati esterne.

Utilizza il rilevamento automatico con un'origine dati Cloud Storage

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

  1. Usa il comando bq mkdef con il flag --autodetect per creare un file di definizione della tabella. mkdef genera un file di definizione della tabella in formato JSON. Le seguenti esempio 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: URI Cloud Storage

      Ad esempio, gs://mybucket/myfile.

  2. (Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio: il comando nano /tmp/file_name apre il file nano. Il file deve avere il seguente aspetto per un file CSV di dati esterni sorgente. Nota che "autodetect" è impostato su true.

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

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni generali quali maxBadRecords e ignoreUnknownValues. Là non ci sono impostazioni di configurazione specifiche per i file di origine JSON, ma sono impostazioni applicabili ai file CSV e Fogli Google . Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

Utilizzare il rilevamento automatico con un'origine dati Drive

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

  1. Usa 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. Nell'esempio che segue 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.

  2. 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. Avvisi "autodetect" impostata su true.

    {
"autodetect": true,
"sourceFormat": "GOOGLE_SHEETS",
"sourceUris": [
  "URI"
]
}

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni generali quali maxBadRecords e ignoreUnknownValues. Là non ci sono impostazioni di configurazione specifiche per i file di origine JSON, ma sono impostazioni applicabili ai file CSV e Fogli Google . Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

  4. Per specificare un particolare foglio o un intervallo di celle in un file di Fogli Google, aggiungi la proprietà range al file di definizione della tabella. Per eseguire query su un foglio specifico, e specificare 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 viene specificato, viene utilizzato il primo foglio del file.

Utilizza uno schema in linea

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

Utilizza uno schema in linea con un'origine dati Cloud Storage o Drive

Crea una definizione di tabella per Cloud Storage o Drive utilizzando una definizione di schema in linea:

  1. Usa il comando bq mkdef con il flag --noautodetect per creare una definizione di tabella. mkdef genera un file di definizione della tabella in formato JSON. Le seguenti esempio 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 di origine

    • URI: URI Cloud Storage o l'URI di 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: lo schema definizione

      Ad esempio, Name:STRING,Address:STRING, ....

    • FILE_NAME: il nome del file di definizione della tabella

  2. (Facoltativo) Apri il file di definizione della tabella in un editor di testo. Ad esempio: il comando nano /tmp/file_name apre il file nano. Il file dovrebbe essere simile al seguente. Nota che "autodetect" non è abilitato 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"
]
}

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni generali quali maxBadRecords e ignoreUnknownValues. Là non ci sono impostazioni di configurazione specifiche per i file di origine JSON, ma sono impostazioni applicabili ai file CSV e Fogli Google . Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

Utilizza un file di schema JSON

Se non vuoi utilizzare il rilevamento automatico o fornire una definizione di schema in linea, puoi creare un file di schema JSON e farvi riferimento durante la creazione della tabella file di definizione. Crea manualmente il file di schema JSON sulla macchina locale. Riferimento a un file di schema JSON archiviato in Cloud Storage o su Drive non è supportato.

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

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

  1. Usa il comando bq mkdef con il flag --noautodetect per creare una definizione di tabella. mkdef genera un file di definizione della tabella in formato JSON. Le seguenti esempio 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: il valore URI Cloud Storage

      Ad esempio, gs://mybucket/myfile.

    • PATH_TO_SCHEMA_FILE: la posizione dello schema JSON sul tuo computer locale

  2. (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 essere simile al seguente. Nota che "autodetect" non è abilitato 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"
]
}

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni generali quali maxBadRecords e ignoreUnknownValues. Là non ci sono impostazioni di configurazione specifiche per i file di origine JSON, ma sono impostazioni applicabili ai file CSV e Fogli Google . Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

Utilizzare un file di schema con un'origine dati Drive

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

  1. Usa il comando bq mkdef con il flag --noautodetect per creare una definizione di tabella. mkdef genera un file di definizione della tabella in formato JSON. Le seguenti esempio 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 di origine

    • URI: l'URI di Drive

      Ad esempio, https://drive.google.com/open?id=123ABCD123AbcD123Abcd.

    • PATH_TO_SCHEMA_FILE: la posizione dello schema JSON sul tuo computer locale

    • FILE_NAME: il nome del file di definizione della tabella

  2. 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 è abilitato e il 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"
]
}

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni generali quali maxBadRecords e ignoreUnknownValues. Là non ci sono impostazioni di configurazione specifiche per i file di origine JSON, ma sono impostazioni applicabili ai file CSV e Fogli Google . Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

  4. Per specificare un particolare foglio o un intervallo di celle in un file di Fogli Google, aggiungi la proprietà range al file di definizione della tabella. Per eseguire query su un foglio specifico, e specificare 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 viene specificato, viene utilizzato il primo foglio del file.

Creare un file di definizione per i formati autodescrittivi

Avro, Parquet e ORC sono formati autodescritti. I file di dati in questi contengono informazioni sullo schema. Se utilizzi uno di questi formati un'origine dati esterna, BigQuery recupera automaticamente utilizzando i dati di origine. Quando crei una definizione di tabella, non è necessario per utilizzare il rilevamento automatico dello schema e non è necessario fornire uno schema in linea di definizione o di schema.

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

  1. Usa il comando bq mkdef per creare una definizione della tabella.

    bq mkdef \
    --source_format=FORMAT \
    "URI" > FILE_NAME

    Sostituisci quanto segue:

    • FORMAT: il formato di origine

    • URI: URI Cloud Storage o l'URI di 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

  2. (Facoltativo) Apri il file di definizione della tabella in un editor di testo. Il file viene visualizzato simile al seguente:

    {
   "sourceFormat": "AVRO",
   "sourceUris": [
   "URI"
    ]
}

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni generali quali maxBadRecords e ignoreUnknownValues. Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

Crea un file di definizione per i dati partizionati in hive

Usa il comando bq mkdef con hive_partitioning_mode e hive_partitioning_source_uri_prefix flag a creare un file di definizione per i dati partizionati in 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 di Datastore o Firestore come dati esterni origine, BigQuery recupera automaticamente lo schema utilizzando autodescrittivi dei dati di origine. Quando crei una definizione di tabella, non è necessario fornire una definizione o un file di schema incorporato.

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

  1. Usa il comando bq mkdef per creare una definizione della tabella. Non è necessario utilizzare --noautodetect con i file di backup di Datastore o Firestore. Schema il rilevamento automatico è disabilitato per questi tipi di file. Il comando mkdef genera di definizione delle tabelle in formato JSON. L'esempio seguente crea una tabella e scrive l'output in un file: /tmp/file_name.

    bq mkdef \
--source_format=DATASTORE_BACKUP \
"URI" > /tmp/FILE_NAME

    Sostituisci quanto segue:

    Il formato di origine DATASTORE_BACKUP viene utilizzato per entrambi Datastore e Firestore.

  2. (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 essere simile al seguente. Tieni presente che non è necessario Impostazione "autodetect".

    {
"sourceFormat": "DATASTORE_BACKUP",
"sourceUris": [
  "gs://URI"
]
}

  3. (Facoltativo) Modifica manualmente il file di definizione della tabella per modificare, aggiungere o Elimina impostazioni quali maxBadRecords e ignoreUnknownValues. Là non sono impostazioni di configurazione specifiche di Datastore Firestore. Per ulteriori informazioni, vedi ExternalDataConfiguration nel riferimento API.

Crea un file di definizione per Bigtable

Quando crei un file di definizione della tabella per Bigtable, puoi generare il file in formato JSON. Utilizzo del comando mkdef per creare una tabella non è attualmente supportata per le origini dati Bigtable. Per Bigtable non è supportato nemmeno il rilevamento automatico dello schema. Per un elenco di Opzioni di definizione delle tabelle Bigtable, consulta BigtableOptions pollici il riferimento dell'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 un con una singola famiglia di colonne, interpretando i valori come numeri interi con codifica binaria.

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

Sostituisci quanto segue:

  • PROJECT_ID: il progetto contenente Cluster Bigtable
  • INSTANCE_ID: l'ID dell'istanza Bigtable
  • TABLE_NAME: il nome della tabella su cui stai eseguendo la query
  • FAMILY_ID: l'identificatore della famiglia di colonne

Per ulteriori informazioni, vedi Recupero dell'URI Bigtable.

Supporto dei caratteri jolly per i file di definizione delle tabelle

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

  • L'asterisco può essere visualizzato all'interno del nome dell'oggetto o alla fine dell'oggetto .
  • L'uso 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 file con estensione .csv nella cartella denominata fed-samples e in eventuali sottocartelle di fed-samples:

    gs://mybucket/fed-samples/*.csv

  • L'esempio seguente mostra come selezionare file con un modello 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 usi lo strumento a riga di comando bq, potresti dover inserire il carattere di escape in alcune piattaforme di terze parti.

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

Il carattere jolly * non è consentito durante la creazione dei file di definizione della tabella per le seguenti origini dati:

  • Bigtable. Per i dati Bigtable, un solo dato è possibile specificare l'origine. Il valore dell'URI deve essere un URL HTTPS valido per un Bigtable.
  • Datastore o Firestore. Datastore Firestore o Firestore archiviate di archiviazione ideale in Cloud Storage. Per Datastore è possibile specificare una sola origine dati. Il valore dell'URI deve terminare con .backup_info o .export_metadata.
  • Drive. Dati archiviati su Drive.

Passaggi successivi