Confirma marcas de tiempo en las bases de datos de dialectos de GoogleSQL

En este tema, se describe cómo escribir una marca de tiempo de confirmación para cada inserción y actualización. que realizas con Spanner. Para usar esta función, configura la opción allow_commit_timestamp en una columna TIMESTAMP y, luego, escribe la marca de tiempo como parte de cada transacción.

Descripción general

La marca de tiempo de confirmación, según TrueTime tecnología, es el momento en que un que la transacción se confirme en la base de datos. La columna allow_commit_timestamp te permite almacenar, de forma atómica, la marca de tiempo de confirmación en una columna. Con las marcas de tiempo de confirmación almacenadas en las tablas, puedes determinar el orden exacto de las mutaciones y compilar funciones como los registros de cambios.

Para insertar marcas de tiempo de confirmación en tu base de datos, completa los siguientes pasos:

1. Crea una columna con el tipo TIMESTAMP con la opción allow_commit_timestamp de columna configurada como true en la definición del esquema. Por ejemplo:

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

2. Si realizas inserciones o actualizaciones con DML, usa la función PENDING_COMMIT_TIMESTAMP para escribir la marca de tiempo de confirmación.

   Si realizas inserciones o actualizaciones con mutaciones usa la cadena de marcador de posición spanner.commit_timestamp() en las inserciones o actualizaciones de tu confirmación marca de tiempo. También puedes usar de confirmación de la marca de tiempo que proporciona la biblioteca cliente. Por ejemplo, esta en el cliente de Java es Value.COMMIT_TIMESTAMP.

Cuando Spanner confirma la transacción con estos marcadores de posición como columna valores, la marca de tiempo de confirmación real se escribe en la columna especificada (para ejemplo: la columna LastUpdateTime). Luego, puedes usar este valor de columna para crear un historial de actualizaciones de la tabla.

No se garantiza que los valores de marca de tiempo de confirmación sean únicos. Las transacciones que escriben en conjuntos de campos que no se superponen podrían tener la misma marca de tiempo. Las transacciones que escriben en conjuntos de campos que se superponen tienen marcas de tiempo únicas.

Las marcas de tiempo de confirmación de Spanner tienen un nivel de detalle de microsegundos y se convierten a nanosegundos cuando se almacenan en columnas TIMESTAMP.

Crea y borra una columna de marcas de tiempo de confirmación

Usa la opción allow_commit_timestamp para agregar y quitar la asistencia de las marcas de tiempo de confirmación:

• Cuando creas una tabla nueva para especificar que una columna admite marcas de tiempo de confirmación
• Cuando modificas una tabla existente:
  • para agregar una columna nueva que admita marcas de tiempo de confirmación
  • para modificar una columna TIMESTAMP existente a fin de que admita marcas de tiempo de confirmación
  • Para modificar una columna TIMESTAMP existente a fin de quitar la compatibilidad de la marca de tiempo de confirmación

Claves e índices

Puedes usar una columna de marcas de tiempo de confirmación como una columna de clave principal o como una columna sin clave. Las claves principales se pueden definir como ASC o DESC.

• ASC (predeterminado): Las claves ascendentes son ideales para responder consultas de un tiempo específico.
• DESC: Las claves descendentes mantienen las filas más recientes en la parte superior de la tabla. Proporcionan acceso rápido a los registros más recientes.

La opción allow_commit_timestamp debe ser coherente en todas las claves principales de las tablas superiores y secundarias. Si la opción no es coherente en todas las claves primarias, Spanner muestra un error. El único momento en que la opción puede ser incoherente es el momento en que se crea o actualiza el esquema.

El uso de marcas de tiempo de confirmación en las siguientes situaciones crea hotspots que reducen el rendimiento de los datos:

• En una columna de marca de tiempo de confirmación que funciona como la primera parte de la clave primaria de una tabla:

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

• En la primera parte de la clave primaria de un índice secundario:

  CREATE INDEX UsersByLastAccess ON Users(LastAccess)
  

  o

  CREATE INDEX UsersByLastAccessAndName ON Users(LastAccess, FirstName)
  

Los hotspots reducen el rendimiento de los datos, incluso con tasas de escritura bajas. No se produce una sobrecarga de rendimiento si las marcas de tiempo de confirmación se habilitan en columnas sin clave que no estén indexadas.

Crea una columna de marcas de tiempo de confirmación

Con el siguiente DDL, se crea una tabla con una columna que admite marcas de tiempo de confirmación.

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

Cuando se agrega la opción, se modifica la columna de marcas de tiempo de la siguiente manera:

• Puedes usar la string del marcador de posición spanner.commit_timestamp() (o una constante que proporcione la biblioteca cliente) para realizar inserciones y actualizaciones.
• La columna solo puede contener valores anteriores. Si quieres obtener más información, consulta la sección sobre cómo proporcionar tu propio valor para la marca de tiempo.

La opción allow_commit_timestamp distingue entre mayúsculas y minúsculas.

Agrega una columna de marcas de tiempo de confirmación a una tabla existente

Para agregar una columna de marcas de tiempo de confirmación a una tabla existente, usa la declaración ALTER TABLE. Por ejemplo, para agregar una columna LastUpdateTime a la tabla Performances, usa la siguiente instrucción:

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

Convierte una columna de marcas de tiempo en una columna de marcas de tiempo de confirmación

Puedes convertir una columna de marca de tiempo existente en una columna de marca de tiempo de confirmación. pero, para ello, Spanner debe validar que la configuración valores de marca de tiempo son del pasado. Por ejemplo:

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

No puedes cambiar el tipo de datos o la anotación NULL de una columna en una declaración ALTER TABLE que incluya SET OPTIONS. Para obtener más detalles, consulta Lenguaje de definición de datos.

