Comandos de gestión de sesiones de JDBC (GoogleSQL)

El controlador JDBC (Java Database Connectivity) de Spanner admite instrucciones de gestión de sesiones, que te permiten modificar el estado de tu conexión, ejecutar transacciones y ejecutar de forma eficiente lotes de instrucciones.

Los siguientes comandos se aplican a las bases de datos con dialecto GoogleSQL.

Instrucciones de conexión

Las siguientes instrucciones modifican o muestran las propiedades de la conexión actual.

READONLY

Valor booleano que indica si la conexión está en modo de solo lectura. El valor predeterminado es false.

SHOW VARIABLE READONLY
SET READONLY = { true | false }

Solo puede cambiar el valor de esta propiedad si no hay ninguna transacción activa.

SET READONLY = TRUE;
-- This transaction is a read-only transaction.
BEGIN TRANSACTION;

-- The following two queries both use the read-only transaction.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title
FROM Albums
ORDER BY Title;

-- This shows the read timestamp that was used for the two queries.
SHOW VARIABLE READ_TIMESTAMP;

-- This marks the end of the read-only transaction. The next statement starts
-- a new read-only transaction.
COMMIT;

AUTOCOMMIT

Valor booleano que indica si la conexión está en modo de confirmación automática. El valor predeterminado es true.

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

Solo puede cambiar el valor de esta propiedad cuando no haya ninguna transacción activa.

Si AUTOCOMMIT tiene el valor false, se inicia automáticamente una nueva transacción después de ejecutar COMMIT o ROLLBACK. La primera instrucción que ejecutes inicia la transacción.

-- The default value for AUTOCOMMIT is true.
SHOW VARIABLE AUTOCOMMIT;

-- This insert statement is automatically committed after it is executed, as
-- the connection is in autocommit mode.
INSERT INTO T (id, col_a, col_b) VALUES (1, 100, 1);

-- Turning off autocommit means that a new transaction is automatically started
-- when the next statement is executed.
SET AUTOCOMMIT = FALSE;
-- The following statement starts a new transaction.
INSERT INTO T (id, col_a, col_b) VALUES (2, 200, 2);

-- This statement uses the same transaction as the previous statement.
INSERT INTO T (id, col_a, col_b) VALUES (3, 300, 3);

-- Commit the current transaction with the two INSERT statements.
COMMIT;

-- Transactions can also be executed in autocommit mode by executing the BEGIN
-- statement.
SET AUTOCOMMIT = TRUE;

-- Execute a transaction while in autocommit mode.
BEGIN;
INSERT INTO T (id, col_a, col_b) VALUES (4, 400, 4);
INSERT INTO T (id, col_a, col_b) VALUES (5, 500, 5);
COMMIT;

RETRY_ABORTS_INTERNALLY

Valor booleano que indica si la conexión vuelve a intentar automáticamente las transacciones anuladas. El valor predeterminado es true.

SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }

Solo puede cambiar el valor de esta propiedad después de que se haya iniciado una transacción (consulte BEGIN TRANSACTION) y antes de que se ejecuten instrucciones en la transacción.

Si asignas el valor true a RETRY_ABORTS_INTERNALLY, la conexión conservará una suma de comprobación de todos los datos que devuelva a la aplicación cliente. Se usa para volver a intentar la transacción si Spanner la cancela.

El valor predeterminado es true. Te recomendamos que asignes el valor false si tu aplicación ya vuelve a intentar las transacciones canceladas.

AUTOCOMMIT_DML_MODE

Una propiedad STRING que indica el modo de confirmación automática de las declaraciones del lenguaje de manipulación de datos (DML).

SHOW VARIABLE AUTOCOMMIT_DML_MODE
SET AUTOCOMMIT_DML_MODE = { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }

A continuación se especifican los posibles valores.

• En el modo TRANSACTIONAL, el controlador ejecuta las instrucciones DML como transacciones atómicas independientes. El controlador crea una transacción, ejecuta la instrucción DML y confirma la transacción si se ejecuta correctamente o la revierte si se produce un error.
• En el modo PARTITIONED_NON_ATOMIC, el controlador ejecuta las instrucciones DML como instrucciones de actualización particionadas. Una instrucción de actualización particionada se puede ejecutar como una serie de muchas transacciones, cada una de las cuales abarca un subconjunto de las filas afectadas. La instrucción de partición proporciona una semántica debilitada a cambio de una mejor escalabilidad y rendimiento.

