Timestamp di commit nei database in dialetto GoogleSQL

Questo documento descrive come scrivere un timestamp di commit per ogni operazione di inserimento e aggiornamento eseguita con Spanner. Per utilizzare questa funzionalità, imposta l'opzione allow_commit_timestamp su una colonna TIMESTAMP, quindi scrivi il timestamp come parte di ogni transazione.

Panoramica

Il timestamp di commit, basato sulla tecnologia TrueTime, è l'ora in cui viene eseguito il commit di una transazione nel database. L'opzione della colonna allow_commit_timestamp consente di archiviare in modo atomico il timestamp di commit in una colonna. Utilizzando i timestamp di commit archiviati nelle tabelle, puoi determinare l'ordinamento esatto delle mutazioni e creare funzionalità come i log delle modifiche.

Per inserire i timestamp di commit nel database:

  1. Crea una colonna di tipo TIMESTAMP con l'opzione della colonna allow_commit_timestamp impostata su true nella definizione dello schema. Ad esempio:

    CREATE TABLE Performances (
    ...
    LastUpdateTime  TIMESTAMP NOT NULL OPTIONS (allow_commit_timestamp=true)
    ...
) PRIMARY KEY (...);

  2. Se esegui inserimenti o aggiornamenti con DML, utilizza la funzione PENDING_COMMIT_TIMESTAMP per scrivere il timestamp di commit.

    Se esegui inserimenti o aggiornamenti con le mutazioni, utilizza la stringa segnaposto spanner.commit_timestamp() negli inserimenti o negli aggiornamenti della colonna del timestamp di commit. Puoi anche utilizzare la costante del timestamp di commit fornita dalla libreria client. Ad esempio, questa costante nel client Java è Value.COMMIT_TIMESTAMP.

Quando Spanner esegue il commit della transazione utilizzando questi segnaposto come valori delle colonne, il timestamp di commit effettivo viene scritto nella colonna specificata (ad esempio la colonna LastUpdateTime). Puoi quindi utilizzare questo valore della colonna per creare una cronologia degli aggiornamenti della tabella.

Non è garantito che i valori dei timestamp di commit siano univoci. Le transazioni che scrivono in insiemi di campi non sovrapposti potrebbero avere lo stesso timestamp. Le transazioni che scrivono in insiemi di campi sovrapposti hanno timestamp univoci.

I timestamp di commit di Spanner hanno una granularità di microsecondi e vengono convertiti in nanosecondi quando vengono archiviati nelle colonne TIMESTAMP.

Creare ed eliminare una colonna del timestamp di commit

Utilizza l'opzione della colonna allow_commit_timestamp per aggiungere e rimuovere il supporto per i timestamp di commit:

  • Quando crei una nuova tabella per specificare che una colonna supporta i timestamp di commit.
  • Quando modifichi una tabella esistente:
    • per aggiungere una nuova colonna che supporta i timestamp di commit,
    • per modificare una colonna TIMESTAMP esistente in modo che supporti i timestamp di commit,
    • per modificare una colonna TIMESTAMP esistente in modo da rimuovere il supporto per i timestamp di commit

Chiavi e indici

Puoi utilizzare una colonna del timestamp di commit come colonna della chiave primaria o come colonna non chiave. Le chiavi primarie possono essere definite come ASC o DESC.

  • ASC (valore predefinito): le chiavi crescenti sono ideali per rispondere alle query da un momento specifico in poi.
  • DESC: le chiavi decrescenti mantengono le righe più recenti nella parte superiore della tabella. Forniscono un accesso rapido ai record più recenti.

L'opzione allow_commit_timestamp deve essere coerente tra le chiavi primarie delle tabelle padre e figlio. Se l'opzione non è coerente tra le chiavi primarie, Spanner restituisce un errore. L'opzione può essere incoerente solo quando crei o aggiorni lo schema.

L'utilizzo dei timestamp di commit nei seguenti scenari crea hotspot che riducono il rendimento dei dati:

  • Colonna del timestamp di commit come prima parte della chiave primaria di una tabella:

    CREATE TABLE Users (
  LastAccess TIMESTAMP NOT NULL,
  UserId     INT64 NOT NULL,
  ...
) PRIMARY KEY (LastAccess, UserId);

  • La prima parte della chiave primaria di un indice secondario:

    CREATE INDEX UsersByLastAccess ON Users(LastAccess)

    o

    CREATE INDEX UsersByLastAccessAndName ON Users(LastAccess, FirstName)

