メインコンテンツまでスキップ
バージョン: 3.19
Features and pricing
New

ScalarDB Cluster Java API ガイド

注記

このページは英語版のページが機械翻訳されたものです。英語版との間に矛盾または不一致がある場合は、英語版を正としてください。

ScalarDB Cluster Java API は、ScalarDB Core の一部である Administrative API と Transaction API に加えて、Microservice Transaction API などの ScalarDB Cluster に固有の追加 API で構成されています。このガイドでは、どのような種類の API が存在するのか、それらの使用方法、例外の処理方法などの関連トピックについて説明します。

Administrative API​

このセクションでは、ScalarDB の Administrative API を使用してプログラムで管理操作を実行する方法について説明します。

警告

Administrative API の呼び出しが基盤となるデータベースに書き込みを行う場合、複数の書き込み操作がトリガーされます。ただし、これらの操作はアトミックに実行されないため、呼び出しが途中で失敗した場合、一貫性のない状態が発生する可能性があります。この非一貫性の問題を解決するには、名前空間またはテーブルを修復してください。詳細については、以下のページを参照してください:

注記

管理操作を実行する別の方法は、Schema Loader を使用することです。

DistributedTransactionAdmin インスタンスを取得する​

管理操作を実行するには、まず DistributedTransactionAdmin インスタンスを取得する必要があります。

DistributedTransactionAdmin インスタンスを取得するには、次のように TransactionFactory を使用します。

TransactionFactory transactionFactory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
DistributedTransactionAdmin admin = transactionFactory.getTransactionAdmin();

設定の詳細については、ScalarDB 設定を参照してください。

すべての管理操作を実行したら、次のように DistributedTransactionAdmin インスタンスを閉じる必要があります。

admin.close();

名前空間を作成する​

テーブルは1つの名前空間に属するため、テーブルを作成する前に名前空間を作成する必要があります。

名前空間は次のように作成できます。

// Create the namespace "ns". If the namespace already exists, an exception will be thrown.
admin.createNamespace("ns");

// Create the namespace only if it does not already exist.
boolean ifNotExists = true;
admin.createNamespace("ns", ifNotExists);

// Create the namespace with options.
Map<String, String> options = ...;
admin.createNamespace("ns", options);

作成オプション​

名前空間の作成操作では、オプション名と値のマップであるオプション (Map<String, String>) を指定できます。オプションを使用すると、ストレージアダプタ固有の設定ができます。

データベースを選択して、使用可能なオプションを確認します。

使用可能なオプションはありません。

テーブルを作成する​

テーブルを作成するときは、テーブルメタデータを定義してからテーブルを作成する必要があります。

テーブルメタデータを定義するには、TableMetadata を使用できます。次の図は、テーブルの列、パーティションキー、クラスタリングキー (クラスタリング順序を含む)、およびセカンダリインデックスを定義する方法を示しています。

// Define the table metadata.
TableMetadata tableMetadata =
    TableMetadata.newBuilder()
        .addColumn("c1", DataType.INT)
        .addColumn("c2", DataType.TEXT)
        .addColumn("c3", DataType.BIGINT)
        .addColumn("c4", DataType.FLOAT)
        .addColumn("c5", DataType.DOUBLE)
        .addPartitionKey("c1")
        .addClusteringKey("c2", Scan.Ordering.Order.DESC)
        .addClusteringKey("c3", Scan.Ordering.Order.ASC)
        .addSecondaryIndex("c4")
        .build();

ScalarDB のデータモデルの詳細については、データをモデル化するを参照してください。

次に、次のようにテーブルを作成します。

// Create the table "ns.tbl". If the table already exists, an exception will be thrown.
admin.createTable("ns", "tbl", tableMetadata);

// Create the table only if it does not already exist.
boolean ifNotExists = true;
admin.createTable("ns", "tbl", tableMetadata, ifNotExists);

// Create the table with options.
Map<String, String> options = ...;
admin.createTable("ns", "tbl", tableMetadata, options);

作成オプション​

テーブルの作成操作では、オプション名と値のマップであるオプション (Map<String, String>) を指定できます。オプションを使用すると、ストレージアダプタ固有の設定ができます。

データベースを選択して、使用可能なオプションを確認します。

名前説明デフォルト
transaction-metadata-decouplingConsensus Commitを使用している場合に、トランザクションメタデータ分離を有効にします。これにより、トランザクションメタデータがアプリケーションデータとは別のテーブルで管理されます。false

セカンダリインデックスを作成する​

セカンダリインデックスは次のように作成できます。

// Create a secondary index on column "c5" for table "ns.tbl". If a secondary index already exists, an exception will be thrown.
admin.createIndex("ns", "tbl", "c5");

// Create the secondary index only if it does not already exist.
boolean ifNotExists = true;
admin.createIndex("ns", "tbl", "c5", ifNotExists);

// Create the secondary index with options.
Map<String, String> options = ...;
admin.createIndex("ns", "tbl", "c5", options);
警告

Consensus Commit を使用している場合、非プライマリキー列で createIndex() を使用すると、コンパニオン before-image セカンダリインデックスも作成されます。詳細については、インデックスベース読み取りの正確性を参照してください。

作成オプション​

セカンダリインデックスの作成操作では、オプション名と値のマップであるオプション (Map<String, String>) を指定できます。オプションを使用すると、ストレージアダプタ固有の設定ができます。

データベースを選択して、使用可能なオプションを確認します。

使用可能なオプションはありません。

テーブルに新しい列を追加する​

次のように、テーブルに新しい非パーティションキー列を追加できます。

// Add a new column "c6" with the INT data type to the table "ns.tbl".
admin.addNewColumnToTable("ns", "tbl", "c6", DataType.INT);

// Add the new column only if it does not already exist.
boolean ifNotExists = true;
admin.addNewColumnToTable("ns", "tbl", "c6", DataType.INT, false, ifNotExists);
警告

テーブルに新しい列を追加する場合は、基盤となるストレージによって実行時間が大きく異なる可能性があるため、慎重に検討する必要があります。特にデータベースが本番環境で実行されている場合は、以下の点を考慮して適切に計画を立ててください。

  • Cosmos DB for NoSQL および DynamoDB の場合: テーブルスキーマは変更されないため、列の追加はほぼ瞬時に行われます。別のテーブルに格納されているテーブルメタデータのみが更新されます。
  • Cassandra の場合: 列を追加すると、スキーマメタデータのみが更新され、既存のスキーマレコードは変更されません。クラスタートポロジが実行時間の主な要因です。スキーマメタデータの変更は、ゴシッププロトコルを介して各クラスターノードに共有されます。このため、クラスターが大きいほど、すべてのノードが更新されるまでの時間が長くなります。
  • リレーショナルデータベース (MySQL、Oracle など) の場合: 列の追加は、データベースエンジンによってはテーブルの再構築を引き起こす可能性があります。そのような場合、実行に長時間かかることがあります。

テーブルから列を削除する​

次のようにテーブルから列を削除できます。

// Drop the column "c6" from the table "ns.tbl".
admin.dropColumnFromTable("ns", "tbl", "c6");

// Drop the column only if it exists.
boolean ifExists = true;
admin.dropColumnFromTable("ns", "tbl", "c6", ifExists);
注記

次の場合、テーブルから列を削除することはできません。

  • 列がパーティションキーまたはクラスタリングキーの一部である場合。
  • テーブルが Cassandra を除く非 JDBC データベース上にある場合。
警告

テーブルから列を削除する場合は、基盤となるストレージによって実行時間が大きく異なる可能性があるため、慎重に検討する必要があります。特にデータベースが本番環境で実行されている場合は、以下の点を考慮して適切に計画を立ててください。

  • Cassandra の場合: 列を削除すると、スキーマメタデータのみが更新され、実際のデータは次のコンパクション時に削除されます。クラスタートポロジが実行時間の主な要因です。スキーマメタデータの変更は、ゴシッププロトコルを介して各クラスターノードに共有されます。このため、クラスターが大きいほど、すべてのノードが更新されるまでの時間が長くなります。
  • リレーショナルデータベース (MySQL、Oracle など) の場合: 列の削除は、基盤となるリレーショナルデータベースに ALTER TABLE ... DROP COLUMN を発行し、データベースによってはテーブルの再構築を引き起こす可能性があります。そのような場合、実行に長時間かかることがあります。

テーブルの列の名前を変更する​

次のようにテーブルの列の名前を変更できます。

// Rename the column "c6" to "c66" in the table "ns.tbl".
admin.renameColumnInTable("ns", "tbl", "c6", "c66");
注記

次の場合、テーブルの列の名前を変更することはできません。

  • テーブルが Cassandra を除く非 JDBC データベース上にある場合。
  • Cassandra の場合、列がパーティションキーまたはクラスタリングキーの一部でない場合。
  • Db2 の場合、列がパーティションキー、クラスタリングキー、またはセカンダリインデックスキーの一部である場合。

テーブルの名前を変更する​

次のようにテーブルの名前を変更できます。

// Rename the table "ns.tbl" to "ns.new_tbl".
admin.renameTable("ns", "tbl", "new_tbl");
注記

非 JDBC データベースではテーブルの名前を変更することはできません。

テーブルの列のデータ型を変更する​

次のようにテーブルの列のデータ型を変更できます。

// Alter the data type of the column "c6" to BIGINT in the table "ns.tbl".
admin.alterColumnDataType("ns", "tbl", "c6", DataType.BIGINT);
注記

次の場合、テーブルの列のデータ型を変更することはできません。

  • 列がパーティションキー、クラスタリングキー、またはセカンダリインデックスキーの一部である場合。
  • テーブルが非 JDBC データベース上または SQLite 上にある場合。
  • INT から BIGINT、FLOAT から DOUBLE、および任意のデータから TEXT への変換以外の変換が指定されている場合。
  • Oracle の場合、INT から BIGINT 以外の変換が指定されている場合。
  • Db2 および TiDB の場合、BLOB から TEXT への変換が指定されている場合。
警告

列の型を変更する場合は、基盤となるストレージによって実行時間が大きく異なる可能性があるため、慎重に検討する必要があります。特にデータベースが本番環境で実行されている場合は、以下の点を考慮して適切に計画を立ててください。

  • リレーショナルデータベース (MySQL、Oracle など) の場合: 列の変更は、基盤となるリレーショナルデータベースに ALTER TABLE ... ALTER COLUMN または ALTER TABLE ... MODIFY を発行し、データベースによってはテーブルの再構築を引き起こす可能性があります。そのような場合、実行に長時間かかることがあります。

テーブルを切り捨てる​

テーブルを切り捨てるには、次のようにします。

// Truncate the table "ns.tbl".
admin.truncateTable("ns", "tbl");

セカンダリインデックスを削除する​

セカンダリインデックスは次のように削除できます。

// Drop the secondary index on column "c5" from table "ns.tbl". If the secondary index does not exist, an exception will be thrown.
admin.dropIndex("ns", "tbl", "c5");

// Drop the secondary index only if it exists.
boolean ifExists = true;
admin.dropIndex("ns", "tbl", "c5", ifExists);
警告

Consensus Commit を使用している場合、dropIndex() はコンパニオン before-image セカンダリインデックスも削除します。詳細については、インデックスベース読み取りの正確性を参照してください。

テーブルを削除する​

テーブルを削除するには、次のようにします。

// Drop the table "ns.tbl". If the table does not exist, an exception will be thrown.
admin.dropTable("ns", "tbl");

// Drop the table only if it exists.
boolean ifExists = true;
admin.dropTable("ns", "tbl", ifExists);

名前空間を削除する​

名前空間を削除するには、次のようにします。

// Drop the namespace "ns". If the namespace does not exist, an exception will be thrown.
admin.dropNamespace("ns");

// Drop the namespace only if it exists.
boolean ifExists = true;
admin.dropNamespace("ns", ifExists);

既存の名前空間を取得する​

既存の名前空間は次のように取得できます。

Set<String> namespaces = admin.getNamespaceNames();

名前空間のテーブルを取得する​

名前空間のテーブルは次のように取得できます。

// Get the tables of the namespace "ns".
Set<String> tables = admin.getNamespaceTableNames("ns");

テーブルメタデータを取得する​

テーブルメタデータは次のように取得できます。

// Get the table metadata for "ns.tbl".
TableMetadata tableMetadata = admin.getTableMetadata("ns", "tbl");