El valor predeterminado es TRANSACTIONAL.

-- Change autocommit DML mode to use Partitioned DML.
SET AUTOCOMMIT_DML_MODE = 'PARTITIONED_NON_ATOMIC';

-- Delete all singers that have been marked as inactive.
-- This statement is executed using Partitioned DML.
DELETE
FROM singers
WHERE active=false;

-- Change DML mode back to standard `TRANSACTIONAL`.
SET AUTOCOMMIT_DML_MODE = 'TRANSACTIONAL';

STATEMENT_TIMEOUT

Propiedad de tipo STRING que indica el valor de tiempo de espera actual de las instrucciones.

SHOW VARIABLE STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT = { '<INT64>{ s | ms | us | ns }' | NULL }

El valor INT64 es un número entero seguido de un sufijo que indica la unidad de tiempo. El valor NULL indica que no se ha definido ningún valor de tiempo de espera. Si se ha definido un valor de tiempo de espera de una instrucción, las instrucciones que tarden más que el valor de tiempo de espera especificado provocarán un error java.sql.SQLTimeoutException e invalidarán la transacción.

Las unidades de tiempo admitidas son:

• s: segundos
• ms: milisegundos
• us: microsegundos
• ns: nanosegundos

El valor predeterminado es NULL, lo que significa que no se ha definido ningún valor de tiempo de espera.

Si se agota el tiempo de espera de una instrucción durante una transacción, la transacción se invalida, todas las instrucciones posteriores de la transacción invalidada (excepto ROLLBACK) fallan y el controlador JDBC de Spanner genera un java.sql.SQLTimeoutException.

READ_ONLY_STALENESS

Propiedad de tipo STRING que indica el valor de obsolescencia de solo lectura actual que usa Spanner para las transacciones y las consultas de solo lectura en el modo AUTOCOMMIT.

SHOW VARIABLE READ_ONLY_STALENESS
SET READ_ONLY_STALENESS = staleness_type

staleness_type:

{ 'STRONG' 
  | 'MIN_READ_TIMESTAMP timestamp'
  | 'READ_TIMESTAMP timestamp'
  | 'MAX_STALENESS <INT64>{ s | ms | us | ns }'
  | 'EXACT_STALENESS <INT64>{ s | ms | us | ns }' }

El valor read-only staleness se aplica a todas las transacciones de solo lectura posteriores y a todas las consultas en modo AUTOCOMMIT.

El valor predeterminado es STRONG.

Las opciones de límite de marca de tiempo son las siguientes:

• STRONG indica a Spanner que realice una lectura sólida.
• MAX_STALENESS define el intervalo de tiempo que usa Spanner para realizar una lectura con obsolescencia limitada en relación con now().
• MIN_READ_TIMESTAMP define una hora absoluta que Spanner usa para realizar una lectura con obsolescencia limitada.
• EXACT_STALENESS define el intervalo de tiempo que usa Spanner para realizar una lectura de obsolescencia exacta en relación con now().
• READ_TIMESTAMP define una hora absoluta que Spanner usa para realizar una lectura de obsolescencia exacta.

Las marcas de tiempo deben tener el siguiente formato:

YYYY-[M]M-[D]DT[[H]H:[M]M:[S]S[.DDDDDD]][timezone]

Las unidades de tiempo admitidas para los valores MAX_STALENESS y EXACT_STALENESS son las siguientes:

• s: segundos
• ms: milisegundos
• us: microsegundos
• ns: nanosegundos

Solo puede modificar el valor de esta propiedad si no hay ninguna transacción activa.

-- Set the read-only staleness to MAX_STALENESS 10 seconds.
SET READ_ONLY_STALENESS = 'MAX_STALENESS 10s';

-- Execute a query in auto-commit mode. This returns results that are up to
-- 10 seconds stale.
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Read-only staleness can also be applied to read-only transactions.
-- MAX_STALENESS is only allowed for queries in autocommit mode.
-- Change the staleness to EXACT_STALENESS and start a read-only transaction.
SET READ_ONLY_STALENESS = 'EXACT_STALENESS 10s';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

