Gestione dei dati delle tabelle

Questo documento descrive come gestire i dati delle tabelle in BigQuery. Puoi lavorare con i dati delle tabelle BigQuery nei seguenti modi:

  • Carica i dati in una tabella
  • Aggiungi o sovrascrivi dati della tabella
  • Sfogliare (o visualizzare l'anteprima) i dati della tabella
  • Esegui query sui dati della tabella
  • Modifica i dati della tabella utilizzando il linguaggio di manipolazione dei dati (DML)
  • Copia i dati della tabella
  • Esportare i dati delle tabelle

Per informazioni sulla gestione degli schemi delle tabelle, consulta Modificare gli schemi delle tabelle.

Prima di iniziare

Concedi ruoli che concedono le autorizzazioni necessarie agli utenti che devono eseguire ciascuna attività in questo documento. Le autorizzazioni necessarie (se presenti) per eseguire un'attività sono elencate nella sezione "Autorizzazioni obbligatorie" dell'attività.

Caricamento di dati in una tabella

Puoi caricare i dati quando crei un oppure puoi crearne una vuota e caricare i dati in un secondo momento. Quando carichi puoi utilizzare il rilevamento automatico degli schemi formati di dati supportati oppure puoi specificare lo schema.

Per ulteriori informazioni sul caricamento dei dati, consulta la documentazione dell'origine il formato e la posizione dei dati:

Aggiunta e sovrascrittura dei dati della tabella

Puoi sovrascrivere i dati della tabella utilizzando un'operazione di caricamento o di query. Puoi aggiungere dati aggiuntivi a una tabella esistente eseguendo un'operazione di caricamento con accodamento o aggiungendo i risultati della query alla tabella.

Per ulteriori informazioni sull'aggiunta o sull'overwriting di una tabella durante il caricamento dei dati, consulta la documentazione relativa al formato dei dati di origine:

Per aggiungere dati a una tabella o sovrascriverne una utilizzando i risultati della query, specifica una tabella di destinazione e imposta l'impostazione di scrittura su:

  • Aggiungi a tabella: aggiunge i risultati della query a una tabella esistente.
  • Sovrascrive tabella: sovrascrive una tabella esistente con lo stesso nome utilizzando i risultati della query.

Puoi utilizzare la seguente query per aggiungere record da una tabella all'altra:

  INSERT INTO .. (
    ,
    ) (SELECT * FROM ..)

Per ulteriori informazioni sull'utilizzo dei risultati delle query per aggiungere o sovrascrivere dati, consulta Scrittura dei risultati di una query.

Esplorare i dati della tabella

Puoi sfogliare i dati delle tabelle per:

  • Utilizzo della console Google Cloud
  • Utilizzo del comando bq head dello strumento a riga di comando bq
  • Chiamata del metodo dell'API tabledata.list
  • Utilizzo delle librerie client

Autorizzazioni obbligatorie

Per sfogliare i dati delle tabelle e delle partizioni, devi disporre dell'autorizzazione Identity and Access Management (IAM) di bigquery.tables.getData.

Ciascuno dei seguenti ruoli IAM predefiniti include le autorizzazioni necessarie per sfogliare i dati delle tabelle e delle partizioni:

  • roles/bigquery.dataViewer
  • roles/bigquery.dataEditor
  • roles/bigquery.dataOwner
  • roles/bigquery.admin

Se disponi dell'autorizzazione bigquery.datasets.create, puoi sfogliare i dati nelle tabelle e nelle partizioni dei set di dati che crei.

Per ulteriori informazioni sui ruoli e sulle autorizzazioni IAM in BigQuery, consulta Ruoli e autorizzazioni predefiniti.

Esplorare i dati della tabella

Per sfogliare i dati della tabella:

Console

  1. Nella console Google Cloud, apri la pagina BigQuery.

    Vai a BigQuery

  2. Nel riquadro Spazio di esplorazione, espandi il progetto e seleziona un set di dati.

  3. Fai clic su una tabella nell'elenco.

  4. Fai clic su Dettagli e prendi nota del valore in Numero di righe. Potresti aver bisogno di questo valore per controllare il punto di partenza dei risultati utilizzando lo strumento a riga di comando o l'API bq.

  5. Fai clic su Anteprima. Viene visualizzato un set di dati di esempio.

    Anteprima tabella

Riga di comando

Esegui il comando bq head con il flag --max_rows per elencare tutte le colonne in per un determinato numero di righe della tabella. Se --max_rows non è specificato, il valore predefinito è 100.

Per sfogliare un sottoinsieme di colonne nella tabella (incluse le colonne nidificate e ripetute colonne), utilizza il flag --selected_fields e inserisci le colonne come virgole elenco separato.

Per specificare il numero di righe da saltare prima di visualizzare i dati della tabella, utilizza il metodo Il flag --start_row=integer (o la scorciatoia -s). Il valore predefinito è 0. Puoi recuperare il numero di righe in una tabella utilizzando il comando bq show per recuperare le informazioni sulla tabella.

Se la tabella che stai sfogliando si trova in un progetto diverso da quello predefinito, aggiungi l'ID progetto al comando nel seguente formato: project_id:dataset.table.

bq head \
--max_rows integer1 \
--start_row integer2 \
--selected_fields "columns" \
project_id:dataset.table

Dove:

  • integer1 è il numero di righe da visualizzare.
  • integer2 è il numero di righe da saltare prima di visualizzare i dati.
  • columns è un elenco di colonne separate da virgole.
  • project_id è l'ID progetto.
  • dataset è il nome del set di dati contenente la tabella.
  • table è il nome della tabella da sfogliare.

Esempi:

Inserisci il seguente comando per elencare tutte le colonne nelle prime 10 righe di mydataset.mytable. mydataset è nel tuo progetto predefinito.

bq head --max_rows=10 mydataset.mytable

Inserisci il seguente comando per elencare tutte le colonne nelle prime 100 righe di mydataset.mytable. mydataset si trova in myotherproject, non è il tuo indirizzo predefinito progetto.

bq head myotherproject:mydataset.mytable

Inserisci il seguente comando per visualizzare solo field1 e field2 in mydataset.mytable. Il comando utilizza il flag --start_row per passare alla riga 100. mydataset.mytable è nel tuo progetto predefinito.

bq head --start_row 100 --selected_fields "field1,field2" mydataset.mytable

Poiché il comando bq head non crea un job di query, lo fanno i comandi bq head non appaiono nella cronologia delle query e non ti vengono addebitati.

API

Sfoglia i dati di una tabella chiamando tabledata.list. Specifica il nome della tabella nel parametro tableId.

Configura questi parametri facoltativi per controllare l'output:

  • maxResults - Numero massimo di risultati da restituire
  • selectedFields: elenco delle colonne da restituire separato da virgole. Se non specificato, vengono restituite tutte le colonne.
  • startIndex: indice in base zero della riga iniziale da leggere

I valori vengono restituiti aggregati in un oggetto JSON che è necessario analizzare, come descritto in tabledata.list documentazione di riferimento.

C#

Prima di provare questo esempio, segui le istruzioni per la configurazione di C# nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery C#.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client. 


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

public class BigQueryBrowseTable
{
    public void BrowseTable(
        string projectId = "your-project-id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        TableReference tableReference = new TableReference()
        {
            TableId = "shakespeare",
            DatasetId = "samples",
            ProjectId = "bigquery-public-data"
        };
        // Load all rows from a table
        PagedEnumerable<TableDataList, BigQueryRow> result = client.ListRows(
            tableReference: tableReference,
            schema: null
        );
        // Print the first 10 rows
        foreach (BigQueryRow row in result.Take(10))
        {
            Console.WriteLine($"{row["corpus"]}: {row["word_count"]}");
        }
    }
}

Go

Prima di provare questo esempio, segui le istruzioni per la configurazione di Go nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione su BigQuery, configura Credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

Librerie client di Cloud per Go l'impaginazione viene eseguita automaticamente per impostazione predefinita, quindi non è necessario implementarla tu, ad esempio: 

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/bigquery"
	"google.golang.org/api/iterator"
)

