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

接続が autocommit モードかどうかを示すブール値。デフォルト値は true です。

SHOW VARIABLE AUTOCOMMIT
SET AUTOCOMMIT = { true | false }

このプロパティの値を変更できるのは、アクティブなトランザクションが存在しない場合のみです。

AUTOCOMMIT が false に設定されている場合、COMMIT または ROLLBACK を実行すると、新しいトランザクションが自動的に開始されます。実行する最初のステートメントによって、トランザクションが開始されます。

▶ 例: 自動 commit（クリックして展開）
 次の例は、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

データ操作言語（DML）ステートメントの自動 commit モードを示す STRING プロパティ。

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

使用できる値は次のとおりです。

  • TRANSACTIONAL モードでは、ドライバが DML ステートメントを独立したアトミック トランザクションとして実行します。ドライバが新しいトランザクションを作成し、DML ステートメントが実行し、実行時にトランザクションを commit するか、エラーが発生した場合にトランザクションをロールバックします。
  • PARTITIONED_NON_ATOMIC モードでは、ドライバが DML ステートメントをパーティション化更新ステートメントとして実行します。パーティション化更新ステートメントは一連のトランザクションの 1 つとして実行でき、各トランザクションは影響を受ける行のサブセットをカバーします。パーティション化ステートメントは、スケーラビリティとパフォーマンスを向上させる代わりに、セマンティクスが緩和されます。

デフォルトは 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 を除く）が失敗し、JDBC ドライバで java.sql.SQLTimeoutException がスローされます。

READ_ONLY_STALENESS

AUTOCOMMIT モードで読み取り専用トランザクションとクエリに使用される現在の読み取り専用のステイルネス設定を示す STRING 型のプロパティ。

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 です。

タイムスタンプ バウンド オプションは次のとおりです。

タイムスタンプには、次の形式を使用する必要があります。

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 です。

▶ 例: commit 統計情報（クリックして展開）
 次の例は、Spanner JDBC ドライバを使用してトランザクションの commit 統計情報を表示する方法を示しています。

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

Spanner リクエストの相対的な優先度を示す STRING 型のプロパティ。優先度は 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'

実行する次のステートメントにリクエスト タグを設定します。1 つのステートメントに設定できるタグは 1 つのみです。タグが複数のステートメントを適用対象とすることはありません。タグはステートメント単位で設定する必要があります。リクエスト タグを削除するには、空の文字列（''）を設定します。

デフォルトは '' です。

同じステートメントに対してトランザクション タグとステートメント タグの両方を設定できます。

ステートメント ヒントを使用してステートメント タグを追加することもできます。

@{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'

実行される直近のトランザクション用のトランザクション タグを設定します。1 つのトランザクションに設定できるタグは 1 つのみです。タグが複数のトランザクションを適用対象とすることはありません。タグはトランザクションごとに設定する必要があります。トランザクション タグを削除するには、空の文字列（''）に設定します。トランザクション タグは、トランザクションでステートメントが実行される前に設定する必要があります。

デフォルトは '' です。

同じステートメントに対してトランザクション タグとステートメント タグの両方を設定できます。

詳細については、リクエスト タグとトランザクション タグによるトラブルシューティングをご覧ください。

▶ 例: トランザクション タグ（クリックして展開）
 次の例は、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 トランザクションを管理して commit します。

READ_TIMESTAMP

SHOW VARIABLE READ_TIMESTAMP

最新の読み取り専用トランザクションの読み取りタイムスタンプが含まれる TIMESTAMP 型の 1 行と 1 列の結果セットを返します。このステートメントがタイムスタンプを返すのは、読み取り専用トランザクションがまだアクティブで、少なくとも 1 つのクエリを実行した場合、または読み取り専用トランザクションが commit されてから新しいトランザクションが開始されるまでの間のみです。それ以外の場合、結果は 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

Spanner が commit した最後に読み取り / 書き込みトランザクションの commit タイムスタンプが含まれる TIMESTAMP 型の 1 行と 1 列の結果セットを返します。このステートメントは、読み取り / 書き込みトランザクションを commit した後、後続の SELECT、DML、またはスキーマ変更ステートメントを実行する前にだけタイムスタンプを返します。それ以外の場合、結果は NULL です。

▶ 例: commit タイムスタンプ（クリックして展開）
 次の例は、Spanner JDBC ドライバを使用して書き込みオペレーションの最後の commit タイムスタンプを表示する方法を示しています。

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

1 行と 2 列の結果セットを返します。

  • COMMIT_TIMESTAMP（type=TIMESTAMP）は、最新のトランザクションが commit された日時を示します。
  • MUTATION_COUNT（type=INT64）は、commit されたトランザクションで適用されたミューテーションの数を示します。この値は、エミュレータで実行すると常に空になります。

ミューテーション数は、トランザクションが commit される前に SET RETURN_COMMIT_STATS が true に設定されている場合にのみ取得できます。

▶ 例: commit レスポンス（クリックして展開）
 次の例は、Spanner JDBC ドライバを使用して書き込みオペレーションの最後の commit レスポンスを表示する方法を示しています。

-- 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]

