Spanner JDBC 驱动程序(Java 数据库连接)支持会话管理语句,让您可以修改连接状态、执行事务并高效执行批量语句。
以下命令适用于 GoogleSQL 方言数据库。
连接语句
以下语句会更改或显示当前连接的属性。
READONLY
一个布尔值,指示连接是否处于只读模式。默认值为 false
。
SHOW VARIABLE READONLY
SET READONLY = { true | false }
只有在没有活跃事务的情况下,您才能更改此属性的值。
▶ 示例:只读事务(点击展开)
以下示例展示了如何使用此属性以只读模式执行
Spanner 中的事务。
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
指示连接是否处于自动提交模式的布尔值。默认值为 true
。
SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }
只有在没有活跃事务的情况下,您才能更改此属性的值。
将 AUTOCOMMIT
设置为 false 后,系统会在您执行 COMMIT
或 ROLLBACK
后自动发起新事务。您执行的第一个语句会启动事务。
▶ 示例:自动提交(点击展开)
以下示例展示了如何使用 autocommit
属性。
-- 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
一个布尔值,表示连接是否自动重试已中止的事务。默认值为 true
。
SHOW VARIABLE RETRY_ABORTS_INTERNALLY
SET RETRY_ABORTS_INTERNALLY = { true | false }
只有在交易开始后,您才能更改此属性的值
(请参阅 BEGIN TRANSACTION
)和之前
事务内执行任何语句。
将 RETRY_ABORTS_INTERNALLY
设置为 true 后,连接会保留连接返回到客户端应用的所有数据的校验和。这个
用于在事务被 Spanner 取消时重试。
默认值为 true
。如果您的问题仍未解决,我们建议您将此值设置为 false
应用已重试被中止的事务。
AUTOCOMMIT_DML_MODE
一个 STRING
属性,用于指示数据操纵语言 (DML) 语句的自动提交模式。
SHOW VARIABLE AUTOCOMMIT_DML_MODE
SET AUTOCOMMIT_DML_MODE = { 'TRANSACTIONAL' | 'PARTITIONED_NON_ATOMIC' }
可能的值包括:
- 在
TRANSACTIONAL
模式下,驱动程序将 DML 语句作为单独的原子化事务执行。驱动程序会创建新事务、执行 DML 语句,并在成功执行后提交事务,或在发生错误时回滚事务。 - 在
PARTITIONED_NON_ATOMIC
模式下,驱动程序将 DML 语句作为分区更新语句执行。分区更新语句可以作为一系列多个事务运行,每个事务均覆盖一部分受影响的行。分区语句提供 削弱语义,以换取更好的可伸缩性和性能。
默认值为 TRANSACTIONAL
。
▶ 示例:分区 DML(点击展开)
以下示例展示了如何执行
分区 DML(使用
Spanner JDBC 驱动程序。
-- 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
STRING
类型的属性,用于指示语句的当前超时值。
SHOW VARIABLE STATEMENT_TIMEOUT
SET STATEMENT_TIMEOUT = { '<INT64>{ s | ms | us | ns }' | NULL }
INT64
值为一个整数,后跟表示时间单位的后缀。值 NULL
表示未设置超时值。如果
语句超时值已设置,处理时间超过
指定的超时值将导致 java.sql.SQLTimeoutException
错误,并且
使交易失效。
受支持的时间单位包括:
s
:秒ms
:毫秒us
:微秒ns
:纳秒
默认值为 NULL
,表示未设置超时值。
事务期间的语句超时会使事务失效,
失效事务中的后续语句(ROLLBACK
除外)失败,
Spanner JDBC 驱动程序抛出 java.sql.SQLTimeoutException
。
READ_ONLY_STALENESS
STRING
类型的属性,指示当前的
只读过时设置
Spanner 在 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 }' }
只读过时值适用于所有后续只读事务,以及 AUTOCOMMIT
模式下的所有查询。
默认值为 STRONG
。
时间戳边界选项如下所示:
STRONG
指示 Spanner 执行强读取。MAX_STALENESS
定义 Spanner 相对于now()
执行有界限过时读取的时间间隔。MIN_READ_TIMESTAMP
定义 Spanner 执行任务所用的绝对时间 有界限过时读取。EXACT_STALENESS
定义 Spanner 执行 精确过时读取、 相对于now()
。READ_TIMESTAMP
定义 Spanner 执行 精确过时读取。
时间戳必须采用以下格式:
YYYY-[M]M-[D]DT[[H]H:[M]M:[S]S[.DDDDDD]][timezone]
设置 MAX_STALENESS
和 EXACT_STALENESS
值所支持的时间单位包括:
s
:秒ms
:毫秒us
:微秒ns
:纳秒
只有在没有活跃事务的情况下,您才能修改此属性的值。
▶ 示例:只读过时(点击即可展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序使用自定义过时值执行查询。
-- 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
STRING
类型的属性,用于指示
优化器版本。版本为整数或“LATEST
”。
SHOW VARIABLE OPTIMIZER_VERSION
SET OPTIMIZER_VERSION = { 'version'|'LATEST'|'' }
设置要用于连接上的所有后续语句的优化器版本。如果优化器版本设置为 ''
(空字符串),则
Spanner 使用最新版本。如果未设置优化器版本
Spanner 使用在数据库中设置的优化器版本
。
默认值为 ''
。
▶ 示例:优化工具版本(点击即可展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序搭配特定优化器版本执行查询。
-- 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
STRING
类型的属性,指示当前的
优化工具统计信息软件包
由该连接所使用的网络。
SHOW VARIABLE OPTIMIZER_STATISTICS_PACKAGE
SET OPTIMIZER_STATISTICS_PACKAGE = { 'package'|'' }
设置要用于连接上的所有后续语句的优化器统计信息软件包。<package>
必须是有效的软件包名称。如果未设置任何优化器统计信息软件包,Spanner 将使用在数据库级别设置的优化器统计信息软件包。
默认值为 ''
。
▶ 示例:优化器统计信息软件包(点击可展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序搭配使用特定优化器统计信息软件包来执行查询。
-- 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
类型为 BOOL
的属性,用于指示是否应针对此连接上的事务返回统计信息。您可以通过执行 SHOW VARIABLE COMMIT_RESPONSE
命令来查看返回的统计信息。
SHOW VARIABLE RETURN_COMMIT_STATS
SET RETURN_COMMIT_STATS = { true | false }
默认值为 false
。
▶ 示例:提交统计信息(点击展开)
以下示例展示了如何查看事务的提交统计信息
Spanner JDBC 驱动程序。
-- 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
类型为 STRING
的属性,表示 Spanner 请求的相对优先级。优先级可作为对 Spanner 调度程序的提示,但无法保证执行顺序。
SHOW VARIABLE RPC_PRIORITY
SET RPC_PRIORITY = {'HIGH'|'MEDIUM'|'LOW'|'NULL'}
'NULL'
表示请求中不应包含任何提示。
默认值为 'NULL'
。
您还可以使用语句提示来指定 RPC 优先级:
@{RPC_PRIORITY=PRIORITY_LOW} SELECT * FROM Albums
如需了解详情,请参阅 Priority
。
标记
以下语句用于管理请求代码和交易代码。
STATEMENT_TAG
一个类型为 STRING
的属性,其中包含下一个
声明。
SHOW VARIABLE STATEMENT_TAG
SET STATEMENT_TAG = 'tag-name'
设置要执行的下一个语句的请求标记。每个语句只能设置一个标记。该标记不会跨多个语句;必须针对每个语句进行设置。将请求标记设置为
空字符串 (''
)。
默认值为 ''
。
您可以为同一对账单同时设置交易代码和对账单代码。
您还可以使用语句提示来添加语句标记:
@{STATEMENT_TAG='my-tag'} SELECT * FROM Albums
如需了解详情,请参阅 使用请求代码和交易代码排查问题。
▶ 示例:语句代码(点击展开)
以下示例展示了如何使用
Spanner JDBC 驱动程序。
-- 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
一个类型为 STRING
的属性,其中包含下一笔交易的代码
交易。
SHOW VARIABLE TRANSACTION_TAG
SET TRANSACTION_TAG = 'tag-name'
为要执行的当前事务设置事务标记。仅一个
可以按交易设置代码该代码不会跨多个事务;必须按事务设置。可通过执行以下操作移除交易代码:
并将其设置为空字符串 (''
)。交易代码必须在
所有语句都已在事务中执行。
默认值为 ''
。
您可以为同一对账单同时设置交易标记和对账单标记。
如需了解详情,请参阅请求标记和事务标记问题排查。
▶ 示例:事务标记(点击展开)
下例显示了如何使用
Spanner JDBC 驱动程序。
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;
事务语句
以下语句用于管理和提交 Spanner 事务。
READ_TIMESTAMP
SHOW VARIABLE READ_TIMESTAMP
返回一个结果集,其中包含 TIMESTAMP
类型的一行和一列,该结果集包括最近一次只读事务的读取时间戳。只有在只读事务仍处于活跃状态并且已执行至少一个查询时,或者只有在紧接着已提交只读事务之后且新事务启动之前,此语句才会返回时间戳。否则,结果为 NULL
。
▶ 示例:读取时间戳(点击展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序查看只读操作的最后读取时间戳。
-- 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
返回一个结果集,其中包含 TIMESTAMP
类型的一行和一列,该结果集包括 Spanner 提交的最近一次读写事务的提交时间戳。仅当出现以下情况时,此语句才会返回时间戳:
在提交读写事务之后和执行
任何后续的 SELECT
、DML
或架构更改语句。否则,
结果为 NULL
。
▶ 示例:提交时间戳(点击即可展开)
以下示例展示了如何查看
Spanner JDBC 驱动程序执行写入操作。
-- 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
返回一个结果集,其中包含一行和两列:
COMMIT_TIMESTAMP
(type=TIMESTAMP
)表示最近一次提交事务的时间。MUTATION_COUNT
(类型为INT64
)表示已在提交的事务中应用了多少次变更。在 模拟器。
仅当在事务提交之前将 SET RETURN_COMMIT_STATS
设置为 true
时,才会提供更改计数。
▶ 示例:提交响应(点击展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序查看写入操作的最后提交响应。
-- 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]
启动新事务。关键字 TRANSACTION
是可选的。
- 使用
COMMIT
或ROLLBACK
终止事务。 - 如果您启用了
AUTOCOMMIT
模式,则此语句会暂时将连接退出AUTOCOMMIT
模式。当事务结束时,连接将返回AUTOCOMMIT
模式。 - 事务模式由此连接的当前
READONLY
设置决定。此值是使用SET READONLY = {TRUE | FALSE}
命令设置的。 - 可通过执行
SET TRANSACTION READ ONLY
来更改事务模式。 或是在执行之后直接SET TRANSACTION READ WRITE
BEGIN [TRANSACTION]
。
只有在没有活跃事务的情况下您才能执行此语句。
▶ 示例:BEGIN TRANSACTION(点击展开)
以下示例展示了如何使用以下代码启动不同类型的事务:
Spanner JDBC 驱动程序。
-- 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]
提交当前事务。关键字 TRANSACTION
是可选的。
- 提交读写事务将对此事务进行所有更新 对其他事务可见,并解除事务在 Spanner。
- 提交只读事务会结束当前的只读事务。任何后续语句都会启动新事务。对于只读事务,
COMMIT
和ROLLBACK
之间没有语义差异。
只有在存在活跃事务的情况下才能执行此语句。
▶ 示例:提交交易(点击即可展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序提交事务。
-- 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]
对当前事务执行 ROLLBACK
。关键字“TRANSACTION
”是
可选属性。
- 对读写事务执行
ROLLBACK
会清除所有缓存的变更,在 Spanner 上回滚该事务并解除该事务持有的所有锁定。 - 对只读事务执行
ROLLBACK
会结束当前的只读事务。任何后续语句都会启动新事务。对于连接上的只读事务,COMMIT
和ROLLBACK
之间没有语义差异。
只有在存在活跃事务的情况下才能执行此语句。
▶ 示例:ROLLBACK TRANSACTION(点击展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序回滚事务。
-- 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 }
设置当前事务的事务模式。
只有在 AUTOCOMMIT
为 false
时,或者已通过执行 BEGIN [TRANSACTION]
启动事务并且尚未在该事务中执行任何语句的情况下,才能执行此语句。
此语句仅为当前事务设置事务模式。事务提交或回滚后,下一个事务将使用连接的默认模式(请参阅 SET READONLY
)。
▶ 示例:SET TRANSACTION(点击展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序设置事务特性。
-- 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;
批量语句
以下语句用于管理批量 DDL 语句并发送这些批量 Spanner。
START BATCH DDL
START BATCH DDL
在连接上启动一批 DDL 语句。批处理期间的所有后续语句都必须是 DDL 语句。DDL 语句在本地缓存,并在执行 RUN BATCH
时作为一个批次发送到 Spanner。将多个 DDL 语句作为一个批次执行通常比单独运行语句速度快。
只有在没有活跃事务的情况下您才能执行此语句。
▶ 示例:DDL 批次(点击即可展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序执行 DDL 批处理。
-- 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;
RUN BATCH
RUN BATCH
将当前 DDL 批次中所有缓存的 DDL 语句发送到数据库,等待 Spanner 执行这些语句,然后结束当前 DDL 批次。
如果 Spanner 无法执行至少一个 DDL 语句,请RUN BATCH
针对 Spanner 无法实现的第一个 DDL 语句返回错误
。否则,RUN BATCH
会成功返回。
下一批 [交易]
清除当前 DDL 批次中所有缓存的 DDL 语句,然后结束该批次。
只有在 DDL 批次处于活跃状态的情况下您才能执行此语句。无论该批次是否包含缓存的 DDL 语句,您都可以使用 ABORT BATCH
。该批次中所有前面的 DDL 语句都将被取消。
▶ 示例:终止 DDL 批处理(点击展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序终止 DDL 批处理。
-- 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;
启动 BATCH DML 并运行批次
以下语句同时批处理两个 DML 语句,并通过一次调用将其发送到服务器。DML 批处理可以作为事务的一部分执行,也可以在自动提交模式下执行。
START BATCH DML;
INSERT INTO MYTABLE (ID, NAME) VALUES (1, 'ONE');
INSERT INTO MYTABLE (ID, NAME) VALUES (2, 'TWO');
RUN BATCH;
▶ 示例:DML 批处理(点击展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序执行 DML 批处理。
-- 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;
Data Boost 和分区查询语句
partitionQuery
API 会将查询划分为较小部分(即分区),并使用多台机器并行提取分区。每个分区都由
分区标记。PartitionQuery API 的延迟时间比标准
Query API,因为它仅适用于批量操作,例如导出或
扫描整个数据库。
借助 Data Boost,您可以执行分析查询和数据导出,且对预配的 Spanner 实例上的现有工作负载几乎没有影响。Data Boost 仅支持分区查询。
您可以使用 SET DATA_BOOST_ENABLED
语句启用 Data Boost。
Spanner JDBC 驱动程序支持三种执行分区查询的替代方案:
SET AUTO_PARTITION_MODE = true
RUN PARTITIONED QUERY sql
PARTITION sql
后跟多个RUN PARTITION 'partition-token'
以下各部分分别介绍了这些方法。
DATA_BOOST_ENABLED
BOOL
类型的属性,用于指示此连接是否应使用
针对分区查询的 Data Boost。默认
为 false
。
SHOW VARIABLE DATA_BOOST_ENABLED
SET DATA_BOOST_ENABLED = { true | false }
▶ 示例:使用 Data Boost 执行查询(点击可展开)
以下示例展示了如何使用 Spanner JDBC 驱动程序搭配使用数据提升功能进行查询。
-- 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;
如需查看完整示例,请参阅 DataBoostExample。
AUTO_PARTITION_MODE
BOOL
类型的属性,用于指示连接是否自动使用
所有已执行查询的分区查询。
SHOW VARIABLE AUTO_PARTITION_MODE
SET AUTO_PARTITION_MODE = { true | false}
- 如果您希望连接对执行的所有查询都使用分区查询,请将此变量设置为
true
。 - 如果您希望连接对所有查询使用 Data Boost,请将
DATA_BOOST_ENABLED
设为true
。
默认值为 false
。
▶ 示例:执行(点击展开)
此示例使用
数据提升
SET AUTO_PARTITION_MODE = true
SET DATA_BOOST_ENABLED = true
SELECT FirstName, LastName FROM Singers
SELECT SingerId, Title FROM Albums
如需查看完整示例,请参阅 AutoPartitionModeExample。
运行分区查询
RUN PARTITIONED QUERY <sql>
在 Spanner 上将查询作为分区查询执行。确保将 DATA_BOOST_ENABLED
设置为 true
,以便使用 Data Boost 执行查询:
SET DATA_BOOST_ENABLED = true
RUN PARTITIONED QUERY SELECT FirstName, LastName FROM Singers
Spanner JDBC 驱动程序会在内部对查询进行分区,并并行执行分区。这些结果会合并到一个结果集中,然后返回给应用。可以设置执行分区的工作器线程数
并使用变量 MAX_PARTITIONED_PARALLELISM
。
有关完整示例,请参阅 RunPartitionedQueryExample。
分区 <SQL>
PARTITION <sql>
创建分区列表以对 Spanner 执行查询
并返回分区令牌列表。您可以使用 RUN PARTITION 'partition-token'
命令在同一客户端或其他客户端的单独连接上执行每个分区令牌。
▶ 示例:分区查询(点击展开)
以下示例展示了如何对查询进行分区,然后使用 Spanner JDBC 驱动程序分别执行每个分区。
-- 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';
如需查看完整示例,请参阅 PartitionQueryExample。
RUN PARTITION 'partition-token'
RUN PARTITION 'partition-token'
执行之前由 PARTITION
返回的查询分区
命令。可以在连接到
与创建分区令牌的数据库相同的数据库。
MAX_PARTITIONED_PARALLELISM
INT64
类型的属性,指示
用于执行分区的 Spanner JDBC 驱动程序。此值用于:
AUTO_PARTITION_MODE = true
RUN PARTITIONED QUERY sql
SHOW VARIABLE MAX_PARTITIONED_PARALLELISM
SET MAX_PARTITIONED_PARALLELISM = <INT64>
设置 Spanner JDBC 驱动程序的工作器线程数上限
可用于执行分区。将此值设置为 0
会指示
Spanner JDBC 驱动程序,使用客户端上的 CPU 核心数
最大机器数量
默认值为 0
。
定向读取语句
STRING
类型的属性,用于为以下内容设置定向读取选项
语句。
SHOW VARIABLE DIRECTED_READ
SET DIRECTED_READ='{"includeReplicas":{"replicaSelections":[{"location":"<location-name>"}]}}'
如需了解详情,请参阅有针对性地读取。
存档点命令
以下语句用于在事务中启用和停用模拟的保存点。您可以通过调用 java.sql.Connection#setSavepoint()
方法创建保存点。
Spanner JDBC 驱动程序可以模拟保存点,以支持 则依赖于这些 API 进行嵌套事务。Savepoint 通过跟踪 中语句所返回结果的运行校验和 交易。回滚到保存点时,Spanner JDBC 驱动程序会回滚事务,然后重试事务,直到重试到设置保存点的位置。该 与初始事务的校验和进行比较,以验证 都返回了相同的结果。
SAVEPOINT_SUPPORT
SHOW VARIABLE SAVEPOINT_SUPPORT
SET SAVEPOINT_SUPPORT = { 'DISABLED' | 'FAIL_AFTER_ROLLBACK' | 'ENABLED' }
类型为 STRING
的属性,用于指示当前的 SAVEPOINT_SUPPORT
配置。可能的值包括:
DISABLED
:所有保存点命令均已停用,并会失败。FAIL_AFTER_ROLLBACK
:已启用 Savepoint 命令。回滚到保存点会回滚整个事务。如果您在回滚到保存点后尝试使用事务,则事务会失败。ENABLED
:所有 Savepoint 命令均已启用。回滚到保存点会回滚事务,并针对保存点执行重试。这个 如果出现以下情况,操作会失败并显示AbortedDueToConcurrentModificationException
错误 截至 Savepoint 为止,事务已使用的底层数据 已更改。
默认值为 FAIL_AFTER_ROLLBACK
。
只有在没有活跃事务的情况下,您才能更改此变量的值。
▶ 示例:支持 Savepoint(点击即可展开)
以下示例展示了如何在 Spanner JDBC 驱动程序中启用和停用保存点支持。
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);
}
后续步骤
了解如何将 JDBC 连接到 GoogleSQL 方言数据库。