// browseTable demonstrates reading data from a BigQuery table directly without the use of a query.
// For large tables, we also recommend the BigQuery Storage API.
func browseTable(w io.Writer, 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()

	table := client.Dataset(datasetID).Table(tableID)
	it := table.Read(ctx)
	for {
		var row []bigquery.Value
		err := it.Next(&row)
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintln(w, row)
	}
	return nil
}

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 saperne di più, consulta Configurare l'autenticazione per le librerie client. 

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQuery.TableDataListOption;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableResult;

// Sample to directly browse a table with optional paging
public class BrowseTable {

  public static void runBrowseTable() {
    // TODO(developer): Replace these variables before running the sample.
    String table = "MY_TABLE_NAME";
    String dataset = "MY_DATASET_NAME";
    browseTable(dataset, table);
  }

  public static void browseTable(String dataset, String table) {
    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();

      // Identify the table itself
      TableId tableId = TableId.of(dataset, table);

      // Page over 100 records. If you don't need pagination, remove the pageSize parameter.
      TableResult result = bigquery.listTableData(tableId, TableDataListOption.pageSize(100));

      // Print the records
      result
          .iterateAll()
          .forEach(
              row -> {
                row.forEach(fieldValue -> System.out.print(fieldValue.toString() + ", "));
                System.out.println();
              });

      System.out.println("Query ran successfully");
    } catch (BigQueryException e) {
      System.out.println("Query failed to run \n" + e.toString());
    }
  }
}

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 la documentazione di riferimento dell'API BigQuery Node.js.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per ulteriori informazioni, vedi Configura l'autenticazione per le librerie client.