名前空間を修復する​

名前空間が不明な状態の場合 (たとえば、名前空間が基盤となるストレージに存在するが ScalarDB メタデータが存在しない、またはその逆)、このメソッドは必要に応じて名前空間とそのメタデータを再作成します。

名前空間は次のように修復できます。

// Repair the namespace "ns" with options.
Map<String, String> options = ...;
admin.repairNamespace("ns", options);

テーブルを修復する​

テーブルが不明な状態の場合 (テーブルは基盤となるストレージに存在するが ScalarDB メタデータは存在しない、またはその逆)、このメソッドは必要に応じてテーブル、そのセカンダリインデックス、およびそのメタデータを再作成します。

テーブルは次のように修復できます。

// Repair the table "ns.tbl" with options.
TableMetadata tableMetadata =
    TableMetadata.newBuilder()
        ...
        .build();
Map<String, String> options = ...;
admin.repairTable("ns", "tbl", tableMetadata, options);
警告

Consensus Commit を使用している場合、以前のバージョンから ScalarDB 3.16.5、3.17.3、または 3.18.0 にアップグレードした後、インデックスベース読み取りに必要なコンパニオン before-image セカンダリインデックスを作成するために、既存の各テーブルで repairTable() を実行する必要があります。詳細については、インデックスベース読み取りの正確性を参照してください。

最新の ScalarDB API をサポートするように環境をアップグレードする​

ScalarDB API の最新バージョンをサポートするように ScalarDB 環境をアップグレードできます。通常、リリースノートに記載されているように、アプリケーション環境が使用する ScalarDB バージョンを更新した後、このメソッドを実行する必要があります。

// Upgrade the ScalarDB environment.
Map<String, String> options = ...;
admin.upgrade(options);

Coordinator テーブルの操作を指定する​

Coordinator テーブルは、Transaction API によってトランザクションのステータスを追跡するために使用されます。

トランザクションマネージャーを使用する場合は、トランザクションを実行するために Coordinator テーブルを作成する必要があります。テーブルの作成に加えて、Coordinator テーブルを切り捨てたり削除したりすることもできます。

Coordinator テーブルを作成する​

Coordinator テーブルは次のように作成できます。

// Create the Coordinator table.
admin.createCoordinatorTables();

// Create the Coordinator table only if one does not already exist.
boolean ifNotExist = true;
admin.createCoordinatorTables(ifNotExist);

// Create the Coordinator table with options.
Map<String, String> options = ...;
admin.createCoordinatorTables(options);

Coordinator テーブルを切り捨てる​

Coordinator テーブルは次のように切り捨てることができます。

// Truncate the Coordinator table.
admin.truncateCoordinatorTables();

Coordinator テーブルを削除する​

Coordinator テーブルは次のように削除できます。

// Drop the Coordinator table.
admin.dropCoordinatorTables();

// Drop the Coordinator table if one exist.
boolean ifExist = true;
admin.dropCoordinatorTables(ifExist);

テーブルをインポートする​

既存のテーブルを ScalarDB にインポートするには、次のようにします。

// Import the table "ns.tbl". If the table is already managed by ScalarDB, the target table does not
// exist, or the table does not meet the requirements of the ScalarDB table, an exception will be thrown.
admin.importTable("ns", "tbl", options, overrideColumnsType);
警告

Consensus Commitを使用している場合に、運用環境で ScalarDB にテーブルをインポートする場合は、データベーステーブルと ScalarDB メタデータテーブルにトランザクションメタデータ列が追加されるため、慎重に計画する必要があります。この場合、データベースと ScalarDB の間にはいくつかの違いがあり、いくつかの制限もあります。詳細については、ScalarDB Schema Loader を使用して既存のテーブルを ScalarDB にインポートするを参照してください。

また、transaction-metadata-decoupling オプションを true に指定することで、トランザクションメタデータ分離を有効にして、トランザクションメタデータをアプリケーションデータとは別のテーブルに保存することもできます。詳細については、トランザクションメタデータ分離を参照してください。

認証と認可 API​

ScalarDB Cluster は認証と認可をサポートしています。ユーザー、ロール、権限を Java を通じてプログラムで管理するには、ClusterClientTransactionAdmin を使用します。これは AuthAdmin を実装しています。

ユーザー、ロール、権限などの認証と認可の概念については、ユーザーの認証と認可を参照してください。

ユーザーを管理する​

次の操作により、ユーザーの作成、変更、取得ができます。

ユーザーを作成または変更する際、UserOption 列挙型を使用して次のオプションを指定できます:

オプション説明
SUPERUSERユーザーをスーパーユーザーとして作成または設定します。
NO_SUPERUSERユーザーを非スーパーユーザーとして作成または設定します。オプションを指定しない場合のデフォルトです。

また、AuthenticationMethod 列挙型を使用して、ユーザーに対して1つ以上の認証方法を指定できます:

認証方法説明
USERPASSユーザー名とパスワードによる認証。
OIDCOpenID Connect (OIDC) 認証。
ユーザーを作成する​

ユーザーは次のように作成できます。

// Create a regular (non-superuser) user with a password.
admin.createUser("username", "password");

// Create a superuser.
admin.createUser("username", "password", AuthAdmin.UserOption.SUPERUSER);

// Create a user without a password for OIDC authentication.
admin.createUser("username", null, ImmutableSet.of(AuthAdmin.AuthenticationMethod.OIDC));

// Create a user with specific authentication methods.
admin.createUser("username", "password", ImmutableSet.of(AuthAdmin.AuthenticationMethod.USERPASS, AuthAdmin.AuthenticationMethod.OIDC));
ユーザーを変更する​

既存のユーザーは次のように変更 (修正) できます。

// Change the password of an existing user.
admin.alterUser("username", "newpassword");

// Remove the password of an existing user (pass an empty string to delete the password).
admin.alterUser("username", "");

// Promote an existing user to superuser.
admin.alterUser("username", null, AuthAdmin.UserOption.SUPERUSER);

// Change the authentication methods of an existing user.
admin.alterUser("username", null, ImmutableSet.of(AuthAdmin.AuthenticationMethod.OIDC));
注記

alterUser にパスワードとして null を渡した場合、パスワードは変更されません。空の文字列を渡した場合、パスワードは削除されます。

ユーザーを削除する​

ユーザーは次のように削除できます。

admin.dropUser("username");
ユーザーを取得する​

既存のユーザーは次のように取得できます。

Optional<AuthAdmin.User> user = admin.getUser("username");
user.ifPresent(u -> {
  System.out.println("Name: " + u.getName());
  System.out.println("Superuser: " + u.isSuperuser());
  System.out.println("Authentication methods: " + u.getAuthenticationMethods());
});
すべてのユーザーを取得する​

すべてのユーザーは次のように取得できます。

List<AuthAdmin.User> users = admin.getUsers();
for (AuthAdmin.User user : users) {
  System.out.println("Name: " + user.getName());
  System.out.println("Superuser: " + user.isSuperuser());
}
現在のユーザーを取得する​

現在ログインしているユーザーは次のように取得できます。

AuthAdmin.User currentUser = admin.getCurrentUser();
System.out.println("Current user: " + currentUser.getName());
System.out.println("Superuser: " + currentUser.isSuperuser());

ユーザーの権限を管理する​

次の操作により、ユーザーへの権限の付与、取り消し、確認ができます。

Privilege 列挙型は、次の値を定義しています:

権限説明
READ読み取り操作 (Get および Scan)
WRITE書き込み操作 (Put、Insert、Upsert、Update)
DELETE削除操作 (Delete)
CREATEテーブルおよびインデックスの作成
DROPテーブルおよびインデックスの削除
TRUNCATEテーブルの切り捨て
ALTERテーブルの変更
GRANTテーブルに対する権限の付与および取り消し
注記

これらの権限名は、ScalarDB SQL の DCL で使用される SQL レベルの権限名 (SELECT、INSERT、UPDATE など) とは異なります。Java API を直接使用する場合は、上記の Privilege 列挙型の値を使用してください。

ユーザーに権限を付与する​

名前空間内のすべてのテーブル、または特定のテーブルに対して、ユーザーに次のように権限を付与できます。

// Grant READ and WRITE privileges to a user for all tables in a namespace.
admin.grant("username", "namespace", AuthAdmin.Privilege.READ, AuthAdmin.Privilege.WRITE);

// Grant READ and WRITE privileges to a user for a specific table.
admin.grant("username", "namespace", "table", AuthAdmin.Privilege.READ, AuthAdmin.Privilege.WRITE);
ユーザーから権限を取り消す​

名前空間内のすべてのテーブル、または特定のテーブルについて、ユーザーから次のように権限を取り消すことができます。

// Revoke READ privilege from a user for all tables in a namespace.
admin.revoke("username", "namespace", AuthAdmin.Privilege.READ);

// Revoke READ privilege from a user for a specific table.
admin.revoke("username", "namespace", "table", AuthAdmin.Privilege.READ);
注記

権限は、付与されたスコープでのみ取り消すことができます。権限が付与されていないスコープで取り消しを行っても、エラーにはならず、単に何も起こりません (別のスコープで付与された権限が削除されることはありません)。

たとえば、名前空間レベルで付与された READ 権限を特定のテーブルに対して取り消しても、効果はありません。ユーザーが権限を持っているかどうかを確認する で説明されているように、テーブルレベルの権限チェックでは名前空間レベルの権限も考慮されるため、テーブルスコープでの取り消しが行われた後も、名前空間全体への付与によってそのテーブルへのアクセスは引き続き許可されます。

ユーザーの権限を取得する​

名前空間内のすべてのテーブル、または特定のテーブルについて、ユーザーが持つ権限を次のように取得できます。

// Get privileges for a user for all tables in a namespace.
Set<AuthAdmin.Privilege> nsPrivileges = admin.getPrivileges("username", "namespace");

// Get privileges for a user for a specific table.
Set<AuthAdmin.Privilege> tablePrivileges = admin.getPrivileges("username", "namespace", "table");
注記

getPrivileges() は、直接付与された権限のみを返します。ロールから継承された権限、テーブルに適用される名前空間レベルの権限、スーパーユーザーのアクセス権は含まれません。ユーザーの実効的なアクセス権を確認するには、hasPrivilege() を使用してください。

ユーザーが権限を持っているかどうかを確認する​

名前空間または特定のテーブルについて、ユーザーが特定の権限を持っているかどうかを次のように確認できます。

// Check if a user has READ privilege on the namespace.
boolean hasNsPrivilege = admin.hasPrivilege("username", "namespace", AuthAdmin.Privilege.READ);

// Check if a user has READ privilege for a specific table.
boolean hasTablePrivilege = admin.hasPrivilege("username", "namespace", "table", AuthAdmin.Privilege.READ);
注記

特定のテーブルに対する権限を確認する場合、テーブルレベルと名前空間レベルの両方の権限 (ロールを介して推移的に付与された権限を含む) が考慮されます。名前空間に対する権限を確認する場合は、名前空間レベルの権限 (ロールを介して推移的に付与された権限を含む) のみが考慮されます。スーパーユーザーの場合、どの権限チェックでも常に true が返されます。

ロールと権限を管理する​

次の操作により、ロールの作成、変更、取得、およびユーザーや他のロールへのロールの付与と取り消しができます。

ロールを作成する​

ロールは次のように作成できます。

admin.createRole("rolename");
ロールを削除する​

ロールは次のように削除できます。

admin.dropRole("rolename");
ロールを取得する​

既存のロールは次のように取得できます。

Optional<AuthAdmin.Role> role = admin.getRole("rolename");
role.ifPresent(r -> {
  System.out.println("Name: " + r.getName());
  System.out.println("Granted roles: " + r.getGrantedRoles());
});
すべてのロールを取得する​

すべてのロールは次のように取得できます。

List<AuthAdmin.Role> roles = admin.getRoles();
for (AuthAdmin.Role role : roles) {
  System.out.println("Name: " + role.getName());
}
ユーザーのロールを取得する​

ユーザーに付与されたロールは次のように取得できます。

List<AuthAdmin.RoleForUser> roles = admin.getRolesForUser("username");
for (AuthAdmin.RoleForUser role : roles) {
  System.out.println("Role: " + role.getName());
  System.out.println("Has admin option: " + role.hasAdminOptionOnUser());
}
ユーザーにロールを付与する​