SELECT Title, SingerId
FROM Albums
ORDER BY Title;

COMMIT;

-- Set the read staleness to an exact timestamp.
SET READ_ONLY_STALENESS = 'READ_TIMESTAMP 2024-01-26T10:36:00Z';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_VERSION

Una propiedad de tipo STRING que indica la versión del optimizador. La versión es un número entero o LATEST.

SHOW VARIABLE OPTIMIZER_VERSION
SET OPTIMIZER_VERSION = { 'version'|'LATEST'|'' }

Define la versión del optimizador que se va a usar en todas las instrucciones siguientes de la conexión. Si la versión del optimizador es '' (la cadena vacía), Spanner usará la versión más reciente. Si no se ha definido ninguna versión del optimizador, Spanner usará la versión del optimizador que se haya definido en el nivel de la base de datos.

El valor predeterminado es ''.

-- Set the optimizer version to 5 and execute a query.
SET OPTIMIZER_VERSION = '5';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the latest optimizer version.
SET OPTIMIZER_VERSION = 'LATEST';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Revert back to using the default optimizer version that has been set for the
-- database.
SET OPTIMIZER_VERSION = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

OPTIMIZER_STATISTICS_PACKAGE

Una propiedad de tipo STRING que indica el paquete de estadísticas del optimizador actual que usa esta conexión.

SHOW VARIABLE OPTIMIZER_STATISTICS_PACKAGE
SET OPTIMIZER_STATISTICS_PACKAGE = { 'package'|'' }

Define el paquete de estadísticas del optimizador que se va a usar en todas las instrucciones siguientes de la conexión. <package> debe ser un nombre de paquete válido. Si no se define ningún paquete de estadísticas del optimizador, Spanner usa el paquete de estadísticas del optimizador que se haya definido a nivel de base de datos.

El valor predeterminado es ''.

-- Show the available optimizer statistics packages in this database.
SELECT * FROM INFORMATION_SCHEMA.SPANNER_STATISTICS;

-- Set the optimizer statistics package and execute a query.
SET OPTIMIZER_STATISTICS_PACKAGE = 'auto_20240124_06_47_29UTC';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Execute the same query with the default optimizer statistics package.
SET OPTIMIZER_STATISTICS_PACKAGE = '';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

RETURN_COMMIT_STATS

Propiedad de tipo BOOL que indica si se deben devolver estadísticas de las transacciones de esta conexión. Para ver las estadísticas devueltas, ejecuta el comando SHOW VARIABLE COMMIT_RESPONSE.

SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }

El valor predeterminado es false.

-- Enable the returning of commit stats.
SET RETURN_COMMIT_STATS = true;

-- Execute a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);
COMMIT;

-- View the commit response with the transaction statistics for the last
-- transaction that was committed.
SHOW VARIABLE COMMIT_RESPONSE;

RPC_PRIORITY

Propiedad de tipo STRING que indica la prioridad relativa de las solicitudes de Spanner. La prioridad actúa como una sugerencia para el programador de Spanner y no garantiza el orden de ejecución.

SHOW VARIABLE RPC_PRIORITY
SET RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}

'NULL' significa que no se debe incluir ninguna pista en la solicitud.

El valor predeterminado es 'NULL'.

También puedes usar una sugerencia de instrucción para especificar la prioridad de la RPC:

@{RPC_PRIORITY=PRIORITY_LOW} SELECT * FROM Albums

Para obtener más información, consulta Priority.

Etiquetas

Las siguientes instrucciones gestionan las etiquetas de solicitud y de transacción.

STATEMENT_TAG

Propiedad de tipo STRING que contiene la etiqueta de solicitud de la siguiente instrucción.

SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'

Define la etiqueta de solicitud de la siguiente instrucción que se va a ejecutar. Solo se puede definir una etiqueta por instrucción. La etiqueta no abarca varias instrucciones, sino que debe definirse por instrucción. Una etiqueta de solicitud se puede quitar asignándole la cadena vacía ('').

El valor predeterminado es ''.

Puede definir etiquetas de transacción y de extracto para el mismo extracto.

También puedes usar una sugerencia de declaración para añadir una etiqueta de declaración:

@{STATEMENT_TAG='my-tag'} SELECT * FROM Albums

