Commit-Zeitstempel in GoogleSQL-Datenbanken

In diesem Dokument wird beschrieben, wie Sie für jeden Einfüge- und Aktualisierungsvorgang, den Sie mit Cloud Spanner ausführen, einen Commit-Zeitstempel schreiben. Damit Sie diese Funktion verwenden können, legen Sie für eine TIMESTAMP-Spalte die Option allow_commit_timestamp fest, und schreiben Sie dann den Zeitstempel als Teil jeder Transaktion.

Übersicht

Der Commit-Zeitstempel basiert auf der TrueTime-Technologie und ist der Zeitpunkt, zu dem in der Datenbank ein Commit für eine Transaktion durchgeführt wird. Mit der Spaltenoption allow_commit_timestamp können Sie den Commit-Zeitstempel in kleinstmöglicher Form in einer Spalte speichern. Mit den in Tabellen gespeicherten Commit-Zeitstempeln können Sie die genaue Reihenfolge von Mutationen bestimmen und Elemente wie Änderungslogs erstellen.

Führen Sie die folgenden Schritte aus, um Commit-Zeitstempel in eine Datenbank einzufügen:

  1. Erstellen Sie eine Spalte vom Typ TIMESTAMP, wobei die Spaltenoption allow_commit_timestamp in der Schemadefinition auf true gesetzt ist. Beispiel:

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

  2. Wenn Sie Einfügungen oder Aktualisierungen mit DML durchführen, verwenden Sie die Funktion PENDING_COMMIT_TIMESTAMP, um den Commit-Zeitstempel zu schreiben.

    Wenn Sie Einfügungen oder Aktualisierungen mit Mutationen durchführen, verwenden Sie beim Einfügen oder Aktualisieren der Spalte mit den Commit-Zeitstempeln den Platzhalter-String spanner.commit_timestamp(). Sie können auch die von der Clientbibliothek bereitgestellte Konstante für den Commit-Zeitstempel verwenden. Im Java-Client ist diese Konstante beispielsweise Value.COMMIT_TIMESTAMP.

Wenn Cloud Spanner die Transaktion mit diesen Platzhaltern als Spaltenwerte festschreibt, wird der tatsächliche Commit-Zeitstempel in die angegebene Spalte geschrieben (z. B. die Spalte LastUpdateTime). Mit diesem Spaltenwert können Sie dann einen Verlauf der Aktualisierungen der Tabelle erstellen.

Die Werte der Commit-Zeitstempel sind nicht zwangsläufig eindeutig. Transaktionen, die in nicht überlappende Gruppen von Feldern schreiben, haben möglicherweise denselben Zeitstempel. Transaktionen, die in überlappende Gruppen von Feldern schreiben, haben eindeutige Zeitstempel.

Commit-Zeitstempel von Cloud Spanner haben eine Genauigkeit im Mikrosekundenbereich und werden beim Speichern in TIMESTAMP-Spalten in Nanosekunden umgewandelt.

Commit-Zeitstempelspalte erstellen und löschen

Verwenden Sie die Spaltenoption allow_commit_timestamp, um Unterstützung für Commit-Zeitstempel hinzuzufügen und zu entfernen:

  • Beim Erstellen einer neuen Tabelle, um anzugeben, dass eine Spalte Commit-Zeitstempel unterstützt.
  • Beim Ändern einer vorhandenen Tabelle:
    • um eine neue Spalte hinzuzufügen, die Commit-Zeitstempel unterstützt,
    • eine vorhandene TIMESTAMP-Spalte ändern, um Commit-Zeitstempel zu unterstützen,
    • zum Ändern einer vorhandenen TIMESTAMP-Spalte, um die Unterstützung von Commit-Zeitstempeln zu entfernen

Schlüssel und Indexe

Sie können eine Commit-Zeitstempelspalte als Primärschlüsselspalte oder als Nicht-Schlüsselspalte verwenden. Primärschlüssel können als ASC oder DESC definiert werden.

  • ASC (Standardeinstellung): Aufsteigende Schlüssel sind ideal für das Beantworten von Abfragen ab einem bestimmten Zeitpunkt.
  • DESC: Bei absteigenden Schlüsseln bleiben die neuesten Zeilen oben in der Tabelle. Sie bieten schnellen Zugriff auf die neuesten Datensätze.