Gli hotspot riducono il rendimento dei dati, anche con tassi di scrittura bassi. Non si verifica alcun sovraccarico di prestazioni se i timestamp di commit sono abilitati nelle colonne non chiave che non sono indicizzate.

Creare una colonna del timestamp di commit

Il seguente DDL crea una tabella con una colonna che supporta i timestamp di commit.

CREATE TABLE Performances (
    SingerId        INT64 NOT NULL,
    VenueId         INT64 NOT NULL,
    EventDate       Date,
    Revenue         INT64,
    LastUpdateTime  TIMESTAMP NOT NULL OPTIONS (allow_commit_timestamp=true)
) PRIMARY KEY (SingerId, VenueId, EventDate),
  INTERLEAVE IN PARENT Singers ON DELETE CASCADE

L'aggiunta dell'opzione modifica la colonna del timestamp come segue:

  • Puoi utilizzare la stringa segnaposto spanner.commit_timestamp() (o una costante fornita dalla libreria client) per inserimenti e aggiornamenti.
  • La colonna può contenere solo valori nel passato. Per ulteriori informazioni, vedi Fornire il proprio valore per il timestamp.

L'opzione allow_commit_timestamp fa distinzione tra maiuscole e minuscole.

Aggiungere una colonna del timestamp di commit a una tabella esistente

Per aggiungere una colonna del timestamp di commit a una tabella esistente, utilizza l'istruzione ALTER TABLE. Ad esempio, per aggiungere una colonna LastUpdateTime alla tabella Performances, utilizza la seguente istruzione:

ALTER TABLE Performances ADD COLUMN LastUpdateTime TIMESTAMP
    NOT NULL OPTIONS (allow_commit_timestamp=true)

Convertire una colonna del timestamp in una colonna del timestamp di commit

Puoi convertire una colonna del timestamp esistente in una colonna del timestamp di commit, ma in questo caso Spanner deve verificare che i valori del timestamp esistenti siano nel passato. Ad esempio:

ALTER TABLE Performances ALTER COLUMN LastUpdateTime
    SET OPTIONS (allow_commit_timestamp=true)

Non puoi modificare il tipo di dati o l'annotazione NULL di una colonna in un'istruzione ALTER TABLE che include SET OPTIONS. Per maggiori dettagli, vedi Linguaggio di definizione dei dati.

Rimuovere l'opzione del timestamp di commit

Se vuoi rimuovere il supporto per i timestamp di commit da una colonna, utilizza l'opzione allow_commit_timestamp=null in un'istruzione ALTER TABLE. Il comportamento del timestamp di commit viene rimosso, ma la colonna rimane un timestamp. La modifica dell'opzione non altera altre caratteristiche della colonna, come il tipo o la nullabilità (NOT NULL). Ad esempio:

ALTER TABLE Performances ALTER COLUMN LastUpdateTime
    SET OPTIONS (allow_commit_timestamp=null)

Scrivere un timestamp di commit utilizzando un'istruzione DML

Utilizza la funzione PENDING_COMMIT_TIMESTAMP per scrivere il timestamp di commit in un'istruzione DML. Spanner seleziona il timestamp di commit quando viene eseguito il commit della transazione.

La seguente istruzione DML aggiorna la colonna LastUpdateTime nella tabella Performances con il timestamp di commit:

UPDATE Performances SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP()
   WHERE SingerId=1 AND VenueId=2 AND EventDate="2015-10-21"

Il seguente esempio di codice utilizza la PENDING_COMMIT_TIMESTAMP funzione per scrivere il timestamp di commit nella LastUpdateTime colonna.

C++

void DmlStandardUpdateWithTimestamp(google::cloud::spanner::Client client) {
  using ::google::cloud::StatusOr;
  namespace spanner = ::google::cloud::spanner;
  auto commit_result = client.Commit(
      [&client](spanner::Transaction txn) -> StatusOr<spanner::Mutations> {
        auto update = client.ExecuteDml(
            std::move(txn),
            spanner::SqlStatement(
                "UPDATE Albums SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP()"
                "  WHERE SingerId = 1"));
        if (!update) return std::move(update).status();
        return spanner::Mutations{};
      });
  if (!commit_result) throw std::move(commit_result).status();
  std::cout << "Update was successful "
            << "[spanner_dml_standard_update_with_timestamp]\n";
}

C#


using Google.Cloud.Spanner.Data;
using System;
using System.Threading.Tasks;