ロールは次のようにユーザーに付与できます。

// Grant a role to a user without admin option.
admin.grantRoleToUser("username", "rolename", false);

// Grant a role to a user with admin option (the user can then grant this role to others).
admin.grantRoleToUser("username", "rolename", true);
ユーザーからロールを取り消す​

ロールは次のようにユーザーから取り消すことができます。

admin.revokeRoleFromUser("username", "rolename");
ロールに対するユーザーの admin オプションを取り消す​

ロール自体は取り消さずに、ユーザーの admin オプションのみを次のように取り消すことができます。

admin.revokeAdminOptionFromUser("username", "rolename");
ロールの付与先ユーザーを取得する​

特定のロールが付与されているユーザーは次のように取得できます。

List<AuthAdmin.GranteeUserRef> grantees = admin.getGranteeUsersForRole("rolename");
for (AuthAdmin.GranteeUserRef grantee : grantees) {
  System.out.println("User: " + grantee.getName());
  System.out.println("Has admin option: " + grantee.hasAdminOption());
}
ロールにメンバーロールを付与する​

ロールにメンバーロールを付与すると、そのロールを持つユーザーはメンバーロールの権限を継承します。次のように付与できます。

// Grant a member role to a role without admin option.
admin.grantRoleToRole("rolename", "memberrolename", false);

// Grant a member role to a role with admin option.
admin.grantRoleToRole("rolename", "memberrolename", true);
ロールからメンバーロールを取り消す​

メンバーロールは次のようにロールから取り消すことができます。

admin.revokeRoleFromRole("rolename", "memberrolename");
別のロールに対するロールの admin オプションを取り消す​

ロール間の付与について、admin オプションのみを次のように取り消すことができます。

admin.revokeAdminOptionFromRole("rolename", "memberrolename");
ロールに権限を付与する​

名前空間内のすべてのテーブル、または特定のテーブルに対して、ロールに次のように権限を付与できます。

// Grant READ and WRITE privileges to a role for all tables in a namespace.
admin.grantPrivilegeToRole("rolename", "namespace", AuthAdmin.Privilege.READ, AuthAdmin.Privilege.WRITE);

// Grant READ and WRITE privileges to a role for a specific table.
admin.grantPrivilegeToRole("rolename", "namespace", "table", AuthAdmin.Privilege.READ, AuthAdmin.Privilege.WRITE);
ロールから権限を取り消す​

名前空間内のすべてのテーブル、または特定のテーブルについて、ロールから次のように権限を取り消すことができます。

// Revoke READ privilege from a role for all tables in a namespace.
admin.revokePrivilegeFromRole("rolename", "namespace", AuthAdmin.Privilege.READ);

// Revoke READ privilege from a role for a specific table.
admin.revokePrivilegeFromRole("rolename", "namespace", "table", AuthAdmin.Privilege.READ);
注記

権限は、付与されたスコープでのみ取り消すことができます。権限が付与されていないスコープで取り消しを行っても、エラーにはならず、単に何も起こりません (別のスコープで付与された権限が削除されることはありません)。

たとえば、名前空間レベルで付与された READ 権限を特定のテーブルに対して取り消しても、効果はありません。ユーザーが権限を持っているかどうかを確認する で説明されているように、テーブルレベルの権限チェックでは名前空間レベルの権限も考慮されるため、テーブルスコープでの取り消しが行われた後も、名前空間全体への付与によってそのテーブルへのアクセスは引き続き許可されます。

ロールの権限を取得する​

名前空間内のすべてのテーブル、または特定のテーブルについて、ロールが持つ権限を次のように取得できます。

// Get privileges for a role for all tables in a namespace.
Set<AuthAdmin.Privilege> nsPrivileges = admin.getRolePrivileges("rolename", "namespace");

// Get privileges for a role for a specific table.
Set<AuthAdmin.Privilege> tablePrivileges = admin.getRolePrivileges("rolename", "namespace", "table");
注記

getRolePrivileges() は、ロールに直接付与された権限のみを返します。メンバーロールから継承された権限や、テーブルに適用される名前空間レベルの権限は含まれません。

これらの API からの失敗の処理の詳細については、認証と認可の例外を参照してください。

Transaction API​

このセクションでは、ScalarDB の Transaction API を使用してトランザクション操作を実行する方法について説明します。

DistributedTransactionManager インスタンスを取得する​

トランザクション操作を実行するには、まず DistributedTransactionManager インスタンスを取得する必要があります。

DistributedTransactionManager インスタンスを取得するには、次のように TransactionFactory を使用します。

TransactionFactory transactionFactory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
DistributedTransactionManager transactionManager = transactionFactory.getTransactionManager();

すべてのトランザクション操作を実行した後、次のように DistributedTransactionManager インスタンスを閉じる必要があります。

transactionManager.close();

トランザクションを実行する​

このサブセクションでは、複数の CRUD 操作でトランザクションを実行する方法について説明します。

トランザクションを開始する​

トランザクション CRUD 操作を実行する前に、トランザクションを開始する必要があります。

トランザクションは次のように開始できます。

// Begin a transaction.
DistributedTransaction transaction = transactionManager.begin();

または、次のようにトランザクションを開始することもできます。

// Start a transaction.
DistributedTransaction transaction = transactionManager.start();

あるいは、次のようにトランザクション ID を指定して、トランザクションに begin メソッドを使用することもできます。

// Begin a transaction with specifying a transaction ID.
DistributedTransaction transaction = transactionManager.begin("<TRANSACTION_ID>");

または、次のようにトランザクション ID を指定して、トランザクションに start メソッドを使用することもできます。

// Start a transaction with specifying a transaction ID.
DistributedTransaction transaction = transactionManager.start("<TRANSACTION_ID>");
注記

トランザクション ID を指定すると、外部システムを ScalarDB にリンクする場合に便利です。それ以外の場合は、begin() メソッドまたは start() メソッドを使用する必要があります。

トランザクション ID を指定する場合は、ScalarDB の正確性はトランザクション ID の一意性に依存するため、システム全体で一意の ID (UUID v4など) を指定してください。

読み取り専用モードでトランザクションを開始またはスタートする​

読み取り専用モードでトランザクションを開始またはスタートすることもできます。この場合、トランザクションでは書き込み操作は許可されず、ScalarDB がそれを読み取り操作に最適化する可能性があります。

注記

パフォーマンスを向上させ、リソース使用量を削減するために、読み取り専用操作には読み取り専用トランザクションを使用することを強く推奨します。

次のように読み取り専用モードでトランザクションを開始またはスタートできます。

// Begin a transaction in read-only mode.
DistributedTransaction transaction = transactionManager.beginReadOnly();
// Start a transaction in read-only mode.
DistributedTransaction transaction = transactionManager.startReadOnly();

または、次のようにトランザクション ID を指定して、beginReadOnly メソッドと startReadOnly メソッドを使用することもできます。

// Begin a transaction in read-only mode by specifying a transaction ID.
DistributedTransaction transaction = transactionManager.beginReadOnly("<TRANSACTION_ID>");
// Start a transaction in read-only mode by specifying a transaction ID.
DistributedTransaction transaction = transactionManager.startReadOnly("<TRANSACTION_ID>");
注記

トランザクション ID を指定する方法は、外部システムを ScalarDB にリンクしたい場合に利用できます。それ以外の場合は、beginReadOnly() メソッドまたは startReadOnly() メソッドを使用する必要があります。

トランザクション ID を指定する場合は、ScalarDB の正確性はトランザクション ID の一意性に依存するため、システム全体で一意の ID (UUID v4など) を指定してください。

属性を指定してトランザクションを開始またはスタートする​

トランザクションを開始またはスタートするときに、トランザクションスコープの属性のマップを指定できます。指定した属性はトランザクション内で発行されるすべてのオペレーションにマージされるため、トランザクション全体に一律に適用する設定を開始時に一度だけ指定できます。オペレーションにすでに同じ属性キーが設定されている場合は、オペレーション側の属性が優先されます。

次のように属性を指定してトランザクションを開始またはスタートできます。

// Specify attributes for the transaction.
Map<String, String> attributes = ...;

// Begin a transaction with attributes.
DistributedTransaction transaction = transactionManager.begin(attributes);
// Start a transaction with attributes.
DistributedTransaction transaction = transactionManager.start(attributes);

次のように、トランザクション ID と属性を一緒に指定することもできます。

// Begin a transaction with attributes by specifying a transaction ID.
DistributedTransaction transaction = transactionManager.begin("<TRANSACTION_ID>", attributes);
// Start a transaction with attributes by specifying a transaction ID.
DistributedTransaction transaction = transactionManager.start("<TRANSACTION_ID>", attributes);

beginReadOnly メソッドと startReadOnly メソッドにも、属性を受け取るオーバーロードがあります。

// Begin a transaction in read-only mode with attributes.
DistributedTransaction transaction = transactionManager.beginReadOnly(attributes);
// Start a transaction in read-only mode with attributes.
DistributedTransaction transaction = transactionManager.startReadOnly(attributes);
// Begin a transaction in read-only mode with attributes by specifying a transaction ID.
DistributedTransaction transaction = transactionManager.beginReadOnly("<TRANSACTION_ID>", attributes);
// Start a transaction in read-only mode with attributes by specifying a transaction ID.
DistributedTransaction transaction = transactionManager.startReadOnly("<TRANSACTION_ID>", attributes);

利用可能な属性の一覧については、オペレーション属性を参照してください。

トランザクションに参加する​

非推奨の通知

join() メソッドは ScalarDB 3.19 以降非推奨となり、将来のリリースで削除される予定です。

トランザクションに参加することは、トランザクションが複数のクライアントリクエストにまたがるステートフルアプリケーション向けです。このようなシナリオでは、アプリケーションは最初のクライアントリクエスト中にトランザクションを開始できます。その後、後続のクライアントリクエストで、アプリケーションは join() メソッドを使用して進行中のトランザクションに参加できます。

次のようにトランザクション ID を指定すると、すでに開始されている進行中のトランザクションに参加できます。

// Join a transaction.
DistributedTransaction transaction = transactionManager.join("<TRANSACTION_ID>");
注記

getId() を使用してトランザクション ID を取得するには、次のように指定します。

tx.getId();

トランザクションを再開する​

非推奨の通知

resume() メソッドは ScalarDB 3.19 以降非推奨となり、将来のリリースで削除される予定です。

トランザクションの再開は、トランザクションが複数のクライアントリクエストにまたがるステートフルアプリケーション向けです。このようなシナリオでは、アプリケーションは最初のクライアントリクエスト中にトランザクションを開始できます。その後、後続のクライアントリクエストで、アプリケーションは resume() メソッドを使用して進行中のトランザクションを再開できます。

次のようにトランザクション ID を指定すると、すでに開始した進行中のトランザクションを再開できます。

// Resume a transaction.
DistributedTransaction transaction = transactionManager.resume("<TRANSACTION_ID>");
注記

getId() を使用してトランザクション ID を取得するには、次のように指定します。

tx.getId();

CRUD 操作を実装する​

次のセクションでは、キーの構築と CRUD 操作について説明します。

注記

CRUD 操作のすべてのビルダーは consistency() メソッドを使用して一貫性を指定できますが、これらのメソッドは無視されます。代わりに、トランザクションでは常に LINEARIZABLE 一貫性レベルが使用されます。

キーの構築​

ほとんどの CRUD 操作では、Key オブジェクト (パーティションキー、クラスタリングキーなど) を指定する必要があります。そのため、CRUD 操作に進む前に、Key オブジェクトの構築方法を次に説明します。

単一の列キーの場合、次のように Key.of<TYPE_NAME>() メソッドを使用してキーを構築できます。

// For a key that consists of a single column of INT.
Key key1 = Key.ofInt("col1", 1);

// For a key that consists of a single column of BIGINT.
Key key2 = Key.ofBigInt("col1", 100L);

// For a key that consists of a single column of DOUBLE.
Key key3 = Key.ofDouble("col1", 1.3d);

// For a key that consists of a single column of TEXT.
Key key4 = Key.ofText("col1", "value");

2～5列で設定されるキーの場合は、Key.of() メソッドを使用して次のようにキーを構築できます。Guava の ImmutableMap.of() と同様に、列名と値を順番に指定する必要があります。