Para obtener más información, consulta Solucionar problemas con etiquetas de solicitud y de transacción.

-- Set the statement tag that should be included with the next statement.
SET STATEMENT_TAG = 'tag1';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- The statement tag property is cleared after each statement execution.
SHOW VARIABLE STATEMENT_TAG;
-- Set another tag for the next statement.
SET STATEMENT_TAG = 'tag2';
SELECT Title
FROM Albums
ORDER BY Title;

-- Set a statement tag with a query hint.
@{STATEMENT_TAG = 'tag3'}
SELECT TrackNumber, Title
FROM Tracks
WHERE AlbumId=1 AND SingerId=1
ORDER BY TrackNumber;

TRANSACTION_TAG

Propiedad de tipo STRING que contiene la etiqueta de transacción de la siguiente transacción.

SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'

Define la etiqueta de transacción de la transacción actual que se va a ejecutar. Solo se puede definir una etiqueta por transacción. La etiqueta no abarca varias transacciones, sino que debe definirse para cada transacción. Para quitar una etiqueta de transacción, debe asignarle una cadena vacía (''). La etiqueta de transacción debe definirse antes de que se ejecute ninguna instrucción en la transacción.

El valor predeterminado es ''.

Puede definir etiquetas de transacción y de extracto para el mismo extracto.

Para obtener más información, consulta Solucionar problemas con etiquetas de solicitud y de transacción.

BEGIN;
-- Set the transaction tag for the current transaction.
SET TRANSACTION_TAG = 'transaction-tag-1';

-- Set the statement tag that should be included with the next statement.
-- The statement will include both the statement tag and the transaction tag.
SET STATEMENT_TAG = 'select-statement';
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- The statement tag property is cleared after each statement execution.
SHOW VARIABLE STATEMENT_TAG;

-- Set another tag for the next statement.
SET STATEMENT_TAG = 'insert-statement';
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

-- The transaction tag property is cleared when the transaction finishes.
SHOW VARIABLE TRANSACTION_TAG;

Extractos de transacciones

Las siguientes instrucciones gestionan y confirman las transacciones de Spanner.

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

Devuelve un conjunto de resultados con una fila y una columna de tipo TIMESTAMP que contiene la marca de tiempo de lectura de la transacción de solo lectura más reciente. Esta instrucción devuelve una marca de tiempo solo cuando una transacción de solo lectura sigue activa y ha ejecutado al menos una consulta, o inmediatamente después de que se haya confirmado una transacción de solo lectura y antes de que empiece una nueva transacción. De lo contrario, el resultado es NULL.

-- Execute a query in autocommit mode using the default read-only staleness
-- (strong).
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp that was used for the previous query.
SHOW VARIABLE READ_TIMESTAMP;

-- Set a non-deterministic read-only staleness and execute the same query.
SET READ_ONLY_STALENESS = 'MAX_STALENESS 20s';

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp that was used for the previous query. The timestamp
-- is determined by Spanner, and is guaranteed to be no less than
-- 20 seconds stale.
SHOW VARIABLE READ_TIMESTAMP;

-- The read timestamp of a read-only transaction can also be retrieved.
SET READ_ONLY_STALENESS = 'STRONG';
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Show the read timestamp of the current read-only transaction. All queries in
-- this transaction will use this read timestamp.
SHOW VARIABLE READ_TIMESTAMP;

SELECT Title
FROM Albums
ORDER BY Title;

-- The read timestamp is the same as for the previous query, as all queries in
-- the same transaction use the same read timestamp.
SHOW VARIABLE READ_TIMESTAMP;

COMMIT;

COMMIT_TIMESTAMP

SHOW VARIABLE COMMIT_TIMESTAMP

Devuelve un conjunto de resultados con una fila y una columna de tipo TIMESTAMP que contiene la marca de tiempo de confirmación de la última transacción de lectura y escritura que ha confirmado Spanner. Esta instrucción devuelve una marca de tiempo solo cuando la ejecutas después de confirmar una transacción de lectura y escritura, y antes de ejecutar cualquier instrucción posterior SELECT, DML o de cambio de esquema. De lo contrario, el resultado es NULL.

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW VARIABLE COMMIT_TIMESTAMP;

COMMIT_RESPONSE