public class UpdateUsingDmlWithTimestampCoreAsyncSample
{
    public async Task<int> UpdateUsingDmlWithTimestampCoreAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        await connection.OpenAsync();

        using var cmd = connection.CreateDmlCommand("UPDATE Albums SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP() WHERE SingerId = 1");
        int rowCount = await cmd.ExecuteNonQueryAsync();

        Console.WriteLine($"{rowCount} row(s) updated...");
        return rowCount;
    }
}

Vai


import (
	"context"
	"fmt"
	"io"

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

func updateUsingDMLWithTimestamp(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	_, err = client.ReadWriteTransaction(ctx, func(ctx context.Context, txn *spanner.ReadWriteTransaction) error {
		stmt := spanner.Statement{
			SQL: `UPDATE Albums
				SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP()
				WHERE SingerId = 1`,
		}
		rowCount, err := txn.Update(ctx, stmt)
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "%d record(s) updated.\n", rowCount)
		return nil
	})
	return err
}

Java

static void updateUsingDmlWithTimestamp(DatabaseClient dbClient) {
  dbClient
      .readWriteTransaction()
      .run(transaction -> {
        String sql =
            "UPDATE Albums "
                + "SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP() WHERE SingerId = 1";
        long rowCount = transaction.executeUpdate(Statement.of(sql));
        System.out.printf("%d records updated.\n", rowCount);
        return null;
      });
}

Node.js

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

database.runTransaction(async (err, transaction) => {
  if (err) {
    console.error(err);
    return;
  }
  try {
    const [rowCount] = await transaction.runUpdate({
      sql: `UPDATE Albums
        SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP()
        WHERE SingerId = 1`,
    });

    console.log(`Successfully updated ${rowCount} records.`);
    await transaction.commit();
  } catch (err) {
    console.error('ERROR:', err);
  } finally {
    // Close the database when finished.
    database.close();
  }
});

PHP

use Google\Cloud\Spanner\SpannerClient;
use Google\Cloud\Spanner\Transaction;