// For a key that consists of two to five columns.
Key key1 = Key.of("col1", 1, "col2", 100L);
Key key2 = Key.of("col1", 1, "col2", 100L, "col3", 1.3d);
Key key3 = Key.of("col1", 1, "col2", 100L, "col3", 1.3d, "col4", "value");
Key key4 = Key.of("col1", 1, "col2", 100L, "col3", 1.3d, "col4", "value", "col5", false);

5列を超えるキーの場合、ビルダーを使用して次のようにキーを構築できます。

// For a key that consists of more than five columns.
Key key = Key.newBuilder()
    .addInt("col1", 1)
    .addBigInt("col2", 100L)
    .addDouble("col3", 1.3d)
    .addText("col4", "value")
    .addBoolean("col5", false)
    .addInt("col6", 100)
    .build();
Get 操作​

Get は、主キーで指定された単一のレコードを取得する操作です。

まず Get オブジェクトを作成し、次に以下のように transaction.get() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Get` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Get get =
    Get.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .projections("c1", "c2", "c3", "c4")
        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
        .build();

// Execute the `Get` operation.
Optional<Result> result = transaction.get(get);

射影を指定して、返される列を選択できます。

WHERE 句を使用する​

where() メソッドを使用して任意の条件を指定することもできます。取得したレコードが where() メソッドで指定された条件と一致しない場合は、Optional.empty() が返されます。where() メソッドの引数として、条件、AND 条件セット、または OR 条件セットを指定できます。where() メソッドを呼び出した後、次のように and() メソッドまたは or() メソッドを使用して、さらに条件または条件セットを追加できます。

// Create a `Get` operation with condition sets.
Get get =
    Get.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .where(
            ConditionSetBuilder.condition(ConditionBuilder.column("c1").isLessThanInt(10))
                .or(ConditionBuilder.column("c1").isGreaterThanInt(20))
                .build())
        .and(
            ConditionSetBuilder.condition(ConditionBuilder.column("c2").isLikeText("a%"))
                .or(ConditionBuilder.column("c2").isLikeText("b%"))
                .build())
        .build();
注記

where() 条件メソッドチェーンでは、条件は上記の例のように ConditionalExpression または OrConditionSet の AND 結合 (結合正規形と呼ばれる)、または ConditionalExpression または AndConditionSet の OR 結合 (分離正規形と呼ばれる) である必要があります。

使用可能な条件と条件セットの詳細については、Javadoc の ConditionBuilder および ConditionSetBuilder ページを参照してください。

Result オブジェクトの処理​

Get 操作と Scan 操作は Result オブジェクトを返します。次に、Result オブジェクトの処理方法を示します。

次のように get<TYPE_NAME>("<COLUMN_NAME>") メソッドを使用して、結果の列値を取得できます。

// Get the BOOLEAN value of a column.
boolean booleanValue = result.getBoolean("<COLUMN_NAME>");

// Get the INT value of a column.
int intValue = result.getInt("<COLUMN_NAME>");

// Get the BIGINT value of a column.
long bigIntValue = result.getBigInt("<COLUMN_NAME>");

// Get the FLOAT value of a column.
float floatValue = result.getFloat("<COLUMN_NAME>");

// Get the DOUBLE value of a column.
double doubleValue = result.getDouble("<COLUMN_NAME>");

// Get the TEXT value of a column.
String textValue = result.getText("<COLUMN_NAME>");

// Get the BLOB value of a column as a `ByteBuffer`.
ByteBuffer blobValue = result.getBlob("<COLUMN_NAME>");

// Get the BLOB value of a column as a `byte` array.
byte[] blobValueAsBytes = result.getBlobAsBytes("<COLUMN_NAME>");

// Get the DATE value of a column as a `LocalDate`.
LocalDate dateValue = result.getDate("<COLUMN_NAME>");

// Get the TIME value of a column as a `LocalTime`.
LocalTime timeValue = result.getTime("<COLUMN_NAME>");

// Get the TIMESTAMP value of a column as a `LocalDateTime`.
LocalDateTime timestampValue = result.getTimestamp("<COLUMN_NAME>");

// Get the TIMESTAMPTZ value of a column as a `Instant`.
Instant timestampTZValue = result.getTimestampTZ("<COLUMN_NAME>");

列の値が null かどうかを確認する必要がある場合は、isNull("<COLUMN_NAME>") メソッドを使用できます。

// Check if a value of a column is null.
boolean isNull = result.isNull("<COLUMN_NAME>");

詳細については、Javadoc の Result ページを参照してください。

セカンダリインデックスを使用して Get を実行する​

セカンダリインデックスを使用して Get 操作を実行できます。

パーティションキーを指定する代わりに、次のようにインデックスキー (インデックス付き列) を指定してセカンダリインデックスを使用できます。

// Create a `Get` operation by using a secondary index.
Key indexKey = Key.ofFloat("c4", 1.23F);

Get get =
    Get.newBuilder()
        .namespace("ns")
        .table("tbl")
        .indexKey(indexKey)
        .projections("c1", "c2", "c3", "c4")
        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
        .build();

// Execute the `Get` operation.
Optional<Result> result = transaction.get(get);

where() メソッドを使用して任意の条件を指定することもできます。詳細については、WHERE 句を使用するを参照してください。

注記

結果に複数のレコードがある場合、transaction.get() は例外をスローします。複数の結果を処理する場合は、セカンダリインデックスを使用して Scan を実行するを参照してください。

Scan 操作​

Scan は、パーティション内の複数のレコードを取得する操作です。Scan 操作では、クラスタリングキーの境界とクラスタリングキー列の順序を指定できます。Scan 操作を実行するには、transaction.scan() メソッドまたは transaction.getScanner() メソッドを使用できます。

  • transaction.scan():
    • このメソッドは、指定された Scan 操作を即座に実行し、一致するすべてのレコードのリストを返します。結果セットがメモリに収まる程度の小さい場合に適しています。
  • transaction.getScanner():
    • このメソッドは、結果セットを遅延的にイテレートできる Scanner オブジェクトを返します。結果セットが大きくなる可能性がある場合に有用で、すべてのレコードを一度にメモリに読み込むことを避けられます。

まず Scan オブジェクトを作成し、次に transaction.scan() メソッドまたは transaction.getScanner() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Scan` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key startClusteringKey = Key.of("c2", "aaa", "c3", 100L);
Key endClusteringKey = Key.of("c2", "aaa", "c3", 300L);

Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .start(startClusteringKey, true)    // Include startClusteringKey
        .end(endClusteringKey, false)       // Exclude endClusteringKey
        .projections("c1", "c2", "c3", "c4")
        .orderings(Scan.Ordering.desc("c2"), Scan.Ordering.asc("c3"))
        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
        .limit(10)
        .build();

// Execute the `Scan` operation by using the `transaction.scan()` method.
List<Result> results = transaction.scan(scan);

// Or, execute the `Scan` operation by using the `transaction.getScanner()` method.
try (TransactionCrudOperable.Scanner scanner = transaction.getScanner(scan)) {
  // Fetch the next result from the scanner
  Optional<Result> result = scanner.one();

  // Fetch all remaining results from the scanner
  List<Result> allResults = scanner.all();
}

クラスタリングキー境界を省略するか、start 境界または end 境界のいずれかを指定できます。orderings を指定しない場合は、テーブルの作成時に定義したクラスタリング順序で結果が並べられます。

さらに、projections を指定して返される列を選択し、limit を使用して Scan 操作で返されるレコードの数を指定できます。

WHERE 句を使用する​

where() メソッドを使用してスキャンされたレコードをフィルタリングすることで、任意の条件を指定することもできます。where() メソッドの引数として、条件、AND 条件セット、または OR 条件セットを指定できます。where() メソッドを呼び出した後、次のように and() メソッドまたは or() メソッドを使用して、さらに条件または条件セットを追加できます。

// Create a `Scan` operation with condition sets.
Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .all()
        .where(
            ConditionSetBuilder.condition(ConditionBuilder.column("c1").isLessThanInt(10))
                .or(ConditionBuilder.column("c1").isGreaterThanInt(20))
                .build())
        .and(
            ConditionSetBuilder.condition(ConditionBuilder.column("c2").isLikeText("a%"))
                .or(ConditionBuilder.column("c2").isLikeText("b%"))
                .build())
        .limit(10)
        .build();
注記

where() 条件メソッドチェーンでは、条件は上記の例のように ConditionalExpression または OrConditionSet の AND 結合 (結合正規形と呼ばれる)、または ConditionalExpression または AndConditionSet の OR 結合 (分離正規形と呼ばれる) である必要があります。

使用可能な条件と条件セットの詳細については、Javadoc の ConditionBuilder および ConditionSetBuilder ページを参照してください。

セカンダリインデックスを使用して Scan を実行する​

セカンダリインデックスを使用して、Scan 操作を実行できます。

パーティションキーを指定する代わりに、次のようにインデックスキー (インデックス付き列) を指定してセカンダリインデックスを使用できます。

// Create a `Scan` operation by using a secondary index.
Key indexKey = Key.ofFloat("c4", 1.23F);

Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .indexKey(indexKey)
        .projections("c1", "c2", "c3", "c4")
        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
        .limit(10)
        .build();

// Execute the `Scan` operation.
List<Result> results = transaction.scan(scan);

where() メソッドを使用して任意の条件を指定することもできます。詳細については、WHERE 句を使用するを参照してください。

注記

セカンダリインデックスを使用して、Scan でクラスタリングキーの境界と順序を指定することはできません。

パーティションキーを指定せずにクロスパーティション Scan を実行し、テーブルのすべてのレコードを取得します​

ScalarDB プロパティファイルで次の設定を有効にすると、パーティションキーを指定せずに、すべてのパーティションにわたって Scan 操作 (クロスパーティションスキャン と呼びます) を実行できます。

scalar.db.cross_partition_scan.enabled=true
警告

非 JDBC データベースの場合、SERIALIZABLE 分離レベルでクロスパーティションスキャンを有効にした場合でも、トランザクションは読み取りコミットスナップショット分離 (SNAPSHOT) で実行される可能性があります。これは、より低い分離レベルです。非 JDBC データベースを使用する場合は、トランザクションの一貫性が重要でない場合にのみ、クロスパーティションスキャンを使用してください。

ビルダーで partitionKey() メソッドを呼び出す代わりに、次のように all() メソッドを呼び出して、パーティションキーを指定せずにテーブルをスキャンできます。

// Create a `Scan` operation without specifying a partition key.
Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .all()
        .projections("c1", "c2", "c3", "c4")
        .limit(10)
        .build();

// Execute the `Scan` operation.
List<Result> results = transaction.scan(scan);
注記

非 JDBC データベースを使用する場合、クロスパーティション Scan で順序を指定することはできません。フィルタリングまたは順序付けを指定したクロスパーティション Scan の使用方法の詳細については、フィルタリングと順序付けを使用してパーティション間の Scan を実行するを参照してください。

フィルタリングと順序付けを使用してパーティション間の Scan を実行する​

次のようにフィルタリングと順序付けによるクロスパーティションスキャンオプションを有効にすると、柔軟な条件と順序付けでクロスパーティション Scan 操作を実行できます。

scalar.db.cross_partition_scan.enabled=true
scalar.db.cross_partition_scan.filtering.enabled=true
scalar.db.cross_partition_scan.ordering.enabled=true
注記

非 JDBC データベースでは scalar.db.cross_partition_scan.ordering を有効にすることはできません。

次のように、all() メソッドを呼び出した後に where() メソッドと orderings() メソッドを呼び出して、任意の条件と順序を指定できます。

// Create a `Scan` operation with arbitrary conditions and orderings.
Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .all()
        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
        .projections("c1", "c2", "c3", "c4")
        .orderings(Scan.Ordering.desc("c3"), Scan.Ordering.asc("c4"))
        .limit(10)
        .build();

// Execute the `Scan` operation.
List<Result> results = transaction.scan(scan);

WHERE 句の詳細については、WHERE 句を使用するを参照してください。

操作単位でクロスパーティションスキャンを有効にする​

上記の設定でクロスパーティションスキャンを全体的に有効にする代わりに、オペレーションにクロスパーティションスキャン属性を設定することで、特定のオペレーションに対して有効にできます。オペレーションに設定した場合、そのオペレーションについては対応する設定値よりも属性が優先されます。

