Accedi ai dati storici

BigQuery ti consente di eseguire query e ripristinare i dati archiviati in BigQuery che sono stati modificati o eliminati nella finestra di viaggio nel tempo. L'accesso a questi dati storici ti consente di recuperare i dati eliminati accidentalmente o di analizzare lo stato esatto dei tuoi dati in un momento specifico del passato senza dover gestire backup separati.

Esegui query sui dati in un momento specifico

Puoi eseguire query sui dati storici di una tabella da qualsiasi momento all'interno della finestra di viaggio nel tempo utilizzando una clausola FOR SYSTEM_TIME AS OF. Questa clausola accetta un'espressione timestamp costante e fa riferimento alla versione della tabella corrente in quel timestamp. La tabella deve essere archiviata in BigQuery e non può essere una tabella esterna. Non esiste un limite alle dimensioni della tabella quando utilizzi SYSTEM_TIME AS OF.

Ad esempio, la seguente query restituisce una versione storica della tabella di un'ora prima:

SELECT *
FROM `mydataset.mytable`
  FOR SYSTEM_TIME AS OF TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 1 HOUR);

Nota: la clausola FOR SYSTEM_TIME AS OF è supportata in GoogleSQL. Per SQL precedente, i decoratori di tempo forniscono una funzionalità equivalente.

Se il timestamp specifica un'ora precedente alla finestra temporale di viaggio nel tempo o precedente alla creazione della tabella, la query non va a buon fine e restituisce un errore simile al seguente:

Invalid snapshot time 1601168925462 for table
myproject:mydataset.table1@1601168925462. Cannot read before 1601573410026.

Dopo aver sostituito una tabella esistente utilizzando l'istruzione CREATE OR REPLACE TABLE, puoi utilizzare FOR SYSTEM_TIME AS OF per eseguire query sulla versione precedente della tabella.

Se la tabella è stata eliminata, non puoi eseguire query sui relativi dati storici direttamente utilizzando FOR SYSTEM_TIME AS OF. La query non va a buon fine e restituisce un errore simile al seguente:

Not found: Table myproject:mydataset.table was not found in location LOCATION

Per accedere ai dati storici di una tabella eliminata, devi invece ripristinare la tabella da un momento specifico.

Ripristina una tabella da un momento specifico

Puoi ripristinare una tabella dai dati storici copiandoli in una nuova tabella. La copia dei dati storici funziona anche se la tabella è stata eliminata o è scaduta, a condizione che venga ripristinata entro la durata della finestra di viaggio nel tempo.

Quando ripristini una tabella dai dati storici, i tag della tabella di origine non vengono copiati nella tabella di destinazione. Inoltre, le informazioni sul partizionamento della tabella non vengono copiate nella tabella di destinazione. Per ricreare lo schema di partizionamento della tabella originale, puoi visualizzare la richiesta di creazione della tabella iniziale in Cloud Logging e utilizzare queste informazioni per partizionare la tabella ripristinata.

Puoi ripristinare solo un'intera tabella. Non puoi ripristinare singole partizioni. Ad esempio, la copia di una partizione utilizzando un decoratore di partizione come bq cp mydataset.mytable$20260712@1418864998000 mydataset.mytable_restored non è supportata.

Puoi ripristinare una tabella eliminata, ma ancora all'interno della finestra di viaggio nel tempo, copiandola in una nuova tabella utilizzando l'indicatore di tempo @<time>. Non puoi eseguire query su una tabella eliminata, anche se utilizzi un decoratore di tempo. Devi prima ripristinarlo.

Utilizza la seguente sintassi con il decoratore di tempo @<time>:

• tableid@TIME dove TIME è il numero di millisecondi dall'epoca di Unix.
• tableid@-TIME_OFFSET dove TIME_OFFSET è l'offset relativo rispetto all'ora corrente, in millisecondi.
• tableid@0: specifica i dati storici più vecchi disponibili.

Per ripristinare una tabella, seleziona una delle seguenti opzioni:

Console

Non puoi annullare l'eliminazione di una tabella utilizzando la console Google Cloud .

bq

1. Nella console Google Cloud , attiva Cloud Shell.

   Attiva Cloud Shell

   Nella parte inferiore della console Google Cloud , viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

2. Per ripristinare una tabella, devi prima determinare un timestamp UNIX di quando la tabella esisteva (in millisecondi). Puoi utilizzare il comando Linux date per generare il timestamp Unix da un valore di timestamp normale:

   date -d '2023-08-04 16:00:34.456789Z' +%s000
   

3. Quindi, utilizza il comando bq copy con il decoratore di viaggi nel tempo @<time> per eseguire l'operazione di copia della tabella.

   Ad esempio, inserisci il seguente comando per copiare la tabella mydataset.mytable al momento 1418864998000 in una nuova tabella mydataset.newtable.

   bq cp mydataset.mytable@1418864998000 mydataset.newtable
   

   (Facoltativo) Specifica il flag --location e imposta il valore sulla tua località.

   Puoi anche specificare un offset relativo. L'esempio seguente copia la versione di una tabella di un'ora fa:

   bq cp mydataset.mytable@-3600000 mydataset.newtable
   

   Nota: se provi a recuperare i dati prima della finestra di viaggio nel tempo o da un momento precedente alla creazione della tabella, riceverai un errore Invalid time travel timestamp. Per saperne di più, consulta Risolvi i problemi di recupero delle tabelle.