Die Option allow_commit_timestamp muss für die Primärschlüssel der über- und untergeordneten Tabellen konsistent sein. Wenn die Option für die Primärschlüssel nicht einheitlich festgelegt ist, gibt Spanner einen Fehler zurück. Die Option kann nur dann uneinheitlich festgelegt sein, wenn Sie das Schema erstellen oder aktualisieren.

Werden in den folgenden Szenarien Commit-Zeitstempel verwendet, entstehen Hotspots, wodurch die Datenleistung verringert wird:

  • Spalte der Commit-Zeitstempel als erster Teil des Primärschlüssels einer Tabelle:

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

  • Der erste Teil des Primärschlüssels eines Sekundärindex:

    CREATE INDEX UsersByLastAccess ON Users(LastAccess)

    oder

    CREATE INDEX UsersByLastAccessAndName ON Users(LastAccess, FirstName)

Hotspots verringern die Datenleistung selbst bei niedrigen Schreibraten. Wenn Commit-Zeitstempel für Nicht-Schlüsselspalten ohne Indexierung aktiviert sind, gibt es keine Leistungseinbußen.

Commit-Zeitstempelspalte erstellen

Die folgende DDL erstellt eine Tabelle mit einer Spalte, die Commit-Zeitstempel unterstützt.

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

Durch Hinzufügen dieser Option ergeben sich für die Zeitstempelspalte folgende Änderungen:

  • Sie können den Platzhalterstring spanner.commit_timestamp() bzw. eine Konstante, die von der Clientbibliothek bereitgestellt wird, für Einfügungen und Aktualisierungen verwenden.
  • Die Spalte darf nur Werte enthalten, die in der Vergangenheit liegen. Weitere Informationen finden Sie unter Bereitstellen eines eigenen Wertes für den Zeitstempel.

Bei der Option allow_commit_timestamp wird zwischen Groß- und Kleinschreibung unterschieden.

Zeitstempelspalte in eine vorhandene Tabelle aufnehmen

Verwenden Sie die Anweisung ALTER TABLE, um einer vorhandenen Tabelle eine Commit-Zeitstempelspalte hinzuzufügen. Geben Sie beispielsweise die folgende Anweisung ein, um der Tabelle Performances die Spalte LastUpdateTime hinzuzufügen:

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

Zeitstempelspalte in eine Commit-Zeitstempelspalte konvertieren

Sie können eine vorhandene Zeitstempelspalte in eine Commit-Zeitstempelspalte konvertieren. Dazu muss Spanner jedoch überprüfen, dass die vorhandenen Zeitstempelwerte in der Vergangenheit liegen. Beispiel:

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

In einer ALTER TABLE-Anweisung, die SET OPTIONS enthält, können Sie den Datentyp bzw. die NULL-Anmerkung einer Spalte nicht ändern. Weitere Informationen finden Sie unter Datendefinitionssprache.

Commit-Zeitstempeloption entfernen

Wenn Sie die Unterstützung für Commit-Zeitstempel aus einer Spalte entfernen möchten, verwenden Sie die Option allow_commit_timestamp=null in einer ALTER TABLE-Anweisung. Das Verhalten für Commit-Zeitstempel wird entfernt, aber die Spalte bleibt weiterhin ein Zeitstempel. Durch die Änderung der Option verändern sich keine anderen Eigenschaften der Spalte, wie Typ oder Unwirksamkeit (NOT NULL). Beispiel:

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

Commit-Zeitstempel mit einer DML-Anweisung schreiben

Sie verwenden Sie Funktion PENDING_COMMIT_TIMESTAMP, um den Commit-Zeitstempel in eine DML-Anweisung zu schreiben. Cloud Spanner wählt den Commit-Zeitstempel aus, wenn der Commit der Transaktion durchgeführt wird.

Mit der folgenden DML-Anweisung wird die Spalte LastUpdateTime der Tabelle Performances mit dem Commit-Zeitstempel aktualisiert.

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

Im folgenden Codebeispiel wird die Funktion PENDING_COMMIT_TIMESTAMP zum Schreiben des Commit-Zeitstempels in die Spalte LastUpdateTime verwendet.

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;
    }
}

Go


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"

Commit-Zeitstempel können nur in Spalten geschrieben werden, die mit der Option allow_commit_timestamp=true gekennzeichnet sind.

Wenn Sie Mutationen in Zeilen in mehreren Tabellen haben, müssen Sie spanner.commit_timestamp() bzw. die Konstante der Clientbibliothek für die Commit-Zeitstempelspalte in jeder Tabelle angeben.

