テーブル指向 Generic Contract の使用

注記

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

ヒント

テーブル指向 Generic Contract は ScalarDL 3.11 で導入されましたが、ScalarDL 3.12 でリリースされた TableStore は、テーブル指向 Generic Contract をラップしたより高次の抽象化を提供します。ほとんどのユースケースでは、テーブル指向 Generic Contract を直接使用するよりも、TableStore を使用する方がシンプルで効率的です。詳細については、ScalarDL の最新版の ScalarDL TableStore をはじめようをご参照ください。

ScalarDL のテーブル指向 Generic Contract は、Generic Contractの一種で、リレーショナルデータモデルに似たデータモデルと台帳データを管理するためのユーザーフレンドリーなインターフェースを提供し、容易なアプリケーション開発を可能にします。このガイドでは、テーブル指向 Generic Contract の使用方法について説明します。

注記

テーブル指向 Generic Contract は現在プライベートプレビュー段階にあり、将来のバージョンでは下位互換性のない更新がある可能性があります。

環境のセットアップ

このセクションでは、ScalarDL クライアントツールを通じてテーブル指向 Generic Contract を使用するための環境をセットアップします。アプリケーションで Generic Contract を操作したい場合は、ScalarDL Client SDK API を使用できます。詳細は、Generic Contract を用いた ScalarDL アプリケーションを書くを参照してください。さらに、SQL ベースのインターフェースも近い将来提供される予定です。

JDKのインストール

このガイドでは、Generic Contract の動作を確認するために Java ランタイム環境のみを使用します。ただし、このガイド以外で独自の ScalarDL アプリケーションを構築するには、以下のいずれかの Java Development Kit (JDK) をインストールすることをお勧めします。

• Oracle JDK: 8、11、17、または 21 (LTS バージョン)
• OpenJDK ディストリビューション (Eclipse Temurin、Amazon Corretto、または Microsoft Build of OpenJDK): 8、11、17、または 21 (LTS バージョン)

ScalarDL 環境のセットアップ

要件に合った ScalarDL 環境をセットアップします。ローカルテスト環境に ScalarDL をデプロイしたい場合は、サンプルの Docker Compose 設定や Scalar Helm Chart を使用してデプロイできます。詳細については、以下を参照してください:

• ScalarDL Ledger をはじめよう
• Scalar Helm Charts をはじめよう

本番環境では、ScalarDL はコンテナイメージとして利用可能です。詳細については、Scalar 製品のコンテナイメージの取得方法を参照してください。

注記

テーブル指向 Generic Contract は、ScalarDL のバージョン 3.11 以降でサポートされています。

必要なツールと Generic Contract のダウンロード

以下のコマンドを実行して、3.11.0 以上の ScalarDL バージョンを指定します。<X.Y.Z> は使用したいバージョンに置き換えてください。利用可能なバージョンについては、タグを参照してください。

VERSION=<X.Y.Z>

また、以下のコマンドを実行して、<X_Y_Z> を下記のマッピング表に応じたテーブル指向 Generic Contract のバージョンに置き換えて指定します。ScalarDL バージョンに対応するバージョンを特定するには、以下のマッピング表を使用してください。セパレータ . を _ に置き換えることを忘れないでください。例えば、バージョン 1.0.0 の場合は 1_0_0 となります。

ScalarDL バージョン	テーブル指向 Generic Contract バージョン
3.11.0 以降	1.0.0

TGC_VERSION=<X_Y_Z>

次に、以下のコマンドを実行してツールと Generic Contract をダウンロードします:

curl -OL https://github.com/scalar-labs/scalardl/releases/download/v$VERSION/scalardl-java-client-sdk-$VERSION.zip
unzip scalardl-java-client-sdk-$VERSION.zip
mv scalardl-java-client-sdk-$VERSION client
curl -OL https://github.com/scalar-labs/scalardl/releases/download/v$VERSION/scalardl-generic-contracts-$VERSION.zip
unzip scalardl-generic-contracts-$VERSION.zip
mv scalardl-generic-contracts-$VERSION generic-contracts

証明書とテーブル指向 Generic Contract の登録

このセクションでは、証明書と Generic Contract を登録する方法について説明します。

プロパティの設定

ScalarDL コンポーネントと対話するには、クライアントプロパティを設定する必要があります。詳細は、プロパティを設定するを参照してください。

証明書またはシークレットの登録

登録用の証明書を準備します。詳細は、証明書の取得方法を参照してください。

次に、以下のように ScalarDL クライアント CLI を使用して証明書を登録します。

client/bin/scalardl generic-contracts register-cert --properties client.properties

注記

証明書の代わりに HMAC 認証を使用することもできます。HMAC 認証の詳細については、ScalarDL 認証ガイドを参照してください。

テーブル指向 Generic Contract の登録

証明書を登録した後、以下のコマンドを実行してテーブル指向 Generic Contract を登録できます。