/**
 * Update data with a DML statement using timestamps.
 *
 * The database and table must already exist and can be created using
 * `create_database`.
 * Example:
 * ```
 * insert_data($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function update_data_with_dml_timestamp(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $database->runTransaction(function (Transaction $t) {
        $rowCount = $t->executeUpdate(
            'UPDATE Albums '
            . 'SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP() WHERE SingerId = 1');
        $t->commit();
        printf('Updated %d row(s).' . PHP_EOL, $rowCount);
    });
}

Python

# instance_id = "your-spanner-instance"
# database_id = "your-spanner-db-id"

spanner_client = spanner.Client()
instance = spanner_client.instance(instance_id)
database = instance.database(database_id)

def update_albums(transaction):
    row_ct = transaction.execute_update(
        "UPDATE Albums "
        "SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP() "
        "WHERE SingerId = 1"
    )

    print("{} record(s) updated.".format(row_ct))

database.run_in_transaction(update_albums)

Ruby

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id
row_count = 0

client.transaction do |transaction|
  row_count = transaction.execute_update(
    "UPDATE Albums SET LastUpdateTime = PENDING_COMMIT_TIMESTAMP() WHERE SingerId = 1"
  )
end

puts "#{row_count} records updated."

Ruby

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

commit_timestamp = client.commit_timestamp

client.commit do |c|
  c.update "Albums", [
    { SingerId: 1, AlbumId: 1, MarketingBudget: 100_000, LastUpdateTime: commit_timestamp },
    { SingerId: 2, AlbumId: 2, MarketingBudget: 750_000, LastUpdateTime: commit_timestamp }
  ]
end

puts "Updated data"

I timestamp di commit possono essere scritti solo nelle colonne annotate con l'opzione allow_commit_timestamp=true.

Se hai mutazioni sulle righe di più tabelle, devi specificare spanner.commit_timestamp() (o la costante della libreria client) per la colonna del timestamp di commit in ogni tabella.

Eseguire una query su una colonna del timestamp di commit

Il seguente esempio esegue una query sulla colonna del timestamp di commit della tabella.

C++

void QueryDataWithTimestamp(google::cloud::spanner::Client client) {
  namespace spanner = ::google::cloud::spanner;

  spanner::SqlStatement select(
      "SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime"
      "  FROM Albums"
      " ORDER BY LastUpdateTime DESC");
  using RowType =
      std::tuple<std::int64_t, std::int64_t, std::optional<std::int64_t>,
                 std::optional<spanner::Timestamp>>;

  auto rows = client.ExecuteQuery(std::move(select));
  for (auto& row : spanner::StreamOf<RowType>(rows)) {
    if (!row) throw std::move(row).status();
    std::cout << std::get<0>(*row) << " " << std::get<1>(*row);
    auto marketing_budget = std::get<2>(*row);
    if (!marketing_budget) {
      std::cout << " NULL";
    } else {
      std::cout << ' ' << *marketing_budget;
    }
    auto last_update_time = std::get<3>(*row);
    if (!last_update_time) {
      std::cout << " NULL";
    } else {
      std::cout << ' ' << *last_update_time;
    }
    std::cout << "\n";
  }
}

C#


using Google.Cloud.Spanner.Data;
using System;
using System.Collections.Generic;
using System.Threading.Tasks;

public class QueryDataWithTimestampColumnAsyncSample
{
    public class Album
    {
        public int SingerId { get; set; }
        public int AlbumId { get; set; }
        public DateTime? LastUpdateTime { get; set; }
        public long? MarketingBudget { get; set; }
    }

    public async Task<List<Album>> QueryDataWithTimestampColumnAsync(string projectId, string instanceId, string databaseId)
    {
        string connectionString = $"Data Source=projects/{projectId}/instances/{instanceId}/databases/{databaseId}";

        using var connection = new SpannerConnection(connectionString);
        using var cmd = connection.CreateSelectCommand("SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime FROM Albums ORDER BY LastUpdateTime DESC");

        var albums = new List<Album>();
        using var reader = await cmd.ExecuteReaderAsync();
        while (await reader.ReadAsync())
        {
            albums.Add(new Album
            {
                SingerId = reader.GetFieldValue<int>("SingerId"),
                AlbumId = reader.GetFieldValue<int>("AlbumId"),
                LastUpdateTime = reader.IsDBNull(reader.GetOrdinal("LastUpdateTime")) ? (DateTime?)null : reader.GetFieldValue<DateTime>("LastUpdateTime"),
                MarketingBudget = reader.IsDBNull(reader.GetOrdinal("MarketingBudget")) ? 0 : reader.GetFieldValue<long>("MarketingBudget")
            });
        }
        return albums;
    }
}

Vai


import (
	"context"
	"fmt"
	"io"
	"strconv"

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

func queryWithTimestamp(w io.Writer, db string) error {
	ctx := context.Background()
	client, err := spanner.NewClient(ctx, db)
	if err != nil {
		return err
	}
	defer client.Close()

	stmt := spanner.Statement{
		SQL: `SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime
				FROM Albums ORDER BY LastUpdateTime DESC`}
	iter := client.Single().Query(ctx, stmt)
	defer iter.Stop()
	for {
		row, err := iter.Next()
		if err == iterator.Done {
			return nil
		}
		if err != nil {
			return err
		}
		var singerID, albumID int64
		var marketingBudget spanner.NullInt64
		var lastUpdateTime spanner.NullTime
		if err := row.ColumnByName("SingerId", &singerID); err != nil {
			return err
		}
		if err := row.ColumnByName("AlbumId", &albumID); err != nil {
			return err
		}
		if err := row.ColumnByName("MarketingBudget", &marketingBudget); err != nil {
			return err
		}
		budget := "NULL"
		if marketingBudget.Valid {
			budget = strconv.FormatInt(marketingBudget.Int64, 10)
		}
		if err := row.ColumnByName("LastUpdateTime", &lastUpdateTime); err != nil {
			return err
		}
		timestamp := "NULL"
		if lastUpdateTime.Valid {
			timestamp = lastUpdateTime.String()
		}
		fmt.Fprintf(w, "%d %d %s %s\n", singerID, albumID, budget, timestamp)
	}
}

Java

static void queryMarketingBudgetWithTimestamp(DatabaseClient dbClient) {
  // Rows without an explicit value for MarketingBudget will have a MarketingBudget equal to
  // null. A try-with-resource block is used to automatically release resources held by
  // ResultSet.
  try (ResultSet resultSet =
      dbClient
          .singleUse()
          .executeQuery(
              Statement.of(
                  "SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime FROM Albums"
                      + " ORDER BY LastUpdateTime DESC"))) {
    while (resultSet.next()) {
      System.out.printf(
          "%d %d %s %s\n",
          resultSet.getLong("SingerId"),
          resultSet.getLong("AlbumId"),
          // We check that the value is non null. ResultSet getters can only be used to retrieve
          // non null values.
          resultSet.isNull("MarketingBudget") ? "NULL" : resultSet.getLong("MarketingBudget"),
          resultSet.isNull("LastUpdateTime") ? "NULL" : resultSet.getTimestamp("LastUpdateTime"));
    }
  }
}

Node.js

// ...

// Imports the Google Cloud client library
const {Spanner} = require('@google-cloud/spanner');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const projectId = 'my-project-id';
// const instanceId = 'my-instance';
// const databaseId = 'my-database';

// Creates a client
const spanner = new Spanner({
  projectId: projectId,
});

// Gets a reference to a Cloud Spanner instance and database
const instance = spanner.instance(instanceId);
const database = instance.database(databaseId);

const query = {
  sql: `SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime
          FROM Albums ORDER BY LastUpdateTime DESC`,
};

// Queries rows from the Albums table
try {
  const [rows] = await database.run(query);

  rows.forEach(row => {
    const json = row.toJSON();

    console.log(
      `SingerId: ${json.SingerId}, AlbumId: ${
        json.AlbumId
      }, MarketingBudget: ${
        json.MarketingBudget ? json.MarketingBudget : null
      }, LastUpdateTime: ${json.LastUpdateTime}`,
    );
  });
} catch (err) {
  console.error('ERROR:', err);
} finally {
  // Close the database when finished
  database.close();
}

PHP

use Google\Cloud\Spanner\SpannerClient;

/**
 * Queries sample data from a database with a commit timestamp column.
 *
 * This sample uses the `MarketingBudget` column. You can add the column
 * by running the `add_column` sample or by running this DDL statement against
 * your database:
 *
 *      ALTER TABLE Albums ADD COLUMN MarketingBudget INT64
 *
 * This sample also uses the 'LastUpdateTime' commit timestamp column. You can
 * add the column by running the `add_timestamp_column` sample or by running
 * this DDL statement against your database:
 *
 * 		ALTER TABLE Albums ADD COLUMN LastUpdateTime TIMESTAMP OPTIONS (allow_commit_timestamp=true)
 *
 * Example:
 * ```
 * query_data_with_timestamp_column($instanceId, $databaseId);
 * ```
 *
 * @param string $instanceId The Spanner instance ID.
 * @param string $databaseId The Spanner database ID.
 */