SHOW VARIABLE COMMIT_RESPONSE

Devuelve un conjunto de resultados con una fila y dos columnas:

• COMMIT_TIMESTAMP (type=TIMESTAMP) indica cuándo se confirmó la transacción más reciente.
• MUTATION_COUNT (type=INT64) indica cuántas mutaciones se han aplicado en la transacción confirmada. Este valor siempre está vacío cuando se ejecuta en el emulador.

El recuento de mutaciones solo está disponible si SET RETURN_COMMIT_STATS se ha definido como true antes de confirmar la transacción.

-- Enable returning commit stats in addition to the commit timestamp.
SET RETURN_COMMIT_STATS = true;

-- Execute a DML statement.
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1), (2, 200, 2), (3, 300, 3);

-- Show the timestamp that the statement was committed.
SHOW VARIABLE COMMIT_RESPONSE;

BEGIN [TRANSACTION]

BEGIN [TRANSACTION]

Inicia una nueva transacción. La palabra clave TRANSACTION es opcional.

• Usa COMMIT o ROLLBACK para finalizar una transacción.
• Si has habilitado el modo AUTOCOMMIT, esta instrucción desactiva temporalmente el modo AUTOCOMMIT. La conexión vuelve al modo AUTOCOMMIT cuando finaliza la transacción.
• El modo de transacción se determina en función del ajuste de READONLY actual de esta conexión. Este valor se define mediante el comando SET READONLY = {TRUE | FALSE}.
• El modo de transacción se puede cambiar ejecutando SET TRANSACTION READ ONLY o SET TRANSACTION READ WRITE directamente después de ejecutar BEGIN [TRANSACTION].

Solo puedes ejecutar esta instrucción si no hay ninguna transacción activa.

-- This starts a transaction using the current defaults of this connection.
-- The value of READONLY determines whether the transaction is a
-- read-write or a read-only transaction.

BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Set READONLY to TRUE to use read-only transactions by default.
SET READONLY=TRUE;

-- This starts a read-only transaction.
BEGIN;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

-- Execute 'SET TRANSACTION READ WRITE' or 'SET TRANSACTION READ ONLY' directly
-- after the BEGIN statement to override the current default of the connection.
SET READONLY=FALSE;
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

COMMIT [TRANSACTION]

COMMIT [TRANSACTION]

Confirma la transacción actual. La palabra clave TRANSACTION es opcional.

• Al confirmar una transacción de lectura y escritura, todas las actualizaciones de esta transacción se hacen visibles para otras transacciones y se liberan todos los bloqueos de la transacción en Spanner.
• Al confirmar una transacción de solo lectura, se finaliza la transacción de solo lectura actual. Cualquier instrucción posterior inicia una nueva transacción. No hay diferencia semántica entre COMMIT y ROLLBACK en una transacción de solo lectura.

Solo puedes ejecutar esta instrucción mientras haya una transacción activa.

-- Execute a regular read-write transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
COMMIT;

-- Execute a read-only transaction. Read-only transactions also need to be
-- either committed or rolled back in the Spanner JDBC driver in order
-- to mark the end of the transaction.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
COMMIT;

ROLLBACK [TRANSACTION]

ROLLBACK [TRANSACTION]

Realiza una ROLLBACK de la transacción actual. Las palabras clave TRANSACTION son opcionales.

• Al realizar una ROLLBACK de una transacción de lectura y escritura, se borran las mutaciones almacenadas en búfer, se revierte la transacción en Spanner y se liberan los bloqueos que tenía la transacción.
• Al realizar una ROLLBACK de una transacción de solo lectura, se finaliza la transacción de solo lectura actual. Las instrucciones posteriores inician una nueva transacción. No hay ninguna diferencia semántica entre COMMIT y ROLLBACK en una transacción de solo lectura en una conexión.

Solo puedes ejecutar esta instrucción mientras haya una transacción activa.

-- Use ROLLBACK to undo the effects of a transaction.
BEGIN;
INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);
-- This ensures that the insert statement is not persisted in the database.
ROLLBACK;

-- Read-only transactions also need to be either committed or rolled back in the
-- Spanner JDBC driver in order to mark the end of the transaction.
-- There is no semantic difference between rolling back or committing a
-- read-only transaction.
BEGIN;
SET TRANSACTION READ ONLY;
SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;
ROLLBACK;