現在のトランザクションを commit します。TRANSACTION キーワードは省略可能です。

  • 読み取り / 書き込みトランザクションを commit すると、このトランザクションのすべての更新が他のトランザクションに表示され、Spanner でのトランザクションのすべてのロックが解除されます。
  • 読み取り専用トランザクションを commit すると、現在の読み取り専用トランザクションが終了します。後続のステートメントで、新しいトランザクションが開始されます。読み取り専用トランザクションの COMMIT と ROLLBACK にはセマンティックの違いがありません。

このステートメントは、アクティブなトランザクションがある間にのみ実行できます。

▶ 例: COMMIT TRANSACTION（クリックして展開）
 次の例は、Spanner JDBC ドライバを使用してトランザクションを commit する方法を示しています。

-- 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] を実行してトランザクションを開始し、トランザクションでまだステートメントを実行していない場合のみです。

このステートメントは、現在のトランザクションのトランザクション モードのみを設定します。トランザクションが commit またはロールバックすると、次のトランザクションは接続のデフォルト モードを使用します（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 の実行時に 1 つのバッチとして Spanner に送信されます。複数の DDL ステートメントを 1 つのバッチとして実行すると、通常はステートメントを個別に実行するよりも高速になります。

このステートメントは、アクティブなトランザクションが存在していない場合にのみ実行できます。

▶ 例: 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 が少なくとも 1 つの 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 and RUN Batch

次のステートメントは 2 つの DML ステートメントをまとめてバッチ処理し、1 回の呼び出しでサーバーに送信します。DML バッチは、トランザクションの一部として、または自動 commit モードで実行できます。

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 はパーティション分割クエリのみをサポートしています。

Data Boost は SET DATA_BOOST_ENABLED ステートメントで有効にできます。

Spanner JDBC ドライバは、パーティション分割されたクエリを実行するための次の 3 つの代替手段をサポートしています。

  • SET AUTO_PARTITION_MODE = true
  • RUN PARTITIONED QUERY sql
  • 複数の RUN PARTITION 'partition-token' が続く PARTITION sql

以下の各セクションでは、これらの方法について説明します。

DATA_BOOST_ENABLED

この接続でパーティション分割されたクエリに Data Boost を使用する必要があるかどうかを示す BOOL 型のプロパティ。デフォルトは 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 ドライバで 2 つのクエリを実行しています。

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

完全な例については、AutoPartitionModeExample をご覧ください。

RUN PARTITIONED QUERY

RUN PARTITIONED QUERY <sql>

Spanner でパーティション分割クエリとしてクエリを実行します。Data Boost でクエリを実行するには、DATA_BOOST_ENABLED が true に設定されていることを確認します。

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

Spanner JDBC ドライバは内部でクエリをパーティション分割し、パーティションを並列に実行します。結果は 1 つの結果セットに統合され、アプリケーションに返されます。パーティションを実行するワーカー スレッドの数は、変数 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

Spanner JDBC ドライバがパーティションの実行に使用するワーカー スレッドの数を示す INT64 型のプロパティ。この値は次の目的で使用されます。

  • 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' }

現在の SAVEPOINT_SUPPORT 構成を示す STRING 型のプロパティ。指定できる値は次のとおりです。

  • DISABLED: すべてのセーブポイント コマンドが無効になり、失敗します。
  • FAIL_AFTER_ROLLBACK: セーブポイント コマンドが有効になっています。セーブポイントにロールバックすると、トランザクション全体がロールバックされます。セーブポイントにロールバックした後にトランザクションの使用を試行すると、トランザクションは失敗します。
  • ENABLED: すべての savepoint コマンドが有効になっています。セーブポイントにロールバックすると、トランザクションがロールバックされ、セーブポイントへの再試行が実行されます。セーブポイントまでのトランザクションで使用された基盤となるデータが変更されている場合、このオペレーションは 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 言語データベースに接続する方法を学習する。