function query_data_with_timestamp_column(string $instanceId, string $databaseId): void
{
    $spanner = new SpannerClient();
    $instance = $spanner->instance($instanceId);
    $database = $instance->database($databaseId);

    $results = $database->execute(
        'SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime ' .
        ' FROM Albums ORDER BY LastUpdateTime DESC'
    );

    foreach ($results as $row) {
        if ($row['MarketingBudget'] == null) {
            $row['MarketingBudget'] = 'NULL';
        }
        if ($row['LastUpdateTime'] == null) {
            $row['LastUpdateTime'] = 'NULL';
        }
        printf('SingerId: %s, AlbumId: %s, MarketingBudget: %s, LastUpdateTime: %s' . PHP_EOL,
            $row['SingerId'], $row['AlbumId'], $row['MarketingBudget'], $row['LastUpdateTime']);
    }
}

Python

def query_data_with_timestamp(instance_id, database_id):
    """Queries sample data from the database using SQL.

    This updates the `LastUpdateTime` column which must be created before
    running this sample. You can add the column by running the
    `add_timestamp_column` sample or by running this DDL statement
    against your database:

        ALTER TABLE Performances ADD COLUMN LastUpdateTime TIMESTAMP
        OPTIONS (allow_commit_timestamp=true)

    """
    spanner_client = spanner.Client()
    instance = spanner_client.instance(instance_id)

    database = instance.database(database_id)

    with database.snapshot() as snapshot:
        results = snapshot.execute_sql(
            "SELECT SingerId, AlbumId, MarketingBudget FROM Albums "
            "ORDER BY LastUpdateTime DESC"
        )

    for row in results:
        print("SingerId: {}, AlbumId: {}, MarketingBudget: {}".format(*row))

Ruby

# project_id  = "Your Google Cloud project ID"
# instance_id = "Your Spanner instance ID"
# database_id = "Your Spanner database ID"

require "google/cloud/spanner"

spanner = Google::Cloud::Spanner.new project: project_id
client  = spanner.client instance_id, database_id