次の例では、特定のオペレーションに対してクロスパーティションスキャン、フィルタリング、および順序付けを有効にしています。

// Enable cross-partition scan for this specific `Scan` operation.
Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .all()
        .where(ConditionBuilder.column("c1").isNotEqualToInt(10))
        .orderings(Scan.Ordering.asc("c3"))
        .attribute(DatabaseOperationAttributes.CROSS_PARTITION_SCAN_ENABLED, "true")
        .attribute(DatabaseOperationAttributes.CROSS_PARTITION_SCAN_FILTERING_ENABLED, "true")
        .attribute(DatabaseOperationAttributes.CROSS_PARTITION_SCAN_ORDERING_ENABLED, "true")
        .build();

これらの属性の詳細については、クロスパーティションスキャン属性を参照してください。

Put 操作​
注記

Put 操作は ScalarDB 3.13以降では非推奨となり、将来のリリースでは削除される予定です。Put 操作の代わりに、Insert 操作、Upsert 操作、または Update 操作を使用してください。

Put は、主キーで指定されたレコードを配置する操作です。この操作はレコードの upsert 操作として動作し、レコードが存在する場合はレコードを更新し、レコードが存在しない場合はレコードを挿入します。

注記

既存のレコードを更新する場合、Put 操作を使用する前に Get または Scan を使用してレコードを読み取る必要があります。そうしないと、競合により操作が失敗します。これは、トランザクションを適切に管理するための ScalarDB の仕様により発生します。レコードを明示的に読み取る代わりに、暗黙的な事前読み取りを有効にできます。詳細については、Put 操作の暗黙的な事前読み取りを有効にするを参照してください。

まず Put オブジェクトを作成し、次に以下のように transaction.put() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Put` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Put` operation.
transaction.put(put);

次のように null 値を持つレコードを配置することもできます。

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", null)
        .doubleValue("c5", null)
        .build();
Put 操作の暗黙的な事前読み取りを有効にする​

Consensus Commit では、レコードが存在する場合、レコードの最新の状態を取得するために、アプリケーションは Put および Delete 操作でレコードを変更する前にレコードを読み取る必要があります。レコードを明示的に読み取る代わりに、暗黙的な事前読み取り を有効にすることができます。暗黙的な事前読み取りを有効にすると、アプリケーションがトランザクションでレコードを明示的に読み取らない場合は、ScalarDB がトランザクションをコミットする前にアプリケーションに代わってレコードを読み取ります。

Put 操作の暗黙的な事前読み取りを有効にするには、次のように Put 操作ビルダーで enableImplicitPreRead() を指定します。

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .enableImplicitPreRead()
        .build();
注記

変更しようとしているレコードが存在しないことが確実な場合は、パフォーマンスを向上させるために、Put 操作の暗黙的な事前読み取りを有効にしないでください。たとえば、初期データをロードする場合は、暗黙的な事前読み取りを有効にしないでください。暗黙的な事前読み取りのない Put 操作は、暗黙的な事前読み取りのある Put 操作よりも高速です。これは、操作によって不要な読み取りがスキップされるためです。

Insert 操作​

Insert は、トランザクションを通じて基礎となるストレージにエントリを挿入する操作です。エントリがすでに存在する場合は、競合エラーが発生します。

まず Insert オブジェクトを作成し、次に以下のように transaction.insert() メソッドを使用してオブジェクトを実行する必要があります。

// Create an `Insert` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Insert insert =
    Insert.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Insert` operation.
transaction.insert(insert);
Upsert 操作​

Upsert は、トランザクションを通じて基礎となるストレージにエントリを挿入したり、エントリを更新したりする操作です。エントリがすでに存在する場合は更新され、そうでない場合はエントリが挿入されます。

まず Upsert オブジェクトを作成し、次に以下のように transaction.upsert() メソッドを使用してオブジェクトを実行する必要があります。

// Create an `Upsert` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Upsert upsert =
    Upsert.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Upsert` operation.
transaction.upsert(upsert);
Update 操作​

Update は、トランザクションを通じて基礎となるストレージ内のエントリを更新する操作です。エントリが存在しない場合、操作によって変更は行われません。

まず Update オブジェクトを作成し、次に以下のように transaction.update() メソッドを使用してオブジェクトを実行する必要があります。

// Create an `Update` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Update update =
    Update.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Update` operation.
transaction.update(update);
Delete 操作​

Delete は、主キーで指定されたレコードを削除する操作です。

注記

レコードを削除する場合、Delete 操作では暗黙的な事前読み取りが常に有効になっているため、事前にレコードを読み取る必要はありません。

まず Delete オブジェクトを作成し、次に以下のように transaction.delete() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Delete` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .build();

// Execute the `Delete` operation.
transaction.delete(delete);
条件付きの Put、Delete、Update​

トランザクション内で条件をチェックするロジックを実装することで、コミット前にトランザクションが満たす必要のある任意の条件 (たとえば、銀行口座の残高が0以上である必要がある) を記述できます。または、Put、Delete、Update などのミューテーション操作で単純な条件を記述することもできます。

Put、Delete、Update 操作に条件が含まれている場合、指定された条件が満たされた場合にのみ操作が実行されます。操作の実行時に条件が満たされていない場合は、UnsatisfiedConditionException という例外がスローされます。

注記

Put 操作で条件を指定する場合は、事前にレコードを読み取るか、暗黙的な事前読み取りを有効にする必要があります。

Put の条件​

Put 操作では、次のように条件を指定できます。

// Build a condition.
MutationCondition condition =
    ConditionBuilder.putIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F))
        .and(ConditionBuilder.column("c5").isEqualToDouble(0.0))
        .build();

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .condition(condition) // condition
        .build();

// Execute the `Put` operation.
transaction.put(put);

putIf 条件を使用するだけでなく、次のように putIfExists 条件と putIfNotExists 条件を指定することもできます。

// Build a `putIfExists` condition.
MutationCondition putIfExistsCondition = ConditionBuilder.putIfExists();

// Build a `putIfNotExists` condition.
MutationCondition putIfNotExistsCondition = ConditionBuilder.putIfNotExists();
Delete の条件​

Delete 操作では、次のように条件を指定できます。

// Build a condition.
MutationCondition condition =
    ConditionBuilder.deleteIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F))
        .and(ConditionBuilder.column("c5").isEqualToDouble(0.0))
        .build();

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .condition(condition) // condition
        .build();

// Execute the `Delete` operation.
transaction.delete(delete);

deleteIf 条件を使用するだけでなく、次のように deleteIfExists 条件を指定することもできます。

// Build a `deleteIfExists` condition.
MutationCondition deleteIfExistsCondition = ConditionBuilder.deleteIfExists();
Update の条件​

Update 操作では、次のように条件を指定できます。

// Build a condition.
MutationCondition condition =
    ConditionBuilder.updateIf(ConditionBuilder.column("c4").isEqualToFloat(0.0F))
        .and(ConditionBuilder.column("c5").isEqualToDouble(0.0))
        .build();

Update update =
    Update.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .condition(condition) // condition
        .build();

// Execute the `Update` operation.
transaction.update(update);

updateIf 条件を使用するだけでなく、次のように updateIfExists 条件を指定することもできます。

// Build a `updateIfExists` condition.
MutationCondition updateIfExistsCondition = ConditionBuilder.updateIfExists();
Mutate 操作​

Mutate は、Put、Insert、Upsert、Update、Delete の複数のミューテーションを実行する操作です。

まずミューテーションオブジェクトを作成し、次に以下のように transaction.mutate() メソッドを使用してミューテーションを実行する必要があります。

// Create `Put` and `Delete` operations.
Key partitionKey = Key.ofInt("c1", 10);

Key clusteringKeyForPut = Key.of("c2", "aaa", "c3", 100L);

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForPut)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

Key clusteringKeyForDelete = Key.of("c2", "bbb", "c3", 200L);

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForDelete)
        .build();

// Execute the mutations.
transaction.mutate(Arrays.asList(put, delete));
Batch 操作​

Batch は、Get、Scan、Put、Insert、Upsert、Update、Delete の複数の操作を実行する操作です。

まず操作オブジェクトを作成し、次に以下のように transaction.batch() メソッドを使用して操作を実行する必要があります。

// Create operation objects.
Key partitionKey = Key.ofInt("c1", 10);

Key clusteringKeyForGet = Key.of("c2", "aaa", "c3", 100L);

Get get =
    Get.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForGet)
        .build();

Scan scan = Scan.newBuilder().namespace("ns").table("tbl").partitionKey(partitionKey).build();

Key clusteringKeyForInsert = Key.of("c2", "bbb", "c3", 200L);

Insert insert =
    Insert.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForInsert)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

Key clusteringKeyForDelete = Key.of("c2", "ccc", "c3", 300L);

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForDelete)
        .build();

// Execute the operations.
List<BatchResult> batchResults = transaction.batch(Arrays.asList(get, scan, insert, delete));

Optional<Result> getResult = batchResults.get(0).getGetResult(); // Result of the get

...

List<Result> scanResult = batchResults.get(1).getScanResult(); // Result of the scan

...
CRUD 操作のデフォルト名前空間​

すべての CRUD 操作のデフォルト名前空間は、ScalarDB 設定のプロパティを使用して設定できます。

scalar.db.default_namespace_name=<NAMESPACE_NAME>

名前空間を指定しない操作では、設定されたデフォルトの名前空間が使用されます。

// This operation will target the default namespace.
Scan scanUsingDefaultNamespace =
    Scan.newBuilder()
        .table("tbl")
        .all()
        .build();
// This operation will target the "ns" namespace.
Scan scanUsingSpecifiedNamespace =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .all()
        .build();
オペレーション属性​

オペレーション属性は、オペレーションに関する追加情報を保持するためのキーと値のペアです。オペレーション属性は、オペレーションビルダーの attribute() メソッドや attributes() メソッドを使用して個々のオペレーションにオペレーションスコープの属性として設定するか、トランザクションの開始時にトランザクションスコープの属性として設定できます。トランザクションスコープの属性は、そのトランザクション内のすべてのオペレーションにマージされます。同じ属性が両方のレベルで設定されている場合は、オペレーションスコープの値がトランザクションスコープの値よりも優先されます。トランザクションスコープの属性の詳細については、属性を指定してトランザクションを開始またはスタートするを参照してください。

次の例は、個々のオペレーションにオペレーション属性を設定する方法を示しています。

// Set operation attributes in the `Get` operation.
Get get = Get.newBuilder()
    .namespace("ns")
    .table("tbl")
    .partitionKey(partitionKey)
    .clusteringKey(clusteringKey)
    .attribute("attribute1", "value1")
    .attributes(ImmutableMap.of("attribute2", "value2", "attribute3", "value3"))
    .build();

// Set operation attributes in the `Scan` operation.
Scan scan = Scan.newBuilder()
    .namespace("ns")
    .table("tbl")
    .partitionKey(partitionKey)
    .projections("c1", "c2", "c3", "c4")
    .attribute("attribute1", "value1")
    .attributes(ImmutableMap.of("attribute2", "value2", "attribute3", "value3"))
    .build();

// Set operation attributes in the `Insert` operation.
Insert insert = Insert.newBuilder()
    .namespace("ns")
    .table("tbl")
    .partitionKey(partitionKey)
    .clusteringKey(clusteringKey)
    .floatValue("c4", 1.23F)
    .doubleValue("c5", 4.56)
    .attribute("attribute1", "value1")
    .attributes(ImmutableMap.of("attribute2", "value2", "attribute3", "value3"))
    .build();

// Set operation attributes in the `Upsert` operation.
Upsert upsert = Upsert.newBuilder()
    .namespace("ns")
    .table("tbl")
    .partitionKey(partitionKey)
    .clusteringKey(clusteringKey)
    .floatValue("c4", 1.23F)
    .doubleValue("c5", 4.56)
    .attribute("attribute1", "value1")
    .attributes(ImmutableMap.of("attribute2", "value2", "attribute3", "value3"))
    .build();

// Set operation attributes in the `Update` operation.
Update update = Update.newBuilder()
    .namespace("ns")
    .table("tbl")
    .partitionKey(partitionKey)
    .clusteringKey(clusteringKey)
    .floatValue("c4", 1.23F)
    .doubleValue("c5", 4.56)
    .attribute("attribute1", "value1")
    .attributes(ImmutableMap.of("attribute2", "value2", "attribute3", "value3"))
    .build();

