JDBC 工作階段管理指令 (GoogleSQL)

Spanner JDBC 驅動程式 (Java Database Connectivity) 支援工作階段管理陳述式,可讓您修改連線狀態、執行交易,並有效率地執行批次陳述式。

下列指令適用於 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 後,系統會在您執行 COMMITROLLBACK 後自動啟動新的交易。您執行的第一個陳述式會啟動交易。

▶ 範例:自動提交 (按一下即可展開)
以下範例說明如何使用 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 (點選即可展開)
以下範例說明如何使用 Spanner JDBC 驅動程式執行區隔 DML

-- 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_STALENESSEXACT_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 上次認可的讀寫交易的修訂時間戳記。只有在您提交讀寫交易後,並在執行任何後續 SELECTDML 或結構定義變更陳述式之前,才能執行這項陳述式並傳回時間戳記。否則,結果為 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 (type=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 為選用項目。

  • 使用 COMMITROLLBACK 終止交易。
  • 如果您已啟用 AUTOCOMMIT 模式,這項陳述式會暫時將連線從 AUTOCOMMIT 模式移除。交易結束後,連線會返回 AUTOCOMMIT 模式。
  • 交易模式取決於此連線目前的 READONLY 設定。您可以使用 SET READONLY = {TRUE | FALSE} 指令設定這個值。
  • 您可以直接在執行 BEGIN [TRANSACTION] 後執行 SET TRANSACTION READ ONLYSET TRANSACTION READ WRITE,藉此變更交易模式。

您只能在沒有有效交易時執行這項陳述式。

▶ 範例: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 上的所有交易鎖定。
  • 提交唯讀交易會結束目前的唯讀交易。後續的任何陳述式都會啟動新的交易。對於唯讀交易,COMMITROLLBACK 之間沒有語意差異。

您只能在有有效交易時執行這項陳述式。

▶ 範例:COMMIT TRANSACTION (按一下可展開)
以下範例說明如何使用 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 會結束目前的唯讀交易。後續的任何陳述式都會啟動新的交易。在連線上,COMMITROLLBACK 的唯讀交易沒有語意差異。

您只能在有有效交易時執行這項陳述式。

▶ 範例: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 }

為目前交易設定交易模式。

您只能在 AUTOCOMMITfalse 時,或您已透過執行 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 陳述式。執行 RUN BATCH 時,系統會在本機緩衝 DDL 陳述式,並以一批次的形式傳送至 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

將目前 DDL 批次中的所有緩衝 DDL 陳述式傳送至資料庫,等待 Spanner 執行這些陳述式,並結束目前的 DDL 批次。

如果 Spanner 無法執行至少一個 DDL 陳述式,RUN BATCH 會針對 Spanner 無法執行的第一個 DDL 陳述式傳回錯誤。否則,RUN BATCH 會成功傳回。

ABORT BATCH [TRANSACTION]

清除目前 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;

START BATCH DML 和 RUN Batch

以下陳述式會將兩個 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 的延遲時間比標準查詢 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 執行查詢 (按一下即可展開)
以下範例說明如何搭配使用 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

▶ 範例:執行 (按一下即可展開)
這個範例會使用 Data Boost 執行兩個 Spanner JDBC 驅動程式查詢

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

PARTITION <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 驅動程式用來執行區隔作業的 worker 執行緒數量。這個值用於:

  • 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 驅動程式會模擬儲存點,以支援在巢狀交易中依賴這些點的架構。模擬儲存點的方式,是追蹤交易中陳述式傳回結果的執行總和。當回復至儲存點時,Spanner JDBC 驅動程式會回復交易,然後重試交易,直到設定儲存點為止。系統會比較重試的總和檢查碼與初始交易的總和檢查碼,以驗證是否傳回相同的結果。

SAVEPOINT_SUPPORT

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

STRING 類型的屬性,表示目前的 SAVEPOINT_SUPPORT 設定。可能的值包括:

  • DISABLED:所有儲存點指令都會停用,並且會失敗。
  • FAIL_AFTER_ROLLBACK:啟用儲存點指令。復原至儲存點會復原整個交易。如果您在回滾至儲存點後嘗試使用交易,交易會失敗。
  • ENABLED:所有儲存點指令都已啟用。回溯至儲存點會復原交易,並對儲存點執行重試。如果交易使用基礎資料的儲存點已變更,此作業就會失敗,並顯示 AbortedDueToConcurrentModificationException 錯誤。

預設值為 FAIL_AFTER_ROLLBACK

只有在沒有有效交易時,您才能變更這個變數的值。

▶ 範例:儲存點支援 (按一下可展開)
以下範例說明如何在 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 方言資料庫