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

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

下列指令適用於 GoogleSQL 方言資料庫。

注意： 您只能搭配 Spanner JDBC 驅動程式使用工作階段管理陳述式。工作階段管理陳述式不適用於用戶端程式庫、Google Cloud CLI 或 Simba 建立的 JDBC 驅動程式。

連線陳述式

下列陳述式會變更或顯示目前連線的屬性。

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 (點選即可展開)

以下範例說明如何使用 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_STALENESS 和 EXACT_STALENESS 值時，支援的時間單位如下：

• s：秒
• ms：毫秒
• us：微秒
• ns：奈秒

只有在沒有進行中的交易時，才能修改這項屬性的值。

注意： 您只能在 AUTOCOMMIT 模式下，對查詢使用 MIN_READ_TIMESTAMP 和 MAX_STALENESS 值。

▶ 範例：唯讀陳舊 (按一下即可展開)

以下範例說明如何使用 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 (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 關鍵字為選用項目。

• 使用 COMMIT 或 ROLLBACK 終止交易。
• 如果已啟用AUTOCOMMIT 模式，這項陳述式會暫時將連線移出 AUTOCOMMIT 模式。交易結束時，連線會返回 AUTOCOMMIT 模式。
• 交易模式取決於這個連線目前的 READONLY 設定。這個值是使用 SET READONLY = {TRUE | FALSE} 指令設定的。
• 執行 BEGIN [TRANSACTION] 後，直接執行 SET TRANSACTION READ ONLY 或 SET 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 上的所有鎖定。
• 提交唯讀交易會結束目前的唯讀交易。後續任何陳述式都會啟動新的交易。對於唯讀交易，COMMIT 和 ROLLBACK 在語意上沒有差異。

只有在有效交易期間，您才能執行這項陳述式。

▶ 範例：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 會結束目前的唯讀交易。後續的任何陳述式都會啟動新的交易。在連線的唯讀交易中，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 { READ ONLY | READ WRITE }

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

只有在 AUTOCOMMIT 為 false 時，或您已執行 BEGIN [TRANSACTION] 啟動交易，但尚未在交易中執行任何陳述式時，才能執行這項陳述式。

這項陳述式只會為目前的交易設定交易模式。交易提交或回溯時，下一個交易會使用連線的預設模式 (請參閱 SET READONLY)。

注意： 如果連線處於 READ ONLY 模式，則無法將交易模式設為 READ WRITE。

▶ 範例：設定交易 (按一下即可展開)

以下範例說明如何使用 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

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

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

注意： 如果批次中的 DDL 陳述式傳回錯誤，Spanner 可能仍會將同一批次中先前的 DDL 陳述式套用至資料庫。

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;

啟動批次 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;

資料加速和分區查詢陳述式

partitionQuery API 會將查詢分成較小的片段 (稱為「分區」)，並使用多部機器平行擷取分區。每個分割區都會以分割區權杖識別。PartitionQuery API 的延遲時間比標準查詢 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 執行查詢 (按一下即可展開)

以下範例說明如何使用 Spanner JDBC 驅動程式，透過 Data Boost 查詢資料。

-- 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 驅動程式用來執行分割區的工作站執行緒數量。這項值用於：

• 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。

只有在沒有進行中的交易時，您才能變更這個變數的值。

▶ 範例：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 方言資料庫。