Vai

Prima di provare questo esempio, segui le istruzioni di configurazione di Go nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Go.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import (
	"context"
	"fmt"
	"time"

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

// deleteAndUndeleteTable demonstrates how to recover a deleted table by copying it from a point in time
// that predates the deletion event.
func deleteAndUndeleteTable(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()

	ds := client.Dataset(datasetID)
	if _, err := ds.Table(tableID).Metadata(ctx); err != nil {
		return err
	}
	// Record the current time.  We'll use this as the snapshot time
	// for recovering the table.
	snapTime := time.Now()

	// "Accidentally" delete the table.
	if err := client.Dataset(datasetID).Table(tableID).Delete(ctx); err != nil {
		return err
	}

	// Construct the restore-from tableID using a snapshot decorator.
	snapshotTableID := fmt.Sprintf("%s@%d", tableID, snapTime.UnixNano()/1e6)
	// Choose a new table ID for the recovered table data.
	recoverTableID := fmt.Sprintf("%s_recovered", tableID)

	// Construct and run a copy job.
	copier := ds.Table(recoverTableID).CopierFrom(ds.Table(snapshotTableID))
	copier.WriteDisposition = bigquery.WriteTruncate
	job, err := copier.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}

	ds.Table(recoverTableID).Delete(ctx)
	return nil
}

Java

Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CopyJobConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.TableId;

// Sample to undeleting a table
public class UndeleteTable {

  public static void runUndeleteTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_TABLE";
    String recoverTableName = "MY_RECOVER_TABLE_TABLE";
    undeleteTable(datasetName, tableName, recoverTableName);
  }

  public static void undeleteTable(String datasetName, String tableName, String recoverTableName) {
    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();

      // "Accidentally" delete the table.
      bigquery.delete(TableId.of(datasetName, tableName));

      // Record the current time.  We'll use this as the snapshot time
      // for recovering the table.
      long snapTime = System.currentTimeMillis();

      // Construct the restore-from tableID using a snapshot decorator.
      String snapshotTableId = String.format("%s@%d", tableName, snapTime);

      // Construct and run a copy job.
      CopyJobConfiguration configuration =
          CopyJobConfiguration.newBuilder(
                  // Choose a new table ID for the recovered table data.
                  TableId.of(datasetName, recoverTableName),
                  TableId.of(datasetName, snapshotTableId))
              .build();

      Job job = bigquery.create(JobInfo.of(configuration));
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("Undelete table recovered successfully.");
      } else {
        System.out.println(
            "BigQuery was unable to copy the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table not found. \n" + e.toString());
    }
  }
}

Node.js

Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

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

async function undeleteTable() {
  // Undeletes "my_table_to_undelete" from "my_dataset".

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

  /**
   * TODO(developer): Choose an appropriate snapshot point as epoch milliseconds.
   * For this example, we choose the current time as we're about to delete the
   * table immediately afterwards.
   */
  const snapshotEpoch = Date.now();

  // Delete the table
  await bigquery
    .dataset(datasetId)
    .table(tableId)
    .delete();

  console.log(`Table ${tableId} deleted.`);

  // Construct the restore-from table ID using a snapshot decorator.
  const snapshotTableId = `${tableId}@${snapshotEpoch}`;

  // Construct and run a copy job.
  await bigquery
    .dataset(datasetId)
    .table(snapshotTableId)
    .copy(bigquery.dataset(datasetId).table(recoveredTableId));

  console.log(
    `Copied data from deleted table ${tableId} to ${recoveredTableId}`
  );
}

Python

Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.

Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.

import time

from google.cloud import bigquery

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

# TODO(developer): Choose a table to recover.
# table_id = "your-project.your_dataset.your_table"

# TODO(developer): Choose a new table ID for the recovered table data.
# recovered_table_id = "your-project.your_dataset.your_table_recovered"

# TODO(developer): Choose an appropriate snapshot point as epoch
# milliseconds. For this example, we choose the current time as we're about
# to delete the table immediately afterwards.
snapshot_epoch = int(time.time() * 1000)

# ...

# "Accidentally" delete the table.
client.delete_table(table_id)  # Make an API request.

# Construct the restore-from table ID using a snapshot decorator.
snapshot_table_id = "{}@{}".format(table_id, snapshot_epoch)

# Construct and run a copy job.
job = client.copy_table(
    snapshot_table_id,
    recovered_table_id,
    # Must match the source and destination tables location.
    location="US",
)  # Make an API request.

job.result()  # Wait for the job to complete.

print(
    "Copied data from deleted table {} to {}".format(table_id, recovered_table_id)
)

Se prevedi di voler ripristinare una tabella in un secondo momento rispetto a quanto consentito dalla finestra di viaggio nel tempo, crea uno snapshot della tabella. Per saperne di più, consulta Introduzione agli snapshot delle tabelle.

Non puoi ripristinare direttamente una vista logica. Per saperne di più, consulta Ripristina una visualizzazione.

Nota: se elimini una tabella e poi ne crei una nuova con lo stesso nome, puoi ripristinare i dati dalla tabella eliminata originale utilizzando il recupero point-in-time. Il timestamp deve specificare un momento in cui la tabella originale esisteva.

Passaggi successivi

• Scopri di più sugli snapshot delle tabelle.
• Scopri di più sulla conservazione dei dati con l'itinerario cronologico e il fail-safe.
• Scopri di più sulla gestione delle tabelle.