Le librerie client Cloud per Node.js eseguono la paginazione automaticamente per impostazione predefinita, quindi non è necessario implementarla manualmente, ad esempio: 


// Import the Google Cloud client library and create a client
const {BigQuery} = require('@google-cloud/bigquery');
const bigquery = new BigQuery();

async function browseRows() {
  // Displays rows from "my_table" in "my_dataset".

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // List rows in the table
  const [rows] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .getRows();

  console.log('Rows:');
  rows.forEach(row => console.log(row));
}

PHP

Prima di provare questo esempio, segui le istruzioni di configurazione PHP riportate nella guida rapida all'utilizzo di BigQuery con le librerie client. Per ulteriori informazioni, consulta API PHP 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.

La paginazione avviene automaticamente nelle librerie client di Cloud per PHP utilizzando la funzione di generatore rows, che recupera la pagina successiva dei risultati durante l'iterazione. 

use Google\Cloud\BigQuery\BigQueryClient;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableId   = 'The BigQuery table ID';
// $maxResults = 10;

$maxResults = 10;
$startIndex = 0;

$options = [
    'maxResults' => $maxResults,
    'startIndex' => $startIndex
];
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table($tableId);
$numRows = 0;
foreach ($table->rows($options) as $row) {
    print('---');
    foreach ($row as $column => $value) {
        printf('%s: %s' . PHP_EOL, $column, $value);
    }
    $numRows++;
}

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 la documentazione di riferimento dell'API BigQuery Python.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client. 


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 browse data rows.
# table_id = "your-project.your_dataset.your_table_name"

# Download all rows from a table.
rows_iter = client.list_rows(table_id)  # Make an API request.

# Iterate over rows to make the API requests to fetch row data.
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Download at most 10 rows.
rows_iter = client.list_rows(table_id, max_results=10)
rows = list(rows_iter)
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Specify selected fields to limit the results to certain columns.
table = client.get_table(table_id)  # Make an API request.
fields = table.schema[:2]  # First two columns.
rows_iter = client.list_rows(table_id, selected_fields=fields, max_results=10)
rows = list(rows_iter)
print("Selected {} columns from table {}.".format(len(rows_iter.schema), table_id))
print("Downloaded {} rows from table {}".format(len(rows), table_id))