// Set operation attributes in the `Delete` operation.
Delete delete = Delete.newBuilder()
    .namespace("ns")
    .table("tbl")
    .partitionKey(partitionKey)
    .clusteringKey(clusteringKey)
    .attribute("attribute1", "value1")
    .attributes(ImmutableMap.of("attribute2", "value2", "attribute3", "value3"))
    .build();

次の属性が利用可能です。属性をサポートしていないオペレーションに属性を設定しても、効果はありません。

クロスパーティションスキャン属性​

次の属性は、クロスパーティション Scan 操作 (パーティションキーを指定しない Scan 操作) に適用されます。オペレーションに設定した場合、そのオペレーションについては対応する scalar.db.cross_partition_scan.* の設定値よりも優先されます。設定の詳細については、クロスパーティションスキャン設定を参照してください。

  • db-cross-partition-scan-enabled: オペレーションでクロスパーティションスキャンを有効にするかどうか。値は true または false である必要があります。
  • db-cross-partition-scan-filtering-enabled: オペレーションでフィルタリングを伴うクロスパーティションスキャンを有効にするかどうか。値は true または false である必要があります。
  • db-cross-partition-scan-ordering-enabled: オペレーションで順序付けを伴うクロスパーティションスキャンを有効にするかどうか。値は true または false である必要があります。この属性は JDBC データベースでのみ利用できます。

これらの属性を設定するには、DatabaseOperationAttributes ユーティリティクラスを使用できます。

Consensus Commit 属性​

次の属性は、Consensus Commit で実行されるトランザクションに適用されます。

  • cc-transaction-isolation: トランザクションの分離レベル。値は SNAPSHOT、SERIALIZABLE、または READ_COMMITTED である必要があります。設定すると、そのトランザクションについて設定済みのデフォルトの分離レベルを上書きします。分離レベルの詳細については、分離レベルを参照してください。
警告

他のオペレーション属性とは異なり、cc-transaction-isolation はトランザクション内のオペレーション単位で適用することはできません。この属性はトランザクションの開始時にのみ解釈されます。この属性を使用するには、属性を指定してトランザクションを開始またはスタートするときに指定するか、トランザクションを開始せずにトランザクションを実行する場合はオペレーションに設定してください。後者の場合、ScalarDB は暗黙的に開始するトランザクションにその値を使用します。

この属性を設定するには、ConsensusCommitOperationAttributes ユーティリティクラスを使用できます。

トランザクションをコミットする​

CRUD 操作を実行した後、トランザクションをコミットして終了する必要があります。

トランザクションは次のようにコミットできます。

// Commit a transaction.
transaction.commit();

トランザクションをロールバックまたはアボートする​

トランザクションの実行中にエラーが発生した場合は、トランザクションをロールバックまたはアボートできます。

トランザクションは次のようにロールバックできます。

// Roll back a transaction.
transaction.rollback();

または、次のようにトランザクションをアボートすることもできます。

// Abort a transaction.
transaction.abort();

ScalarDB で例外を処理する方法の詳細については、例外の処理方法を参照してください。

トランザクションを開始せずにトランザクションを実行する​

トランザクションを開始せずにトランザクション操作を実行できます。この場合、ScalarDB は操作を実行する前に自動的にトランザクションを開始し、操作の実行後にトランザクションをコミットします。このセクションでは、トランザクションを開始せずにトランザクションを実行する方法について説明します。

Get 操作を実行する​

Get は、主キーで指定された単一のレコードを取得する操作です。

最初に Get オブジェクトを作成し、次に以下のように transactionManager.get() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Get` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Get get =
    Get.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .projections("c1", "c2", "c3", "c4")
        .build();

// Execute the `Get` operation.
Optional<Result> result = transactionManager.get(get);

Get 操作の詳細については、Get 操作を参照してください。

Scan 操作の実行​

Scan は、パーティション内の複数のレコードを取得する操作です。Scan 操作では、クラスタリングキーの境界とクラスタリングキー列の順序を指定できます。Scan 操作を実行するには、transactionManager.scan() メソッドまたは transactionManager.getScanner() メソッドを使用できます。

  • transactionManager.scan():
    • このメソッドは、指定された Scan 操作を即座に実行し、一致するすべてのレコードのリストを返します。結果セットがメモリに収まる程度の小さい場合に適しています。
  • transactionManager.getScanner():
    • このメソッドは、結果セットを遅延的にイテレートできる Scanner オブジェクトを返します。結果セットが大きくなる可能性がある場合に有用で、すべてのレコードを一度にメモリに読み込むことを避けられます。

まず Scan オブジェクトを作成し、次に transactionManager.scan() メソッドまたは transactionManager.getScanner() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Scan` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key startClusteringKey = Key.of("c2", "aaa", "c3", 100L);
Key endClusteringKey = Key.of("c2", "aaa", "c3", 300L);

Scan scan =
    Scan.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .start(startClusteringKey, true)    // Include startClusteringKey
        .end(endClusteringKey, false)       // Exclude endClusteringKey
        .projections("c1", "c2", "c3", "c4")
        .orderings(Scan.Ordering.desc("c2"), Scan.Ordering.asc("c3"))
        .limit(10)
        .build();

// Execute the `Scan` operation by using the `transactionManager.scan()` method.
List<Result> results = transactionManager.scan(scan);

// Or, execute the `Scan` operation by using the `transactionManager.getScanner()` method.
try (TransactionManagerCrudOperable.Scanner scanner = transactionManager.getScanner(scan)) {
  // Fetch the next result from the scanner
  Optional<Result> result = scanner.one();

  // Fetch all remaining results from the scanner
  List<Result> allResults = scanner.all();
}

Scan 操作の詳細については、Scan 操作を参照してください。

Put 操作を実行します​

注記

Put 操作は ScalarDB 3.13以降では非推奨となり、将来のリリースでは削除される予定です。Put 操作の代わりに、Insert 操作、Upsert 操作、または Update 操作を使用してください。

まず Put オブジェクトを作成し、次に以下のように transactionManager.put() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Put` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Put` operation.
transactionManager.put(put);

Put 操作の詳細については、Put 操作を参照してください。

Insert 操作の実行​

Insert は、トランザクションを通じて基礎となるストレージにエントリを挿入する操作です。エントリがすでに存在する場合は、競合エラーが発生します。

まず Insert オブジェクトを作成し、次に以下のように transactionManager.insert() メソッドを使用してオブジェクトを実行する必要があります。

// Create an `Insert` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Insert insert =
    Insert.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Insert` operation.
transactionManager.insert(insert);

Insert 操作の詳細については、Insert 操作を参照してください。

Upsert 操作を実行する​

Upsert は、トランザクションを通じて基礎となるストレージにエントリを挿入するか、エントリを更新する操作です。エントリがすでに存在する場合は更新され、そうでない場合はエントリが挿入されます。

まず Upsert オブジェクトを作成し、次に以下のように transactionManager.upsert() メソッドを使用してオブジェクトを実行する必要があります。

// Create an `Upsert` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Upsert upsert =
    Upsert.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Upsert` operation.
transactionManager.upsert(upsert);

Upsert 操作の詳細については、Upsert 操作を参照してください。

Update 操作の実行​

Update は、トランザクションを通じて基礎となるストレージ内のエントリを更新する操作です。エントリが存在しない場合、操作によって変更は行われません。

まず Update オブジェクトを作成し、次に以下のように transactionManager.update() メソッドを使用してオブジェクトを実行する必要があります。

// Create an `Update` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Update update =
    Update.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

// Execute the `Update` operation.
transactionManager.update(update);

Update 操作の詳細については、Update 操作を参照してください。

Delete 操作を実行する​

Delete は、主キーで指定されたレコードを削除する操作です。

まず Delete オブジェクトを作成し、次に以下のように transactionManager.delete() メソッドを使用してオブジェクトを実行する必要があります。

// Create a `Delete` operation.
Key partitionKey = Key.ofInt("c1", 10);
Key clusteringKey = Key.of("c2", "aaa", "c3", 100L);

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKey)
        .build();

// Execute the `Delete` operation.
transactionManager.delete(delete);

Delete 操作の詳細については、Delete 操作を参照してください。

Mutate 操作の実行​

Mutate は、複数のミューテーション (Put、Insert、Upsert、Update、および Delete 操作) を実行する操作です。

まずミューテーションオブジェクトを作成し、次に以下のように transactionManager.mutate() メソッドを使用してミューテーションを実行する必要があります。

// Create `Put` and `Delete` operations.
Key partitionKey = Key.ofInt("c1", 10);

Key clusteringKeyForPut = Key.of("c2", "aaa", "c3", 100L);

Put put =
    Put.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForPut)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

Key clusteringKeyForDelete = Key.of("c2", "bbb", "c3", 200L);

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForDelete)
        .build();

// Execute the mutations.
transactionManager.mutate(Arrays.asList(put, delete));

Mutate 操作の詳細については、Mutate 操作を参照してください。

また、ScalarDB での例外の処理方法の詳細については、例外の処理方法を参照してください。

Batch 操作の実行​

Batch は、Get、Scan、Put、Insert、Upsert、Update、Delete の複数の操作を実行する操作です。

まず操作オブジェクトを作成し、次に以下のように transactionManager.batch() メソッドを使用して操作を実行する必要があります。

// Create operation objects.
Key partitionKey = Key.ofInt("c1", 10);

Key clusteringKeyForGet = Key.of("c2", "aaa", "c3", 100L);

Get get =
    Get.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForGet)
        .build();

Scan scan = Scan.newBuilder().namespace("ns").table("tbl").partitionKey(partitionKey).build();

Key clusteringKeyForInsert = Key.of("c2", "bbb", "c3", 200L);

Insert insert =
    Insert.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForInsert)
        .floatValue("c4", 1.23F)
        .doubleValue("c5", 4.56)
        .build();

Key clusteringKeyForDelete = Key.of("c2", "ccc", "c3", 300L);

Delete delete =
    Delete.newBuilder()
        .namespace("ns")
        .table("tbl")
        .partitionKey(partitionKey)
        .clusteringKey(clusteringKeyForDelete)
        .build();

// Execute the operations.
List<BatchResult> batchResults = transactionManager.batch(Arrays.asList(get, scan, insert, delete));

Optional<Result> getResult = batchResults.get(0).getGetResult(); // Result of the get

...

List<Result> scanResult = batchResults.get(1).getScanResult(); // Result of the scan

...

Batch 操作の詳細については、Batch 操作を参照してください。

Microservice Transaction API​

このセクションでは、ScalarDB の Microservice Transaction API を使用して複数のプロセスにまたがるトランザクションを実行する方法について説明します。この API は、GlobalTransactionManager、GlobalTransaction、および BranchTransaction インターフェースで構成されています。

グローバルトランザクションは、1つ以上のブランチから構成される単一のトランザクションです。各ブランチは独自のプロセス (例: マイクロサービスごとに1つのプロセス) で実行され、独自のデータに対して CRUD 操作を実行します。トランザクションは1回だけ開始され、各ブランチはトランザクション ID を使用してそれに参加し、その後トランザクション全体としてコミットまたはロールバックされます。これにより、すべてのブランチの作業が一緒に反映されるか、まったく反映されないかのどちらかになります。

グローバルトランザクションには2種類のハンドルがあります:

  • GlobalTransaction: トランザクションの結果を制御する全体的なハンドルです。このハンドルは CRUD 操作を実行しません。
  • BranchTransaction: トランザクションの1つのブランチのハンドルで、そのブランチの CRUD 操作を実行します。

詳細については、Javadoc の GlobalTransactionManager、GlobalTransaction、および BranchTransaction ページを参照してください。

GlobalTransactionManager インスタンスの取得​

グローバルトランザクションを実行するには、まず GlobalTransactionManager インスタンスを取得する必要があります。グローバルトランザクションに参加するすべてのプロセスは、独自のインスタンスが必要です。

GlobalTransactionManager インスタンスを取得するには、次のように TransactionFactory を使用します:

TransactionFactory transactionFactory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
GlobalTransactionManager transactionManager = transactionFactory.getGlobalTransactionManager();

すべてのグローバルトランザクションを実行した後は、次のように GlobalTransactionManager インスタンスをクローズする必要があります:

transactionManager.close();