Commit-Zeitstempelspalte abfragen

Im folgenden Beispiel wird die Commit-Zeitstempelspalte der Tabelle abgefragt.

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, absl::optional<std::int64_t>,
                 absl::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;
    }
}

Go


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

Eigenen Wert für die Commit-Zeitstempelspalte angeben

Sie können Ihren eigenen Wert für die Commit-Zeitstempelspalte verwenden, anstatt spanner.commit_timestamp() bzw. die Konstante der Clientbilbiothek als Spaltenwert zu übergeben. Der Wert muss ein Zeitstempel sein, der in der Vergangenheit liegt. Mit dieser Einschränkung wird sichergestellt, dass das Schreiben von Zeitstempeln ein kostengünstiger und schneller Vorgang ist. Der Server gibt den Fehler FailedPrecondition zurück, wenn ein zukünftiger Zeitstempel angegeben ist.

Änderungslog erstellen

Angenommen, Sie möchten ein Änderungslog aller Mutationen erstellen, die an einer Tabelle vorgenommen werden, und dieses Änderungslog dann für Audits verwenden. Ein Beispiel wäre eine Tabelle, in der der Änderungsverlauf von Textverarbeitungsdokumenten gespeichert wird. Der Commit-Zeitstempel erleichtert das Erstellen des Änderungslogs, da die entsprechende Reihenfolge der Einträge im Änderungslog durch die Zeitstempel erzwungen werden kann. Sie könnten ein Änderungslog mit dem Änderungsverlauf eines bestimmten Dokuments erstellen, indem Sie ein Schema wie im folgenden Beispiel verwenden:

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;

Zum Erstellen eines Änderungslogs fügen Sie in derselben Transaktion, in der Sie eine Zeile in Document einfügen oder aktualisieren, eine neue Zeile in DocumentHistory ein. Verwenden Sie beim Einfügen der neuen Zeile in DocumentHistory den Platzhalter spanner.commit_timestamp() bzw. die Konstante der Clientbibliothek, damit Cloud Spanner den Commit-Zeitstempel in die Spalte Ts schreibt. Das Verschränken der Tabelle DocumentsHistory mit der Tabelle Documents sorgt für Datenlokalität und effizientere Einfüge- und Aktualisierungsvorgänge. Dadurch ergibt sich jedoch auch die zusätzliche Einschränkung, dass die übergeordneten und untergeordneten Zeilen zusammen gelöscht werden müssen. Sie sollten die Tabellen nicht verschränken, damit die Zeilen in DocumentHistory beibehalten werden, nachdem Zeilen in Documents gelöscht wurden.

Abfragen aktueller Daten mit Commit-Zeitstempeln optimieren

Commit-Zeitstempel ermöglichen eine Spanner-Optimierung, die die Abfrage-E/A beim Abrufen von Daten reduzieren kann, die nach einem bestimmten Zeitpunkt geschrieben wurden.

Für diese Optimierung muss die Anweisung WHERE einer Abfrage einen Vergleich zwischen der Commit-Zeitstempelspalte einer Tabelle und einem von Ihnen angegebenen Zeitpunkt mit folgenden Attributen enthalten:

  • Geben Sie die genaue Zeit als konstanten Ausdruck an: ein Literal, ein Parameter oder eine Funktion, deren eigene Argumente als Konstanten ausgewertet werden.

  • Vergleichen Sie, ob der Commit-Zeitstempel neuer als die angegebene Zeit ist. Verwenden Sie dazu entweder den Operator > oder >=.

  • Optional können Sie der Anweisung WHERE mit AND weitere Einschränkungen hinzufügen. Wenn Sie die Anweisung mit OR erweitern, wird die Abfrage von dieser Optimierung ausgeschlossen.

Sehen Sie sich beispielsweise die folgende Tabelle Performances mit einer Commit-Zeitstempelspalte an:

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);

Diese Abfrage profitiert von der oben beschriebenen Optimierung durch Commit-Zeitstempel, da sie einen „Größer als oder gleich“-Vergleich zwischen der Commit-Zeitstempelspalte der Tabelle und einem konstanten Ausdruck enthält – in diesem Fall ein Literal:

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

Die folgende Abfrage kommt ebenfalls für die Optimierung infrage, da sie einen „Größer als“-Vergleich zwischen dem Commit-Zeitstempel und einer Funktion enthält, deren Argumente während der Ausführung der Abfrage alle als Konstanten ausgewertet werden:

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

Nächste Schritte