Specifica di uno schema

BigQuery ti consente di specificare lo schema di una tabella quando carichi i dati in una tabella e quando crei una tabella vuota. In alternativa, puoi utilizzare il rilevamento automatico dello schema per i formati di dati supportati.

Quando carichi file di esportazione Avro, Parquet, ORC, Firestore o Datastore, lo schema viene recuperato automaticamente dai dati di origine autodescrittivi.

Puoi specificare lo schema di una tabella nei seguenti modi:

• Utilizza la console Google Cloud .
• Utilizza l'istruzione SQL CREATE TABLE.
• Inline utilizzando lo strumento a riga di comando bq.
• Crea un file di schema in formato JSON.
• Chiama il metodo jobs.insert e configura la proprietà schema nella configurazione del job load.
• Chiama il metodo tables.insert e configura lo schema nella risorsa tabella utilizzando la proprietà schema.

Dopo aver caricato i dati o creato una tabella vuota, puoi modificare la definizione dello schema della tabella.

Componenti dello schema

Quando specifichi uno schema della tabella, devi fornire il nome e il tipo di dati di ogni colonna. Puoi anche fornire la descrizione, la modalità e il valore predefinito di una colonna.

Nomi delle colonne

Il nome di una colonna può contenere lettere (a-z, A-Z), numeri (0-9) o trattini bassi (_), e deve iniziare con una lettera o un trattino basso. Se utilizzi nomi delle colonne flessibili, BigQuery supporta l'inizio di un nome di colonna con un numero. Fai attenzione quando inizi le colonne con un numero, poiché l'utilizzo di nomi di colonne flessibili con l'API BigQuery Storage di lettura o l'API BigQuery Storage Write richiede una gestione speciale. Per ulteriori informazioni sul supporto dei nomi delle colonne flessibili, consulta Nomi delle colonne flessibili.

I nomi delle colonne hanno una lunghezza massima di 300 caratteri. I nomi delle colonne non possono utilizzare i seguenti prefissi:

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER

Non sono consentiti nomi di colonna duplicati, anche se l'uso delle maiuscole è diverso. Ad esempio, una colonna denominata Column1 è considerata identica a una colonna denominata column1. Per scoprire di più sulle regole di denominazione delle colonne, consulta Nomi delle colonne nella guida di riferimento di GoogleSQL.

Se il nome di una tabella (ad esempio test) è uguale a uno dei nomi delle colonne (ad esempio test), l'espressione SELECT interpreta la colonna test come un STRUCT contenente tutte le altre colonne della tabella. Per evitare questo conflitto, utilizza uno dei seguenti metodi:

• Evita di utilizzare lo stesso nome per una tabella e le relative colonne.

• Assegna alla tabella un alias diverso. Ad esempio, la seguente query assegna l'alias di tabella t alla tabella project1.dataset.test:

  SELECT test FROM project1.dataset.test AS t;
  

• Includi il nome della tabella quando fai riferimento a una colonna. Ad esempio:

  SELECT test.test FROM project1.dataset.test;
  

Nomi delle colonne flessibili

Hai maggiore flessibilità nella denominazione delle colonne, incluso l'accesso esteso ai caratteri in lingue diverse dall'inglese, nonché a simboli aggiuntivi.

I nomi delle colonne flessibili supportano i seguenti caratteri:

• Qualsiasi lettera in qualsiasi lingua, come rappresentata dall'espressione regolare Unicode \p{L}.
• Qualsiasi carattere numerico in qualsiasi lingua rappresentato dall'espressione regolare Unicode \p{N}.
• Qualsiasi carattere di punteggiatura del connettore, inclusi i trattini bassi, come rappresentato dall'espressione regolare Unicode \p{Pc}.
• Un trattino o una lineetta rappresentati dall'espressione regolare Unicode \p{Pd}.
• Qualsiasi segno destinato ad accompagnare un altro carattere, come rappresentato dall'espressione regolare Unicode \p{M}. Ad esempio, accenti, dieresi o caselle di inclusione.
• I seguenti caratteri speciali:
  • Una e commerciale (&) rappresentata dall'espressione regolare Unicode \u0026.
  • Un segno di percentuale (%) rappresentato dall'espressione regolare Unicode \u0025.
  • Un segno di uguale (=) rappresentato dall'espressione regolare Unicode \u003D.
  • Un segno più (+) rappresentato dall'espressione regolare Unicode \u002B.
  • Un segno dei due punti (:) rappresentato dall'espressione regolare Unicode \u003A.
  • Un apostrofo (') rappresentato dall'espressione regolare Unicode \u0027.
  • Un segno di minore (<) rappresentato dall'espressione regolare Unicode \u003C.
  • Un segno di maggiore (>) rappresentato dall'espressione regolare Unicode \u003E.
  • Un simbolo di cancelletto (#) rappresentato dall'espressione regolare Unicode \u0023.
  • Una linea verticale (|) rappresentata dall'espressione regolare Unicode \u007c.
  • Spazio vuoto.

I nomi delle colonne flessibili non supportano i seguenti caratteri speciali:

• Un punto esclamativo (!) rappresentato dall'espressione regolare Unicode \u0021.
• Un segno di virgolette (") rappresentato dall'espressione regolare Unicode \u0022.
• Un simbolo del dollaro ($) rappresentato dall'espressione regolare Unicode \u0024.
• Una parentesi aperta (() rappresentata dall'espressione regolare Unicode \u0028.
• Una parentesi chiusa ()) rappresentata dall'espressione regolare Unicode \u0029.
• Un asterisco (*) rappresentato dall'espressione regolare Unicode \u002A.
• Una virgola (,) rappresentata dall'espressione regolare Unicode \u002C.
• Un punto (.) rappresentato dall'espressione regolare Unicode \u002E. I punti non vengono sostituiti dai trattini bassi nei nomi delle colonne dei file Parquet quando viene utilizzata una mappa dei caratteri dei nomi delle colonne. Per ulteriori informazioni, vedi limitazioni delle colonne flessibili.
• Una barra (/) rappresentata dall'espressione regolare Unicode \u002F.
• Un punto e virgola (;) rappresentato dall'espressione regolare Unicode \u003B.
• Un punto interrogativo (?) rappresentato dall'espressione regolare Unicode \u003F.
• Un simbolo @ (@) rappresentato dall'espressione regolare Unicode \u0040.
• Una parentesi quadra aperta ([) rappresentata dall'espressione regolare Unicode \u005B.
• Una barra rovesciata (\) rappresentata dall'espressione regolare Unicode \u005C.
• Una parentesi quadra chiusa (]) rappresentata dall'espressione regolare Unicode \u005D.
• Un accento circonflesso (^) rappresentato dall'espressione regolare Unicode \u005E.
• Un accento grave (`) rappresentato dall'espressione regolare Unicode \u0060.
• Una parentesi graffa aperta {{) rappresentata dall'espressione regolare Unicode \u007B.
• Una parentesi graffa chiusa (}) rappresentata dall'espressione regolare Unicode \u007D.
• Una tilde (~) rappresentata dall'espressione regolare Unicode \u007E.

Per ulteriori linee guida, vedi Nomi delle colonne.

I caratteri delle colonne espanse sono supportati sia dall'API BigQuery Storage di lettura sia dall'API BigQuery Storage di scrittura. Per utilizzare l'elenco esteso di caratteri Unicode con l'API BigQuery Storage di lettura, devi impostare un flag. Puoi utilizzare l'attributo displayName per recuperare il nome della colonna. L'esempio seguente mostra come impostare un flag con il client Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Per utilizzare l'elenco esteso di caratteri Unicode con l'API BigQuery Storage Write, devi fornire lo schema con la notazione column_name, a meno che tu non stia utilizzando l'oggetto writer JsonStreamWriter. Il seguente esempio mostra come fornire lo schema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

In questo esempio, item_name_column e item_description_column sono nomi segnaposto che devono essere conformi alla convenzione di denominazione dei buffer di protocollo. Tieni presente che le annotazioni column_name hanno sempre la precedenza sui nomi dei segnaposto.

Limitazioni

• I nomi delle colonne flessibili non sono supportati con le tabelle esterne.

Descrizioni delle colonne

Ogni colonna può includere una descrizione facoltativa. La descrizione è una stringa con una lunghezza massima di 1024 caratteri.

Valori predefiniti

Il valore predefinito di una colonna deve essere un valore letterale o una delle seguenti funzioni:

• CURRENT_DATE
• CURRENT_DATETIME
• CURRENT_TIME
• CURRENT_TIMESTAMP
• GENERATE_UUID
• RAND
• SESSION_USER
• ST_GEOGPOINT

Tipi di dati GoogleSQL

GoogleSQL ti consente di specificare i seguenti tipi di dati nello schema. Il tipo di dati è obbligatorio.

Per saperne di più sui tipi di dati in GoogleSQL, vedi Tipi di dati GoogleSQL.

Puoi anche dichiarare un tipo di array quando esegui query sui dati. Per ulteriori informazioni, vedi Utilizzare gli array.

Modalità

BigQuery supporta le seguenti modalità per le colonne. La modalità è facoltativa. Se la modalità non è specificata, la colonna assume il valore predefinito NULLABLE.

Per ulteriori informazioni sulle modalità, vedi mode nella TableFieldSchema.

Modalità di arrotondamento

Quando una colonna è di tipo NUMERIC o BIGNUMERIC, puoi impostare l'opzione colonna rounding_mode, che determina la modalità di arrotondamento dei valori della colonna quando vengono scritti nella tabella. Puoi impostare l'opzione rounding_mode su una colonna di primo livello o su un campo STRUCT. Sono supportate le seguenti modalità di arrotondamento:

• "ROUND_HALF_AWAY_FROM_ZERO": questa modalità (predefinita) arrotonda i casi a metà lontano da zero.
• "ROUND_HALF_EVEN": Questa modalità arrotonda i casi a metà verso la cifra pari più vicina.

Non puoi impostare l'opzione rounding_mode per una colonna che non è di tipo NUMERIC o BIGNUMERIC. Per scoprire di più su questi tipi, consulta la sezione Tipi decimali.

L'esempio seguente crea una tabella e inserisce valori arrotondati in base alla modalità di arrotondamento della colonna:

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

La tabella mytable ha il seguente aspetto:

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

Per ulteriori informazioni, consulta la sezione roundingMode nella TableFieldSchema.

Specifica gli schemi

Quando carichi dati o crei una tabella vuota, puoi specificare lo schema della tabella utilizzando la console Google Cloud o lo strumento a riga di comando bq. La specifica di uno schema è supportata quando carichi file CSV e JSON (delimitati da nuova riga). Quando carichi dati Avro, Parquet, ORC, di esportazione di Firestore o di esportazione di Datastore, lo schema viene recuperato automaticamente dai dati di origine autodescrittivi.

Per specificare uno schema della tabella:

bq --location=location load \
--source_format=format \
project_id:dataset.table_name \
path_to_source \
schema

bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING

bq mk --table project_id:dataset.table schema

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob = loadJob.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

using Google.Cloud.BigQuery.V2;

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.Schema = bigquery.Schema{
		{Name: "name", Type: bigquery.StringFieldType},
		{Name: "post_abbr", Type: bigquery.StringFieldType},
	}
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

import (
	"context"
	"fmt"
	"time"

	"cloud.google.com/go/bigquery"
)

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	sampleSchema := bigquery.Schema{
		{Name: "full_name", Type: bigquery.StringFieldType},
		{Name: "age", Type: bigquery.IntegerFieldType},
	}

	metaData := &bigquery.TableMetadata{
		Schema:         sampleSchema,
		ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
	}
	tableRef := client.Dataset(datasetID).Table(tableID)
	if err := tableRef.Create(ctx, metaData); err != nil {
		return err
	}
	return nil
}

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCS {

  public static void runLoadJsonFromGCS() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              .setSchema(schema)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Json from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(datasetName, tableName);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"

load_job = client.load_table_from_uri(
    uri,
    table_id,
    location="US",  # Must match the destination dataset location.
    job_config=job_config,
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Specificare un file di schema JSON

Se preferisci, puoi specificare lo schema utilizzando un file JSON anziché una definizione di schema incorporata. Un file di schema JSON è costituito da un array JSON contenente quanto segue:

• Il nome della colonna
• Il tipo di dati della colonna
• (Facoltativo) La modalità della colonna (se non specificata, la modalità predefinita è NULLABLE)
• (Facoltativo) I campi della colonna se è di tipo STRUCT
• (Facoltativo) La descrizione della colonna
• (Facoltativo) I tag di policy della colonna, utilizzati per il controllo dell'accesso a livello di campo
• (Facoltativo) La lunghezza massima dei valori della colonna per i tipi STRING o BYTES
• (Facoltativo) La precisione della colonna per i tipi NUMERIC o BIGNUMERIC
• (Facoltativo) La scala della colonna per i tipi NUMERIC o BIGNUMERIC
• (Facoltativo) La collation della colonna per i tipi STRING
• (Facoltativo) Il valore predefinito della colonna
• (Facoltativo) La modalità di arrotondamento della colonna, se la colonna è di tipo NUMERIC o BIGNUMERIC

Creazione di un file di schema JSON

Per creare un file di schema JSON, inserisci un TableFieldSchema per ogni colonna. I campi name e type sono obbligatori. Tutti gli altri campi sono facoltativi.

[
  {
    "name": string,
    "type": string,
    "mode": string,
    "fields": [
      {
        object (TableFieldSchema)
      }
    ],
    "description": string,
    "policyTags": {
      "names": [
        string
      ]
    },
    "maxLength": string,
    "precision": string,
    "scale": string,
    "collation": string,
    "defaultValueExpression": string,
    "roundingMode": string
  },
  {
    "name": string,
    "type": string,
    ...
  }
]

Se la colonna è di tipo RANGE<T>, utilizza il campo rangeElementType per descrivere T, dove T deve essere uno dei seguenti valori: DATE, DATETIME o TIMESTAMP.

[
  {
    "name": "duration",
    "type": "RANGE",
    "mode": "NULLABLE",
    "rangeElementType": {
      "type": "DATE"
    }
  }
]

L'array JSON è indicato dalle parentesi quadre di apertura e chiusura []. Ogni voce della colonna deve essere separata da una virgola: },.

Per scrivere lo schema di una tabella esistente in un file locale:

bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change the table_id variable to the full name of the
# table you want to get schema from.
table_id = "your-project.your_dataset.your_table_name"

# TODO(dev): Change schema_path variable to the path
# of your schema file.
schema_path = "path/to/schema.json"
table = client.get_table(table_id)  # Make an API request.

# Write a schema file to schema_path with the schema_to_json method.
client.schema_to_json(table.schema, schema_path)

with open(schema_path, "r", encoding="utf-8") as schema_file:
    schema_contents = schema_file.read()

# View table properties
print(f"Got table '{table.project}.{table.dataset_id}.{table.table_id}'.")
print(f"Table schema: {schema_contents}")

Puoi utilizzare il file di output come punto di partenza per il tuo file di schema JSON. Se utilizzi questo approccio, assicurati che il file contenga solo l'array JSON che rappresenta lo schema della tabella.

Ad esempio, il seguente array JSON rappresenta uno schema di tabella di base. Questo schema ha tre colonne: qtr (REQUIRED STRING), rep (NULLABLE STRING) e sales (NULLABLE FLOAT).

[
  {
    "name": "qtr",
    "type": "STRING",
    "mode": "REQUIRED",
    "description": "quarter"
  },
  {
    "name": "rep",
    "type": "STRING",
    "mode": "NULLABLE",
    "description": "sales representative"
  },
  {
    "name": "sales",
    "type": "FLOAT",
    "mode": "NULLABLE",
    "defaultValueExpression": "2.55"
  }
]

Utilizzo di un file di schema JSON

Dopo aver creato il file dello schema JSON, puoi specificarlo utilizzando lo strumento a riga di comando bq. Non puoi utilizzare un file schema con la console Google Cloud o l'API.

Fornisci il file schema:

• Se stai caricando dati, utilizza il comando bq load.
• Se stai creando una tabella vuota, utilizza il comando bq mk.

Quando fornisci un file dello schema JSON, questo deve essere archiviato in una posizione leggibile localmente. Non puoi specificare un file di schema JSON archiviato in Cloud Storage o Google Drive.

Specificare un file di schema durante il caricamento dei dati

Per caricare i dati in una tabella utilizzando una definizione dello schema JSON:

bq --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

bq load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change uri variable to the path of your data file.
uri = "gs://your-bucket/path/to/your-file.csv"
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

job_config = bigquery.LoadJobConfig(
    # To use the schema you loaded pass it into the
    # LoadJobConfig constructor.
    schema=schema,
    skip_leading_rows=1,
)

# Pass the job_config object to the load_table_from_file,
# load_table_from_json, or load_table_from_uri method
# to use the schema on a new table.
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)  # Make an API request.
print(f"Loaded {destination_table.num_rows} rows to {table_id}.")

Specifica di un file di schema durante la creazione di una tabella

Per creare una tabella vuota in un set di dati esistente utilizzando un file di schema JSON:

bq mk --table project_id:dataset.table path_to_schema_file

bq mk --table mydataset.mytable ./myschema.json

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(f"Created table {table_id}.")

Specifica di uno schema nell'API

Specifica uno schema della tabella utilizzando l'API:

• Per specificare uno schema durante il caricamento dei dati, chiama il metodo jobs.insert e configura la proprietà schema nella risorsa JobConfigurationLoad.

• Per specificare uno schema quando crei una tabella, chiama il metodo tables.insert e configura la proprietà schema nella risorsa Table.

La specifica di uno schema utilizzando l'API è simile alla procedura per creare un file di schema JSON.

Sicurezza delle tabelle

Per controllare l'accesso alle tabelle in BigQuery, vedi Controllare l'accesso alle risorse con IAM.

Passaggi successivi

• Scopri come specificare colonne nidificate e ripetute in una definizione dello schema.
• Scopri di più sul rilevamento automatico dello schema.
• Scopri di più sul caricamento dei dati in BigQuery.
• Scopri di più su come creare e utilizzare le tabelle.