client/bin/scalardl generic-contracts register-contracts --properties client.properties --contracts-file generic-contracts/conf/table-authenticity-management-contracts.toml

テーブル指向 Generic Contract との対話

これで、テーブル指向 Generic Contract を実行できます。このセクションでは、部門のIDを介して結合できる2つのサンプルテーブル (employee と department) を通じて、次の機能を試します。

• テーブルの作成と表示
• レコードの挿入
• レコードの選択
• レコードの更新
• レコード履歴の取得

テーブルの作成と表示

次のコマンドを実行してサンプルテーブルを作成できます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Create \
--contract-argument '{"name": "employee", "key": "id", "type": "string", "indexes": [{"key": "department", "type": "string"}]}'
client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Create \
--contract-argument '{"name": "department", "key": "id", "type": "string"}'

テーブルを作成する際には、名前と主キーを指定する必要があります。追加でセカンダリインデックスを指定することもできます。主キーおよびインデックスキーのデータ型として、string、number、boolean がサポートされています。

次のコマンドを実行して、作成したテーブルを表示できます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.ShowTables \
--contract-argument '{}'

次のような結果が得られるはずです。

Contract result:
[ {
  "name" : "employee",
  "key" : "id",
  "type" : "string",
  "indexes" : [ {
    "key" : "department",
    "type" : "string"
  } ]
}, {
  "name" : "department",
  "key" : "id",
  "type" : "string",
  "indexes" : [ ]
} ]

レコードの挿入

次に、以下のコマンドを実行していくつかの employee レコードを挿入します。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Insert \
--contract-argument '{"table": "employee", "values": {"id": "1001", "name": "Alice", "department": "sales", "salary": 654.3}}'
client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Insert \
--contract-argument '{"table": "employee", "values": {"id": "1002", "name": "Bob", "department": "sales", "salary": 543.2}}'
client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Insert \
--contract-argument '{"table": "employee", "values": {"id": "1003", "name": "Carol", "department": "engineering", "salary": 654.3}}'

次のコマンドを実行して、対応する department レコードも挿入します。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Insert \
--contract-argument '{"table": "department", "values": {"id": "sales", "location": "Shinjuku", "phone": "000-1234"}}'
client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Insert \
--contract-argument '{"table": "department", "values": {"id": "engineering", "location": "Shibuya", "phone": "000-4321"}}'

レコードの選択

次に、挿入したレコードを確認します。レコードを選択するには、少なくとも主キーまたはインデックスキーを指定する必要があります。例えば、次のコマンドを実行して主キーを指定することで、employee レコードを取得できます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Select \
--contract-argument '{"table": "employee", "conditions": [ {"column": "id", "value": "1001", "operator": "EQ"} ], "projections": [ "id", "name", "department" ]}'

オプションで、JSON レコードオブジェクトのトップレベルフィールドを指定することで、列を投影することもできます。次のような結果が得られるはずです。

Contract result:
[ {
  "id" : "1001",
  "name" : "Alice",
  "department" : "sales"
} ]

次のコマンドを実行してインデックスキーを指定することで、レコードを選択することもできます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Select \
--contract-argument '{"table": "employee", "conditions": [ {"column": "department", "value": "sales", "operator": "EQ"} ], "projections": [ "id", "name", "department" ]}'

次のような結果が得られるはずです。

Contract result:
[ {
  "id" : "1001",
  "name" : "Alice",
  "department" : "sales"
}, {
  "id" : "1002",
  "name" : "Bob",
  "department" : "sales"
} ]

レコードをフィルタリングしたい場合は、次のコマンドを実行して追加の条件を指定します。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Select \
--contract-argument '{"table": "employee", "conditions": [ {"column": "department", "value": "sales", "operator": "EQ"}, {"column": "salary", "value": 600, "operator": "LT"} ]}'

追加のフィルタリングには、次の演算子を使用できます: EQ (等しい)、NE (等しくない)、LT (より小さい)、LTE (以下)、GT (より大きい)、GTE (以上)、IS_NULL、および IS_NOT_NULL。次のような結果が得られるはずです。

Contract result:
[ {
  "id" : "1002",
  "name" : "Bob",
  "department" : "sales",
  "salary" : 543.2
} ]

次のコマンドを実行して2つのテーブルを結合することもできます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Select \
--contract-argument '{ "table": "employee", "joins": [ { "table": "department", "left": "employee.department", "right": "department.id" } ], "conditions": [ {"column": "employee.department", "value": "engineering", "operator": "EQ"} ] }'

次のような結果が得られるはずです。

Contract result:
[ {
  "employee.id" : "1003",
  "employee.name" : "Carol",
  "employee.department" : "engineering",
  "employee.salary" : 654.3,
  "department.id" : "engineering",
  "department.location" : "Shibuya",
  "department.phone" : "000-4321"
} ]

レコードの更新

次のコマンドを実行して employee レコードを更新できます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.Update \
--contract-argument '{ "table": "employee", "values": {"salary": 754.3}, "conditions": [ {"column": "department", "value": "sales", "operator": "EQ"} ] }'