# Print row data in tabular format.
rows = client.list_rows(table, max_results=10)
format_string = "{!s:<16} " * len(rows.schema)
field_names = [field.name for field in rows.schema]
print(format_string.format(*field_names))  # Prints column headers.
for row in rows:
    print(format_string.format(*row))  # Prints row data.

Ruby

Prima di provare questo esempio, segui le istruzioni per la configurazione di Ruby nel Guida rapida di BigQuery con librerie client. Per ulteriori informazioni, consulta API Ruby BigQuery documentazione di riferimento.

Per autenticarti a BigQuery, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configurare l'autenticazione per le librerie client.

L'impaginazione avviene automaticamente nelle librerie client di Cloud per Ruby utilizzando Table#data e Data#next. 

require "google/cloud/bigquery"

def browse_table
  bigquery = Google::Cloud::Bigquery.new project_id: "bigquery-public-data"
  dataset  = bigquery.dataset "samples"
  table    = dataset.table "shakespeare"

  # Load all rows from a table
  rows = table.data

  # Load the first 10 rows
  rows = table.data max: 10

  # Print row data
  rows.each { |row| puts row }
end

Eseguire query sui dati della tabella

Puoi eseguire query su dati BigQuery utilizzando uno dei seguenti tipi di job di query:

  • Job di query interattive. Di predefinito, BigQuery esegue job di query interattivi (on demand) il prima possibile.

  • Job di query continua (anteprima). Con questi job, la query viene eseguita continuamente, consentendoti di analizzare i dati in entrata in BigQuery in tempo reale e di scrivere i risultati in una tabella BigQuery oppure di esportarli in Bigtable o Pub/Sub. Puoi utilizzare questa funzionalità per eseguire attività urgenti, come creare informazioni e intervenire immediatamente in base a queste, applicare l'inferenza di machine learning (ML) in tempo reale e creare pipeline di dati basate su eventi.

  • Job di query in batch. Con questi lavori, BigQuery mette in coda ogni query batch per tuo conto e poi avvia quando le risorse inattive sono disponibili, in genere entro pochi minuti.

Puoi eseguire job di query utilizzando i seguenti metodi:

Per ulteriori informazioni sull'esecuzione di query sulle tabelle BigQuery, consulta Introduzione all'esecuzione di query sui dati di BigQuery.

Oltre a eseguire query sui dati archiviati nelle tabelle BigQuery, puoi per eseguire query su dati archiviati esternamente. Per ulteriori informazioni, vedi Introduzione alle origini dati esterne.

Modifica dei dati delle tabelle

Puoi modificare i dati in una tabella utilizzando le istruzioni DML (Data Manipulation Language) in SQL. Le istruzioni DML ti consentono di aggiornare, unire, inserire ed eliminare righe nelle tabelle. Per riferimenti alla sintassi ed esempi di ciascun tipo di istruzione DML, consulta Istruzioni Data Manipulation Language in GoogleSQL.

Il dialetto SQL precedente non supporta le istruzioni DML. Per aggiornare o eliminare i dati utilizzando SQL precedente, devi eliminare la tabella e ricrearla con nuovi dati. In alternativa, puoi scrivere una query che modifichi i dati e scrivere i risultati della query in una nuova tabella di destinazione.

Copia dei dati della tabella

Puoi copiare una tabella in uno dei seguenti modi:

  • Utilizzo della console Google Cloud
  • Utilizzo del comando bq cp dello strumento a riga di comando bq
  • Chiamata del metodo API jobs.insert e configurazione di un job di copia
  • Utilizzo delle librerie client

Per ulteriori informazioni sulla copia delle tabelle, consulta Copiare una tabella.

Esportazione dei dati delle tabelle

Puoi esportare i dati della tabella in un bucket Cloud Storage in formato CSV, JSON, Avro o Parquet (anteprima). L'esportazione sulla macchina locale non è supportata, ma puoi scaricare e salvare i risultati delle query utilizzando la console Google Cloud.

Per ulteriori informazioni, vedi Esportazione dei dati di una tabella.

Sicurezza delle tabelle

Per controllare l'accesso alle tabelle in BigQuery, consulta Introduzione ai controlli di accesso alle tabelle.

Passaggi successivi