SET TRANSACTION

SET TRANSACTION { READ ONLY | READ WRITE }

Define el modo de transacción de la transacción actual.

Solo puedes ejecutar esta instrucción cuando AUTOCOMMIT sea false o si has iniciado una transacción ejecutando BEGIN [TRANSACTION] y aún no has ejecutado ninguna instrucción en la transacción.

Esta instrucción solo define el modo de transacción de la transacción actual. Cuando la transacción se confirma o se revierte, la siguiente transacción usa el modo predeterminado de la conexión (consulta SET READONLY).

-- Start a transaction and set the transaction mode to read-only.
BEGIN;
SET TRANSACTION READ ONLY;

SELECT FirstName, LastName
FROM Singers
ORDER BY LastName;

-- Commit the read-only transaction to mark the end of the transaction.
COMMIT;

-- Start a transaction and set the transaction mode to read-write.
BEGIN;
SET TRANSACTION READ WRITE;

INSERT INTO T (id, col_a, col_b)
VALUES (1, 100, 1);

COMMIT;

Declaraciones por lotes

Las siguientes instrucciones gestionan lotes de instrucciones DDL y los envían a Spanner.

START BATCH DDL

START BATCH DDL

Inicia un lote de instrucciones DDL en la conexión. Todas las instrucciones posteriores durante el lote deben ser instrucciones DDL. Las instrucciones DDL se almacenan en búfer localmente y se envían a Spanner como un lote cuando ejecutas RUN BATCH. Ejecutar varias instrucciones DDL como un lote suele ser más rápido que ejecutar las instrucciones por separado.

Solo puedes ejecutar esta instrucción si no hay ninguna transacción activa.

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Singers (
  SingerId  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

-- This statement is buffered locally until RUN BATCH is executed.
CREATE TABLE Albums (
  AlbumId  INT64 NOT NULL,
  Title    STRING(MAX),
  SingerId INT64,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
) PRIMARY KEY (AlbumId);

-- This runs the DDL statements as one batch.
RUN BATCH;

EJECUTAR BATCH

RUN BATCH

Envía a la base de datos todas las instrucciones DDL almacenadas en el lote DDL actual, espera a que Spanner ejecute estas instrucciones y finaliza el lote DDL actual.

Si Spanner no puede ejecutar al menos una instrucción DDL, RUN BATCH devuelve un error para la primera instrucción DDL que Spanner no puede ejecutar. De lo contrario, RUN BATCH se devuelve correctamente.

ABORT BATCH [TRANSACTION]

Borra todas las instrucciones DDL almacenadas en el búfer del lote DDL actual y finaliza el lote.

Solo puede ejecutar esta instrucción cuando haya un lote de DDL activo. Puedes usar ABORT BATCH independientemente de si el lote tiene o no instrucciones DDL almacenadas en búfer. Se anularán todas las instrucciones DDL anteriores del lote.

-- Start a DDL batch. All following statements must be DDL statements.
START BATCH DDL;

-- The following statements are buffered locally.
CREATE TABLE Singers (
  SingerId  INT64 NOT NULL,
  FirstName STRING(MAX),
  LastName  STRING(MAX)
) PRIMARY KEY (SingerId);

CREATE TABLE Albums (
  AlbumId  INT64 NOT NULL,
  Title    STRING(MAX),
  SingerId INT64,
  CONSTRAINT fk_albums_singers FOREIGN KEY (SingerId) REFERENCES Singers (SingerId)
) PRIMARY KEY (AlbumId);

-- This aborts the DDL batch and removes the DDL statements from the buffer.
ABORT BATCH;

START BATCH DML y RUN Batch

Las siguientes instrucciones agrupan las dos instrucciones DML y las envían en una llamada al servidor. Un lote de DML se puede ejecutar como parte de una transacción o en modo de confirmación automática.

START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;

-- Start a DML batch. All following statements must be a DML statement.
START BATCH DML;

-- The following statements are buffered locally.
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');

-- This sends the statements to Spanner.
RUN BATCH;

-- DML batches can also be part of a read/write transaction.
BEGIN;
-- Insert a row using a single statement.
INSERT INTO MYTABLE (ID, NAME) VALUES (3, 'THREE');

-- Insert two rows using a batch.
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (4, 'FOUR');
INSERT INTO MYTABLE (ID, NAME) VALUES (5, 'FIVE');
RUN BATCH;

-- Rollback the current transaction. This rolls back both the single DML
-- statement and the DML batch.
ROLLBACK;

Acelerador de datos y sentencias de consulta con particiones

La API partitionQuery divide una consulta en partes más pequeñas, o particiones, y usa varias máquinas para obtener las particiones en paralelo. Cada partición se identifica mediante un token de partición. La API PartitionQuery tiene una latencia mayor que la API de consulta estándar, ya que solo está diseñada para operaciones en bloque, como exportar o analizar toda la base de datos.

Data Boost te permite ejecutar consultas analíticas y exportaciones de datos con un impacto casi nulo en las cargas de trabajo de la instancia de Spanner aprovisionada. Data Boost solo admite consultas particionadas.

Puedes habilitar Data Boost con la instrucción SET DATA_BOOST_ENABLED.

El controlador JDBC de Spanner admite tres alternativas para ejecutar consultas particionadas:

• SET AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql
• PARTITION sql seguido de varios RUN PARTITION 'partition-token'

Cada uno de estos métodos se describe en las secciones siguientes.

DATA_BOOST_ENABLED

Propiedad de tipo BOOL que indica si esta conexión debe usar Data Boost para las consultas particionadas. El valor predeterminado es false.

SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }

-- Enable Data Boost on this connection.
SET DATA_BOOST_ENABLED = true;

-- Execute a partitioned query. Data Boost is only used for partitioned queries.
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers;

Para ver un ejemplo completo, consulta DataBoostExample.

AUTO_PARTITION_MODE

Propiedad de tipo BOOL que indica si la conexión usa automáticamente consultas particionadas para todas las consultas que se ejecutan.

SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}

• Asigna el valor true a esta variable si quieres que la conexión use consultas particionadas para todas las consultas que se ejecuten.
• También puedes definir DATA_BOOST_ENABLED como true si quieres que la conexión use Data Boost para todas las consultas.

El valor predeterminado es false.

SET AUTO_PARTITION_MODE = true
SET DATA_BOOST_ENABLED = true
SELECT FirstName, LastName FROM Singers
SELECT SingerId, Title FROM Albums

Para ver un ejemplo completo, consulta AutoPartitionModeExample.

EJECUTAR CONSULTA PARTICIONADA

RUN PARTITIONED QUERY <sql>

Ejecuta una consulta como consulta con particiones en Spanner. Asegúrate de que DATA_BOOST_ENABLED esté configurado como true para ejecutar la consulta con Data Boost:

SET DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers

El controlador JDBC de Spanner particiona internamente la consulta y ejecuta las particiones en paralelo. Los resultados se combinan en un conjunto de resultados y se devuelven a la aplicación. El número de hilos de trabajador que ejecutan particiones se puede definir con la variable MAX_PARTITIONED_PARALLELISM.

Para ver un ejemplo completo, consulta RunPartitionedQueryExample.

PARTITION <SQL>

PARTITION <sql>

Crea una lista de particiones para ejecutar una consulta en Spanner y devuelve una lista de tokens de partición. Cada token de partición se puede ejecutar en una conexión independiente en el mismo cliente o en otro mediante el comando RUN PARTITION 'partition-token'.

-- Partition a query. This returns a list of partition tokens that can be
-- executed either on this connection or on any other connection to the same
-- database.
PARTITION SELECT FirstName, LastName FROM Singers;

-- Run the partitions that were returned from the previous statement.
RUN PARTITION 'partition-token-1';
RUN PARTITION 'partition-token-2';

Para ver un ejemplo completo, consulta PartitionQueryExample.

EJECUTAR PARTICIÓN 'partition-token'

RUN PARTITION 'partition-token'

Ejecuta una partición de consulta que ha devuelto previamente el comando PARTITION. El comando se puede ejecutar en cualquier conexión que esté conectada a la misma base de datos que la base de datos que creó los tokens de partición.

MAX_PARTITIONED_PARALLELISM