Select Contract を使用する場合と同様に、レコードを更新するには少なくとも主キーまたはインデックスキーを指定する必要があります。

レコード履歴の取得

次のコマンドを実行してレコードの更新履歴を取得できます。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.GetHistory \
--contract-argument '{ "table": "employee", "key": "1003" }'

次のような結果が得られるはずです。

Contract result:
[ {
  "age" : 1,
  "values" : {
    "id" : "1003",
    "name" : "Carol",
    "department" : "engineering",
    "salary" : 754.3
  }
}, {
  "age" : 0,
  "values" : {
    "id" : "1003",
    "name" : "Carol",
    "department" : "engineering",
    "salary" : 654.3
  }
} ]

取得するバージョン (世代) の数を制限したい場合は、次のコマンドを実行して limit オプションを指定します。

client/bin/scalardl generic-contracts execute-contract --properties client.properties \
--contract-id table.v${TGC_VERSION}.GetHistory \
--contract-argument '{ "table": "employee", "key": "1003", "limit": 1 }'

指定した数の最新レコードが得られるはずです。

Contract result:
[ {
  "age" : 1,
  "values" : {
    "id" : "1003",
    "name" : "Carol",
    "department" : "engineering",
    "salary" : 754.3
  }
} ]

テーブル指向 Generic Contract によって作成されたデータの検証

ScalarDL では、データがすべて有効な状態にあることを確認するために、時折データを検証する必要があります。validate-ledger コマンドを使用して、テーブル指向 Generic Contract によって作成されたアセットを検証できます。アプリケーションでそれらを検証したい場合は、ScalarDL Client SDK API を使用できます。詳細は、データを検証するを参照してください。

次のコマンドを実行してテーブルスキーマを検証できます。

client/bin/scalardl generic-contracts validate-ledger --properties client.properties \
--table-name employee

次のような結果が得られるはずです。

{
  "status_code" : "OK",
  "Ledger" : {
    "id" : "tbl_employee",
    "age" : 0,
    "nonce" : "26af1229-1c1f-4b89-86e2-ec011da3b313",
    "hash" : "ZA9yFzjIg1qeHAd7Sub8uFvt2JrTb6XSzGUktPEITr0=",
    "signature" : "MEUCIAh4Xj93J/jldqbQor7AVM4ii9+suxQrZlCFnKWWDIo0AiEAiM6Yi6GO4bQ2VZg2GnqKmOFPEANrTU4g7pjBMcaX6TQ="
  },
  "Auditor" : null
}

次のコマンドを実行してレコードを検証できます。

client/bin/scalardl generic-contracts validate-ledger --properties client.properties \
--table-name employee --primary-key-column-name id --column-value '"1001"'

次のような結果が得られるはずです。

{
  "status_code" : "OK",
  "Ledger" : {
    "id" : "rec_employee_id_1001",
    "age" : 0,
    "nonce" : "41a18e7f-314f-4aec-8984-62bf6cd355d0",
    "hash" : "n7KJLuC/KOzFZLnGKEs6pOQvCbl4WSF+xplOUd9MrSo=",
    "signature" : "MEUCIEHafCsSXWWtZnDbSpAwFQk4qjW1B7cXjEgdwVF8uKQeAiEAsvzEMKyuNFozAbLC/E8FEviCMLCqo9DPRQe4tVBFwIk="
  },
  "Auditor" : null
}

次のコマンドを実行してインデックスレコードを検証できます。

client/bin/scalardl generic-contracts validate-ledger --properties client.properties \
--table-name employee --index-key-column-name department --column-value '"sales"'

次のような結果が得られるはずです。

{
  "status_code" : "OK",
  "Ledger" : {
    "id" : "idx_employee_department_sales",
    "age" : 0,
    "nonce" : "41a18e7f-314f-4aec-8984-62bf6cd355d0",
    "hash" : "n7KJLuC/KOzFZLnGKEs6pOQvCbl4WSF+xplOUd9MrSo=",
    "signature" : "MEUCIEHafCsSXWWtZnDbSpAwFQk4qjW1B7cXjEgdwVF8uKQeAiEAsvzEMKyuNFozAbLC/E8FEviCMLCqo9DPRQe4tVBFwIk="
  },
  "Auditor" : null
}

注記

Generic Contract は、内部的にテーブル指向 Generic Contract によって作成されたアセットに専用のアセット ID を割り当てます。アセット ID は、アセットタイプのプレフィックスと識別用のキーで設定されています。例えば、レコードのアセット ID には、rec_ というプレフィックス、テーブル名、主キー列名、および列値が使用されます。したがって、validate-ledger の結果には、そのような生のアセット ID が表示されます。

参照

Java アプリケーションでテーブル指向 Generic Contract と対話するには、次を参照してください。

• Generic Contract を用いた ScalarDL アプリケーションを書く
• ScalarDL Java Client SDK の Javadocs