client.execute("SELECT SingerId, AlbumId, MarketingBudget, LastUpdateTime
                FROM Albums ORDER BY LastUpdateTime DESC").rows.each do |row|
  puts "#{row[:SingerId]} #{row[:AlbumId]} #{row[:MarketingBudget]} #{row[:LastUpdateTime]}"
end

Fornire il proprio valore per la colonna del timestamp di commit

Puoi fornire il tuo valore per la colonna del timestamp di commit, anziché passare spanner.commit_timestamp() (o la costante della libreria client) come valore della colonna. Il valore deve essere un timestamp nel passato. Questa limitazione garantisce che la scrittura dei timestamp sia un'operazione rapida ed economica. Il server restituisce un errore FailedPrecondition se viene specificato un timestamp futuro.

Creare un log delle modifiche

Supponiamo che tu voglia creare un log delle modifiche di ogni mutazione che si verifica in una tabella e poi utilizzarlo per l'audit. Un esempio è una tabella che memorizza la cronologia delle modifiche ai documenti di elaborazione testi. Il timestamp di commit semplifica la creazione del log delle modifiche, perché i timestamp possono applicare l'ordinamento delle voci del log delle modifiche. Puoi creare un log delle modifiche che memorizza la cronologia delle modifiche di un determinato documento utilizzando uno schema come il seguente esempio:

CREATE TABLE Documents (
  UserId     INT64 NOT NULL,
  DocumentId INT64 NOT NULL,
  Contents   STRING(MAX) NOT NULL,
) PRIMARY KEY (UserId, DocumentId);

CREATE TABLE DocumentHistory (
  UserId     INT64 NOT NULL,
  DocumentId INT64 NOT NULL,
  Ts         TIMESTAMP NOT NULL OPTIONS (allow_commit_timestamp=true),
  Delta      STRING(MAX),
) PRIMARY KEY (UserId, DocumentId, Ts),
  INTERLEAVE IN PARENT Documents ON DELETE NO ACTION;

Per creare un log delle modifiche, inserisci una nuova riga in DocumentHistory nella stessa transazione in cui inserisci o aggiorni una riga in Document. Nell'inserimento della nuova riga in DocumentHistory, utilizza il segnaposto spanner.commit_timestamp() (o la costante della libreria client) per indicare a Spanner di scrivere il timestamp di commit nella colonna Ts. L'interleaving della tabella DocumentsHistory con la tabella Documents consente la località dei dati e inserimenti e aggiornamenti più efficienti. Tuttavia, aggiunge anche il vincolo che le righe padre e figlio devono essere eliminate insieme. Per conservare le righe in DocumentHistory dopo l'eliminazione delle righe in Documents, non eseguire l'interleaving delle tabelle.

Ottimizzare le query sui dati recenti con i timestamp di commit

I timestamp di commit consentono un'ottimizzazione di Spanner che può ridurre l'I/O delle query durante il recupero dei dati scritti dopo un determinato periodo di tempo.

Per attivare questa ottimizzazione, la clausola WHERE di una query deve includere un confronto tra la colonna del timestamp di commit di una tabella e un'ora specifica fornita, con i seguenti attributi:

  • Fornisci l'ora specifica come espressione costante: un valore letterale, un parametro o una funzione i cui argomenti vengono valutati come costanti.

  • Confronta se il timestamp di commit è più recente dell'ora specificata, tramite gli operatori > o >=.

  • (Facoltativo) Aggiungi ulteriori limitazioni alla clausola WHERE con AND. L'estensione della clausola con OR non consente l'ottimizzazione della query.

Ad esempio, considera la seguente tabella Performances, che include una colonna del timestamp di commit:

CREATE TABLE Performances (
    SingerId INT64 NOT NULL,
    VenueId INT64 NOT NULL,
    EventDate DATE,
    Revenue INT64,
    LastUpdateTime TIMESTAMP NOT NULL OPTIONS (allow_commit_timestamp=true)
) PRIMARY KEY (SingerId, VenueId, EventDate);

Questa query beneficia dell'ottimizzazione del timestamp di commit descritta in precedenza, perché include un confronto maggiore o uguale a tra la colonna del timestamp di commit della tabella e un'espressione costante, in questo caso un valore letterale:

SELECT * FROM Performances WHERE LastUpdateTime >= "2022-05-01";

Anche la seguente query è idonea per l'ottimizzazione, poiché include un confronto maggiore di tra il timestamp di commit e una funzione i cui argomenti vengono valutati come costanti durante l'esecuzione della query:

SELECT * FROM Performances
  WHERE LastUpdateTime > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 30 DAY);

Passaggi successivi