Propiedad de tipo INT64 que indica el número de hilos de trabajo que utiliza el controlador JDBC de Spanner para ejecutar particiones. Este valor se usa para lo siguiente:

• AUTO_PARTITION_MODE = true
• RUN PARTITIONED QUERY sql

SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>

Define el número máximo de subprocesos de trabajador que el controlador JDBC de Spanner puede usar para ejecutar particiones. Si se le asigna el valor 0, se indica al controlador JDBC de Spanner que use el número de núcleos de CPU de la máquina cliente como máximo.

El valor predeterminado es 0.

Declaraciones de lectura dirigidas

Propiedad de tipo STRING que define la opción de lectura dirigida para las siguientes instrucciones.

SHOW VARIABLE DIRECTED_READ
SET DIRECTED_READ='{"includeReplicas":{"replicaSelections":[{"location":"<location-name>"}]}}'

Para obtener más información, consulta Lecturas dirigidas.

Comandos de estado guardado

Las siguientes instrucciones habilitan e inhabilitan los puntos de guardado emulados en las transacciones. Para crear un punto de guardado, llama al método java.sql.Connection#setSavepoint().

El controlador JDBC de Spanner emula puntos de guardado para admitir frameworks que dependen de ellos para las transacciones anidadas. Los puntos de guardado se emulan haciendo un seguimiento de una suma de comprobación en curso de los resultados que han devuelto las instrucciones de la transacción. Cuando se revierte a un punto de guardado, el controlador JDBC de Spanner revierte la transacción y, a continuación, vuelve a intentar la transacción hasta el punto en el que se estableció el punto de guardado. La suma de comprobación del reintento se compara con la suma de comprobación de la transacción inicial para verificar que se han devuelto los mismos resultados.

SAVEPOINT_SUPPORT

SHOW VARIABLE SAVEPOINT_SUPPORT
SET SAVEPOINT_SUPPORT = { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }

Una propiedad de tipo STRING que indica la SAVEPOINT_SUPPORT configuración actual. Los valores posibles son:

• DISABLED: todos los comandos de punto de guardado están inhabilitados y no funcionarán.
• FAIL_AFTER_ROLLBACK: los comandos de punto de guardado están habilitados. Al restaurar un punto de guardado, se revierte toda la transacción. La transacción falla si intentas usarla después de volver a un punto de guardado.
• ENABLED: todos los comandos de punto de guardado están habilitados. Si vuelves a un punto de guardado, se deshace la transacción y se vuelve a intentar hasta el punto de guardado. Esta operación falla y devuelve un error AbortedDueToConcurrentModificationException si los datos subyacentes que ha usado la transacción hasta el punto de guardado han cambiado.

El valor predeterminado es FAIL_AFTER_ROLLBACK.

Solo puedes cambiar el valor de esta variable si no hay ninguna transacción activa.

try (Connection connection =
    DriverManager.getConnection(
        String.format(
            "jdbc:cloudspanner:/projects/%s/instances/%s/databases/%s",
            "my-project", "my-instance", "my-database"))) {
  // Savepoints can only be used when AutoCommit=false.
  connection.setAutoCommit(false);

  // Disables setting a savepoint.
  connection.createStatement().execute("SET SAVEPOINT_SUPPORT='DISABLED'");
  // The following statement fails because savepoints have been disabled.
  connection.setSavepoint("my_savepoint1");

  // Enables setting a savepoint and releasing a savepoint.
  // Rolling back to a savepoint is disabled.
  connection.createStatement().execute("SET SAVEPOINT_SUPPORT='FAIL_AFTER_ROLLBACK'");
  Savepoint mySavepoint2 = connection.setSavepoint("my_savepoint2");
  connection.createStatement().execute("insert into my_table (id, value) values (1, 'One')");
  connection.releaseSavepoint(mySavepoint2);
  connection.commit();

  // Enables setting, releasing and rolling back to a savepoint.
  connection.createStatement().execute("SET SAVEPOINT_SUPPORT='ENABLED'");
  Savepoint mySavepoint3 = connection.setSavepoint("my_savepoint3");
  connection.createStatement().execute("insert into my_table (id, value) values (2, 'Two')");
  connection.rollback(mySavepoint3);
}

Siguientes pasos

Consulta cómo conectar JDBC a una base de datos con dialecto GoogleSQL.