グローバルトランザクションの実行​

このサブセクションでは、グローバルトランザクションの実行方法について説明します。1つのプロセスがトランザクションを開始し、各プロセスが独自のブランチを開始して CRUD 操作を実行し、各ブランチが終了されてから、トランザクションを開始したプロセスがコミットまたはロールバックします。

グローバルトランザクションの開始​

グローバルトランザクションを開始するのは1つのプロセスだけで、そのプロセスが後でコミットまたはロールバックします。他のプロセスは自分のブランチのみを開始します。

次のようにグローバルトランザクションを開始できます:

// Begin a global transaction.
GlobalTransaction globalTransaction = transactionManager.begin();

または、次のようにグローバルトランザクションをスタートすることもできます:

// Start a global transaction.
GlobalTransaction globalTransaction = transactionManager.start();

ScalarDB がトランザクション ID を生成します。すべてのブランチがその ID を必要とするため、getId() を使用して読み取り、他のプロセスに渡す必要があります:

// Get the ID of the global transaction.
String transactionId = globalTransaction.getId();
読み取り専用モードでグローバルトランザクションを開始する​

読み取り専用モードでグローバルトランザクションを開始することもできます。この場合、トランザクションでは書き込み操作は許可されず、ScalarDB がそれを読み取り操作に最適化する可能性があります。

注記

パフォーマンスを向上させ、リソース使用量を削減するために、読み取り専用操作には読み取り専用トランザクションを使用することを強く推奨します。

次のように読み取り専用モードでグローバルトランザクションを開始またはスタートできます:

// Begin a global transaction in read-only mode.
GlobalTransaction globalTransaction = transactionManager.beginReadOnly();
// Start a global transaction in read-only mode.
GlobalTransaction globalTransaction = transactionManager.startReadOnly();
属性を指定してグローバルトランザクションを開始する​

グローバルトランザクションを開始するときに、トランザクションスコープの属性のマップを指定できます。指定した属性はトランザクション内で発行されるすべての操作にマージされるため、トランザクション全体に一律に適用する設定を開始時に一度だけ指定できます。操作にすでに同じ属性キーが設定されている場合は、操作側の属性が優先されます。

次のように属性を指定してグローバルトランザクションを開始またはスタートできます:

// Specify attributes for the global transaction.
Map<String, String> attributes = ...;

// Begin a global transaction with attributes.
GlobalTransaction globalTransaction = transactionManager.begin(attributes);
// Start a global transaction with attributes.
GlobalTransaction globalTransaction = transactionManager.start(attributes);

beginReadOnly および startReadOnly メソッドにも、属性を受け取るオーバーロードがあります:

// Begin a global transaction in read-only mode with attributes.
GlobalTransaction globalTransaction = transactionManager.beginReadOnly(attributes);
// Start a global transaction in read-only mode with attributes.
GlobalTransaction globalTransaction = transactionManager.startReadOnly(attributes);

使用可能な属性のリストについては、オペレーション属性を参照してください。

ブランチの開始​

グローバルトランザクションで CRUD 操作を実行する各プロセスは、グローバルトランザクションの ID を指定して独自のブランチを開始します。

次のようにブランチを開始できます:

// Begin a branch of the global transaction.
BranchTransaction branch = transactionManager.beginBranch("<TRANSACTION_ID>");

または、次のようにブランチをスタートすることもできます:

// Start a branch of the global transaction.
BranchTransaction branch = transactionManager.startBranch("<TRANSACTION_ID>");
注記

グローバルトランザクションを開始したプロセスも CRUD 操作を実行する場合は、ブランチを開始する必要があります。GlobalTransaction ハンドルは CRUD 操作を実行しないためです。

ブランチが属するグローバルトランザクションの ID を取得するには、次のように getId() を使用します:

// Get the ID of the global transaction that this branch belongs to.
String transactionId = branch.getId();
属性を指定してブランチを開始する​

ブランチを開始するときに、ブランチスコープの属性のマップを指定できます。指定した属性はそのブランチで発行されるすべての操作に付与されます。操作にすでに同じ属性キーが設定されている場合は、操作側の属性が優先されます。同様に、グローバルトランザクションに同じ属性キーが指定されている場合は、ブランチレベルの属性が優先されます。つまり、より狭いスコープが常に優先されます。

次のように属性を指定してブランチを開始またはスタートできます:

// Specify attributes for the branch.
Map<String, String> attributes = ...;

// Begin a branch with attributes.
BranchTransaction branch = transactionManager.beginBranch("<TRANSACTION_ID>", attributes);
// Start a branch with attributes.
BranchTransaction branch = transactionManager.startBranch("<TRANSACTION_ID>", attributes);

使用可能な属性のリストについては、オペレーション属性を参照してください。

ブランチでの CRUD 操作の実装​

BranchTransaction の CRUD 操作は、DistributedTransaction の操作と同じです。詳細については、CRUD 操作を実装するを参照してください。

ブランチを終了する前に、ブランチから取得したすべての Scanner オブジェクトをクローズしてください。詳細については、ブランチの終了を参照してください。

ブランチの終了​

ブランチが最後の CRUD 操作を実行した後、ブランチを終了して作業の結果を宣言する必要があります。ブランチを終了してもトランザクションはコミットされません。結果はグローバルトランザクションによって制御されます。

ブランチの作業が成功した場合は、次のようにブランチを終了できます:

// End the branch, declaring that its work succeeded.
branch.end(BranchTransaction.Status.SUCCESS);

ブランチの作業が失敗した場合は、次のようにブランチを終了できます:

// End the branch, declaring that its work failed.
branch.end(BranchTransaction.Status.FAILURE);
警告

ブランチを終了するときは、次の点に注意してください:

  • ブランチを実行するプロセスは、成功パスと失敗パスの両方で、ブランチをちょうど1回終了する必要があります。トランザクションの結果も制御するプロセスも例外ではありません。コミットまたはロールバックは、同じ GlobalTransactionManager インスタンスが開始したブランチにのみ反映されるためです。
  • BranchTransaction.Status.SUCCESS は、すでに終了したブランチを拒否し、ブランチから取得したすべての Scanner オブジェクトがクローズされていることを要求します。そうでない場合、ブランチの終了は IllegalStateException をスローします。
  • BranchTransaction.Status.FAILURE は、catch 句から呼び出せるよう寛容です。すでに終了したブランチを終了しても何もしません。また、開いている Scanner オブジェクトも許可されます。
  • ブランチから取得したすべての Scanner オブジェクトを、ブランチを終了する前にクローズしてください。ブランチを終了した後にクローズしないでください。try-with-resources 文を使用する場合、Scanner オブジェクトはブロックが終了したときにのみクローズされるため、ブランチはその後に終了する必要があります。開いたままの Scanner オブジェクトは、トランザクションがロールバックされるときにクローズされます。
  • すでに終了したブランチに対して CRUD 操作を実行すると、宣言した結果に関わらず IllegalStateException をスローします。

グローバルトランザクションのコミット​

すべてのブランチが終了した後、グローバルトランザクションを開始したプロセスがトランザクションをコミットして、すべてのブランチの書き込みを全体として永続化します。

次のようにグローバルトランザクションをコミットできます:

// Commit a global transaction.
globalTransaction.commit();
警告

すべてのブランチが BranchTransaction.Status.SUCCESS で終了した後にのみ、グローバルトランザクションをコミットしてください。ブランチが BranchTransaction.Status.FAILURE で終了した場合は、代わりにトランザクションをロールバックしてください。

ScalarDB はこのルールの違反を検出しません。ブランチが BranchTransaction.Status.FAILURE で終了した後にコミットしてもエラーは発生しません。また、ブランチがまだ作業中の状態でコミットすると、そのブランチの部分的な作業がコミットされる可能性があります。コミットはそれまでにステージングされた書き込みで進行し、後から到着した操作はすでに進行中のコミットを停止させることなく拒否されます。

グローバルトランザクションのロールバックまたはアボート​

グローバルトランザクションの実行中にエラーが発生した場合、トランザクションをロールバックまたはアボートできます。これにより、すべてのブランチの書き込みが破棄されます。ただし、ブランチは終了されません。ブランチを開始した各プロセスは、BranchTransaction.Status.FAILURE でブランチを終了する必要があります。

次のようにグローバルトランザクションをロールバックできます:

// Roll back a global transaction.
globalTransaction.rollback();

または、次のようにグローバルトランザクションをアボートすることもできます:

// Abort a global transaction.
globalTransaction.abort();

ScalarDB での例外の処理方法の詳細については、例外の処理方法を参照してください。

複数のプロセスにまたがるグローバルトランザクションの実行​

このサブセクションでは、グローバルトランザクションが2つのプロセスにまたがる場合に各要素を組み合わせる方法を示します。

最初のプロセスはグローバルトランザクションを開始し、独自のブランチで作業を行い、トランザクション ID を2番目のプロセスに渡し、その後トランザクションをコミットします:

// In a method that declares throws TransactionException (or wider).
TransactionFactory transactionFactory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
GlobalTransactionManager transactionManager = transactionFactory.getGlobalTransactionManager();

// Begin a global transaction.
GlobalTransaction globalTransaction = transactionManager.begin();

BranchTransaction branch = null;
try {
  // Execute CRUD operations in this process's own branch, and then end the branch.
  branch = transactionManager.beginBranch(globalTransaction.getId());
  Optional<Result> result = branch.get(...);
  branch.insert(...);
  branch.end(BranchTransaction.Status.SUCCESS);

  // Pass the transaction ID to the second process, for example, in an RPC call, and wait until
  // its branch has executed its CRUD operations and has been ended.
  callSecondProcess(globalTransaction.getId());

  // Commit the global transaction as a whole.
  globalTransaction.commit();
} catch (UnknownTransactionStatusException e) {
  // The status of the global transaction, whether it was committed or not, is unknown. Check
  // whether it was committed before deciding how to proceed, and do not roll it back blindly.
} catch (Exception e) {
  // End this process's own branch, declaring that its work failed.
  if (branch != null) {
    try {
      branch.end(BranchTransaction.Status.FAILURE);
    } catch (CrudException ex) {
      // Ending the branch failed. The global transaction is rolled back below, so you don't need
      // to do anything further. You can simply log the occurrence here.
    }
  }

  // Roll back the global transaction, which discards the writes of all its branches.
  try {
    globalTransaction.rollback();
  } catch (RollbackException ex) {
    // Rolling back the global transaction failed. Since the transaction should eventually recover,
    // you don't need to do anything further. You can simply log the occurrence here.
  }
}

2番目のプロセスは、受信したトランザクション ID を使用してブランチを開始し、CRUD 操作のみを実行します。コミットとロールバックは最初のプロセスに委ねられます:

// In a method that declares throws TransactionException (or wider).
TransactionFactory transactionFactory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
GlobalTransactionManager transactionManager = transactionFactory.getGlobalTransactionManager();

// Begin a branch of the global transaction by using the transaction ID that was received.
BranchTransaction branch = transactionManager.beginBranch(transactionId);

try {
  // Execute CRUD operations in the branch, and then end the branch.
  Optional<Result> result = branch.get(...);
  branch.insert(...);
  branch.end(BranchTransaction.Status.SUCCESS);
} catch (Exception e) {
  // End the branch, declaring that its work failed.
  try {
    branch.end(BranchTransaction.Status.FAILURE);
  } catch (CrudException ex) {
    // Ending the branch failed. The process that began the global transaction rolls it back, so
    // you don't need to do anything further. You can simply log the occurrence here.
  }

  throw e;
}

// Return to the caller, which commits or rolls back the global transaction.

ブランチの CRUD 操作が失敗した場合は、BranchTransaction.Status.FAILURE でブランチを終了し、例外をグローバルトランザクションを開始したプロセスに伝播させて、そのプロセスがトランザクションをロールバックできるようにしてください。

例外の処理方法​

トランザクションを実行するときは、例外も適切に処理する必要があります。

警告

例外を適切に処理しないと、異常やデータの不整合が発生する可能性があります。

例外​

このセクションでは、このガイドで説明する API がスローする可能性のある各例外と、その例外が示す内容について説明します。

TransactionException および TransactionNotFoundException​