Quita la opción de marca de tiempo de confirmación

Si deseas quitar la asistencia de marca de tiempo de confirmación de una columna, usa la opción allow_commit_timestamp=null en una declaración ALTER TABLE. Se quita el comportamiento de la marca de tiempo de confirmación, pero la columna sigue siendo una marca de tiempo. El cambio de la opción no altera otras características de la columna, como el tipo o la capacidad de nulidad (NOT NULL). Por ejemplo:

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

Escribe una marca de tiempo de confirmación con una declaración DML

Usa la función PENDING_COMMIT_TIMESTAMP para escribir la marca de tiempo de confirmación en una declaración DML. Spanner selecciona la marca de tiempo de confirmación cuando la transacción confirmaciones.

Nota: Después de llamar a la función PENDING_COMMIT_TIMESTAMP, la tabla y cualquier índice derivado no se podrá leer en ninguna instrucción de SQL futura de la transacción. Debido a esto, el flujo de cambios no puede extraer el valor anterior para el Columna que tiene una marca de tiempo de confirmación pendiente, si la columna se vuelve a modificar más adelante en la misma transacción. Debes escribir las marcas de tiempo de confirmación en una transacción para evitar la posibilidad de intentar leer el desde una tabla de particiones. Si intentas leer la tabla, Spanner producirá un error.

La siguiente declaración DML actualiza la columna LastUpdateTime en el Tabla Performances con la marca de tiempo de confirmación:

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

En el siguiente ejemplo de código, se usa la función PENDING_COMMIT_TIMESTAMP para escribir la marca de tiempo de confirmación en la columna LastUpdateTime.

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"

Las marcas de tiempo de confirmación solo se pueden escribir en columnas anotadas con la opción allow_commit_timestamp=true.

Si tienes mutaciones en filas de varias tablas, debes especificar spanner.commit_timestamp() (o la constante de la biblioteca cliente) en la columna de marcas de tiempo de confirmación de cada tabla.

Consulta una columna de marcas de tiempo de confirmación

En el siguiente ejemplo, se consulta la columna de marcas de tiempo de confirmación de la tabla.

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

Proporciona tu propio valor para la columna de marca de tiempo de confirmación

Puedes proporcionar tu propio valor para la columna de marcas de tiempo de confirmación, en lugar de pasar spanner.commit_timestamp() (o la constante de la biblioteca cliente) como el valor de la columna. El valor debe ser una marca de tiempo anterior. Esta restricción garantiza que la escritura de marcas de tiempo sea una operación rápida y económica. El servidor muestra un error FailedPrecondition si se especifica una marca de tiempo futura.

Nota: El valor CURRENT_TIMESTAMP no se basa en el tiempo real. Entonces, el valor de retornos no necesariamente es pasado y no se puede utilizar para comparar con un de confirmación de la marca de tiempo.

Crear un registro de cambios

Supongamos que deseas crear un registro de cambios de todas las mutaciones que se producen en una tabla y, luego, usarlo para realizar auditorías. Un ejemplo sería una tabla que almacena el historial de cambios de los documentos de procesamiento de texto. Las marcas de tiempo de confirmación facilitan la creación del registro de cambios, ya que pueden aplicar de forma forzosa el orden de las entradas del registro de cambios. Puedes crear un registro de cambios que almacene el historial de cambios de un documento determinado mediante un esquema como se muestra en el siguiente ejemplo:

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;

Para crear un registro de cambios, inserta una fila nueva en el DocumentHistory en la misma transacción en la que insertas o actualizas una fila en el Document. En la sección de la fila nueva en DocumentHistory, usa el marcador de posición spanner.commit_timestamp() (o constante de la biblioteca cliente) para decirle Spanner escribe la marca de tiempo de confirmación en la columna Ts. Intercalar la tabla DocumentsHistory con la tabla Documents permitirá la ubicación de datos y la realización de inserciones y actualizaciones más eficientes. Sin embargo, también agrega la restricción de que las filas superiores y secundarias se deben borrar juntas. Para mantener las filas de DocumentHistory después de que se borren las filas de Documents, no intercales las tablas.

Optimiza las consultas de datos recientes con marcas de tiempo de confirmación

Las marcas de tiempo de confirmación habilitan una optimización de Spanner que puede reducir la E/S de consulta cuando se recuperan datos escritos después de un tiempo.

Para activar esta optimización, la cláusula WHERE de una consulta debe incluir un comparación entre la columna de marca de tiempo de confirmación de una tabla y una hora específica que proporcionas con los siguientes atributos:

• Proporciona la hora específica como una expresión constante: un literal, una parámetro o una función cuyos propios argumentos se evalúan como constantes.

• Compara si la marca de tiempo de confirmación es más reciente que la en un momento determinado, a través de los operadores > o >=.

• De manera opcional, agrega más restricciones a la cláusula WHERE con AND. Si extiendes la cláusula con OR, la consulta no se beneficia de esta optimización.

Por ejemplo, considera la siguiente tabla Performances, que incluye en una columna de marcas de tiempo de confirmación:

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

Esta consulta se beneficia de la optimización de la marca de tiempo de confirmación que se describe anteriormente, ya que tiene una comparación mayor o igual entre la columna de marca de tiempo de confirmación de la tabla y una expresión constante, en este Caso, literal:

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

La siguiente consulta también califica para la optimización, ya que tiene un comparación mayor que entre la marca de tiempo de confirmación y una función cuyos argumentos se evalúan como constantes durante la ejecución de la consulta:

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

¿Qué sigue?

• Usa las marcas de tiempo de confirmación para crear un registro de cambios con Go.