begin()、beginReadOnly()、および beginBranch() API は TransactionException または TransactionNotFoundException をスローする可能性があります:

  • TransactionException をキャッチした場合、この例外は、一時的または非一時的障害が原因でトランザクションを開始できなかったことを示します。トランザクションを再試行することはできますが、非一時的障害が原因でトランザクションを開始できない可能性があります。
  • TransactionNotFoundException をキャッチした場合、この例外は、一時的障害が原因でトランザクションを開始できなかったことを示します。この場合、トランザクションを再試行できます。

start()、startReadOnly()、および startBranch() メソッドは、それぞれ begin()、beginReadOnly()、および beginBranch() のエイリアスであるため、エイリアス元のメソッドと同じ例外をスローします。

CrudException および CrudConflictException​

CRUD 操作の API (get()、scan()、put()、delete()、および mutate()) は、CrudException または CrudConflictException をスローする可能性があります:

  • CrudException をキャッチした場合、この例外は、一時的または非一時的障害が原因でトランザクション CRUD 操作が失敗したことを示します。トランザクションを最初から再試行できますが、原因が非一時的である場合は、トランザクションが失敗する可能性があります。
  • CrudConflictException をキャッチした場合、この例外は、一時的な障害 (競合エラーなど) が原因でトランザクション CRUD 操作が失敗したことを示します。この場合、トランザクションを最初から再試行できます。

end(Status) API もこれらの例外をスローする可能性があります。CRUD 操作の例外と同じ方法で処理できます。

UnsatisfiedConditionException​

ミューテーション操作の API (put()、delete()、および mutate()) も UnsatisfiedConditionException をスローする可能性があります。

UnsatisfiedConditionException をキャッチした場合、この例外はミューテーション操作の条件が満たされていないことを示します。この例外は、アプリケーションの要件に従って処理できます。

CommitException、CommitConflictException、および UnknownTransactionStatusException​

commit() API は CommitException、CommitConflictException、または UnknownTransactionStatusException をスローする可能性があります:

  • CommitException をキャッチした場合、この例外は、一時的または非一時的障害が原因でトランザクションのコミットが失敗したことを示します。トランザクションを最初から再試行できますが、原因が非一時的である場合はトランザクションが失敗する可能性があります。
  • CommitConflictException をキャッチした場合、この例外は、一時的な障害 (競合エラーなど) が原因でトランザクションのコミットが失敗したことを示します。この場合、トランザクションを最初から再試行できます。
  • UnknownTransactionStatusException をキャッチした場合、この例外は、トランザクションのステータス (成功したかどうか) が不明であることを示します。この場合、トランザクションが正常にコミットされたかどうかを確認し、失敗した場合はトランザクションを再試行する必要があります。

トランザクションステータスを識別する方法は、ユーザーに委任されています。トランザクションステータステーブルを作成し、他のアプリケーションデータとアトミックに更新すると、ステータステーブルからトランザクションのステータスを取得できるようにすることができます。

RollbackException および AbortException​

rollback() API は RollbackException をスローする可能性があり、rollback() のエイリアスである abort() API は AbortException をスローする可能性があります。どちらの例外も、トランザクションのロールバックが一時的または非一時的障害により失敗したことを示します。

どちらの例外をキャッチした場合も、トランザクションは最終的に回復するため、これ以上何もする必要はありません。発生したことをログに記録するだけでよいです。

認証と認可の例外​

認証と認可が有効になっている場合、現在のユーザーが認証されていないか、必要な権限を持っていないために操作が失敗することがあります。Administrative API、Transaction API、および Microservice Transaction API はすべて、次の4つの共通のメソッドを通じてこのような失敗を報告します:

  • isAuthenticationError() は、現在のユーザーが認証されていない場合に true を返します。
  • isAuthorizationError() は、現在のユーザーが必要な権限を持っていない場合に true を返します。
  • isSuperuserRequired() は、操作にスーパーユーザー権限が必要な場合に true を返します。
  • getRequiredPrivilege() は、権限不足が原因で失敗した場合に、その操作に必要な権限を返します。

Administrative API では、これらのメソッドは ExecutionException にあります。Transaction API と Microservice Transaction API では、TransactionException およびそのサブクラスにあります。たとえば、現在のユーザーがテーブルに対する READ 権限を持っていない場合、get() は CrudException をスローし、この例外に対して isAuthorizationError() は true を返します。

認証と認可のステータスコードの詳細については、認証および認可エラーコードを参照してください。

例​

以下の例では、UnknownTransactionStatusException の場合、重複操作の可能性を回避するためにアプリケーションがトランザクションが成功したかどうかを確認する必要があるため、トランザクションは再試行されません。その他の例外の場合、例外の原因が一時的または非一時的であるため、トランザクションは再試行されます。例外の原因が一時的な場合、再試行するとトランザクションが成功する可能性があります。ただし、例外の原因が非一時的である場合、再試行してもトランザクションは失敗します。このような場合、再試行回数を使い果たします。

注記

以下の例では、トランザクションは最大3回試行され、再試行ごとに100ミリ秒間スリープします。ただし、アプリケーションの要件に応じて、指数バックオフなどの再試行ポリシーを選択できます。

Transaction API の例​

次のサンプルコードは、例外を処理する方法を示しています。

public class Sample {
  public static void main(String[] args) throws Exception {
    TransactionFactory factory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
    DistributedTransactionManager transactionManager = factory.getTransactionManager();

    int retryCount = 0;
    TransactionException lastException = null;

    while (true) {
      if (retryCount++ > 0) {
        // Attempt the transaction three times maximum.
        if (retryCount > 3) {
          // Throw the last exception if the number of retries exceeds the maximum.
          throw lastException;
        }

        // Sleep 100 milliseconds before retrying the transaction.
        TimeUnit.MILLISECONDS.sleep(100);
      }

      DistributedTransaction transaction = null;
      try {
        // Begin a transaction.
        transaction = transactionManager.begin();

        // Execute CRUD operations in the transaction.
        Optional<Result> result = transaction.get(...);
        List<Result> results = transaction.scan(...);
        transaction.insert(...);
        transaction.delete(...);

        // Commit the transaction.
        transaction.commit();
      } catch (UnsatisfiedConditionException e) {
        // You need to handle `UnsatisfiedConditionException` only if a mutation operation specifies a condition.
        // This exception indicates the condition for the mutation operation is not met.

        try {
          transaction.rollback();
        } catch (RollbackException ex) {
          // Rolling back the transaction failed. Since the transaction should eventually recover, 
          // you don't need to do anything further. You can simply log the occurrence here.
        }

        // You can handle the exception here, according to your application requirements.

        return;
      } catch (UnknownTransactionStatusException e) {
        // If you catch `UnknownTransactionStatusException` when committing the transaction, 
        // it indicates that the status of the transaction, whether it was successful or not, is unknown.
        // In such a case, you need to check if the transaction is committed successfully or not and 
        // retry the transaction if it failed. How to identify a transaction status is delegated to users.
        return;
      } catch (TransactionException e) {
        // For other exceptions, you can retry the transaction.

        // For `CrudConflictException`, `CommitConflictException`, and `TransactionNotFoundException`,
        // you can basically retry the transaction. However, for the other exceptions, the transaction
        // will still fail if the cause of the exception is non-transient. In such a case, you will 
        // exhaust the number of retries and throw the last exception.

        if (transaction != null) {
          try {
            transaction.rollback();
          } catch (RollbackException ex) {
            // Rolling back the transaction failed. The transaction should eventually recover,
            // so you don't need to do anything further. You can simply log the occurrence here.
          }
        }

        lastException = e;
      }
    }
  }
}

Microservice Transaction API の例​

次のサンプルコードは、グローバルトランザクションを実行するときに例外を処理する方法を示しています。トランザクションの結果は GlobalTransaction ハンドルによって制御されるため、トランザクションはブランチではなくそのハンドルを通じてロールバックされます:

public class Sample {
  public static void main(String[] args) throws Exception {
    TransactionFactory factory = TransactionFactory.create("<CONFIGURATION_FILE_PATH>");
    GlobalTransactionManager transactionManager = factory.getGlobalTransactionManager();

    int retryCount = 0;
    TransactionException lastException = null;

    while (true) {
      if (retryCount++ > 0) {
        // Attempt the transaction three times maximum.
        if (retryCount > 3) {
          // Throw the last exception if the number of retries exceeds the maximum.
          throw lastException;
        }

        // Sleep 100 milliseconds before retrying the transaction.
        TimeUnit.MILLISECONDS.sleep(100);
      }

      GlobalTransaction globalTransaction = null;
      BranchTransaction branch = null;
      try {
        // Begin a global transaction.
        globalTransaction = transactionManager.begin();

        // Execute CRUD operations in this process's own branch, and then end the branch.
        branch = transactionManager.beginBranch(globalTransaction.getId());
        Optional<Result> result = branch.get(...);
        branch.insert(...);
        branch.delete(...);
        branch.end(BranchTransaction.Status.SUCCESS);

        // Let the other processes execute CRUD operations in their own branches and end them.
        callOtherProcesses(globalTransaction.getId());

        // Commit the global transaction.
        globalTransaction.commit();
      } catch (UnsatisfiedConditionException e) {
        // You need to handle `UnsatisfiedConditionException` only if a mutation operation specifies a condition.
        // This exception indicates the condition for the mutation operation is not met.

        // End this process's own branch, declaring that its work failed.
        if (branch != null) {
          try {
            branch.end(BranchTransaction.Status.FAILURE);
          } catch (CrudException ex) {
            // Ending the branch failed. The global transaction is rolled back below, so you don't
            // need to do anything further. You can simply log the occurrence here.
          }
        }

        try {
          globalTransaction.rollback();
        } catch (RollbackException ex) {
          // Rolling back the global transaction failed. Since the transaction should eventually recover,
          // you don't need to do anything further. You can simply log the occurrence here.
        }

        // You can handle the exception here, according to your application requirements.

        return;
      } catch (UnknownTransactionStatusException e) {
        // If you catch `UnknownTransactionStatusException` when committing the global transaction,
        // it indicates that the status of the transaction, whether it was successful or not, is unknown.
        // In such a case, you need to check if the transaction is committed successfully or not and
        // retry the transaction if it failed. How to identify a transaction status is delegated to users.
        return;
      } catch (TransactionException e) {
        // For other exceptions, you can retry the global transaction.

        // For `CrudConflictException`, `CommitConflictException`, and `TransactionNotFoundException`,
        // you can basically retry the transaction. However, for the other exceptions, the transaction
        // will still fail if the cause of the exception is non-transient. In such a case, you will
        // exhaust the number of retries.

        // End this process's own branch, declaring that its work failed.
        if (branch != null) {
          try {
            branch.end(BranchTransaction.Status.FAILURE);
          } catch (CrudException ex) {
            // Ending the branch failed. The global transaction is rolled back below, so you don't
            // need to do anything further. You can simply log the occurrence here.
          }
        }

        if (globalTransaction != null) {
          try {
            globalTransaction.rollback();
          } catch (RollbackException ex) {
            // Rolling back the global transaction failed. The transaction should eventually recover,
            // so you don't need to do anything further. You can simply log the occurrence here.
          }
        }

        lastException = e;
      } catch (Exception e) {
        // The call to the other processes can fail with an exception that ScalarDB does not define,
        // such as an RPC failure. Retrying does not necessarily help in that case, so this sample
        // code cleans up and propagates the exception instead.

        // End this process's own branch, declaring that its work failed.
        if (branch != null) {
          try {
            branch.end(BranchTransaction.Status.FAILURE);
          } catch (CrudException ex) {
            // Ending the branch failed. The global transaction is rolled back below, so you don't
            // need to do anything further. You can simply log the occurrence here.
          }
        }

        if (globalTransaction != null) {
          try {
            globalTransaction.rollback();
          } catch (RollbackException ex) {
            // Rolling back the global transaction failed. The transaction should eventually recover,
            // so you don't need to do anything further. You can simply log the occurrence here.
          }
        }

        throw e;
      }
    }
  }
}
注記

グローバルトランザクションを再試行するということは、そのトランザクションに参加するすべてのプロセスで最初から再試行することを意味します。トランザクションをロールバックすると、すべてのブランチの書き込みが破棄されるためです。

テクニカルサポートに問い合わせ
商用ライセンスをご契約のお客様のみご利用いただけます。
ドキュメントの問題を報告
このページについて何かお気づきの点がありましたら、こちらから報告いただけます。