前提条件ステップ 1: プロジェクトを設定するステップ 2: ドライバーを初期化するステップ 3: テーブルとインデックスを作成するステップ 4: ドキュメントを挿入するステップ 5: ドキュメントにクエリを実行するステップ 6: ドキュメントを更新する完全なアプリケーションの実行

Node.js 用 Amazon QLDB ドライバー — クイックスタートチュートリアル

このセクションでは、Node.js 用 Amazon QLDB ドライバーを使用して簡単なアプリケーションを設定する方法について説明します。このガイドには、ドライバーのインストール手順と、基本的な作成、読み取り、更新、削除 (CRUD) オペレーションを実行する JavaScript と TypeScript の短いコード例が含まれています。これらのオペレーションを完全なサンプルアプリケーションで実行する詳細な例については、「Node.js チュートリアル」を参照してください。

注記

ステップによっては、サポート対象メジャーバージョンの Node.js 用 QLDB ドライバーごとに異なるコード例を示しています (該当する場合)。

前提条件

作業を始める前に、次の操作を実行してください。

Node.js ドライバー用の「前提条件」を完了します (まだ完了していない場合)。これには、AWS へのサインアップ、開発のためのプログラムによるアクセスの許可、Node.js のインストールが含まれます。
quick-start という名前の台帳を作成します。

台帳の作成方法については、「Amazon QLDB 台帳の基本的なオペレーション」、または「コンソールの開始方法」の「ステップ 1: 新しい台帳を作成する」を参照してください。

TypeScript を使用している場合、次の設定手順も実行する必要があります。

TypeScript をインストールするには

TypeScript パッケージをインストールします。QLDB ドライバーは TypeScript 3.8.x で動作します。
```
$ npm install --global typescript@3.8.0
```
パッケージがインストールされたら、次のコマンドを実行して TypeScript コンパイラがインストールされていることを確認します。
```
$ tsc --version
```

次のステップのコードを実行するには、まず TypeScript ファイルを、次のように、実行可能な JavaScript コードにトランスパイルする必要があります。


$ tsc app.ts; node app.js

ステップ 1: プロジェクトを設定する

まず、Node.js プロジェクトを設定します。

アプリケーション用のフォルダを作成します。
```
$ mkdir myproject
$ cd myproject
```
プロジェクトを初期化するには、次の npm コマンドを入力し、設定中に表示される質問に回答します。ほとんどの質問にはデフォルトを使用できます。
```
$ npm init
```
Node.js 用 Amazon QLDB ドライバーをインストールします。
- バージョン 3.x の使用
```
$ npm install amazon-qldb-driver-nodejs --save
```
- バージョン 2.x の使用
```
$ npm install amazon-qldb-driver-nodejs@2.2.0 --save
```
- バージョン 1.x の使用
```
$ npm install amazon-qldb-driver-nodejs@1.0.0 --save
```

ドライバーのピア依存関係をインストールします。

バージョン 3.x の使用


$ npm install @aws-sdk/client-qldb-session --save
$ npm install ion-js --save
$ npm install jsbi --save

バージョン 2.x または 1.x の使用


$ npm install aws-sdk --save
$ npm install ion-js@4.0.0 --save
$ npm install jsbi@3.1.1 --save

JavaScript には app.js、TypeScript には app.ts という名前で新しいファイルを作成します。

次に、以下のステップのコード例を段階的に追加し、いくつかの基本的な CRUD オペレーションを試します。または、ステップバイステップのチュートリアルをスキップして、代わりに完全なアプリケーションを実行することもできます。

ステップ 2: ドライバーを初期化する

quick-start という名前の台帳に接続するドライバーのインスタンスを初期化します。次のコードを app.js または app.ts ファイルに追加します。

注記

このコード例では、us-east-1 を、台帳を作成した AWS リージョンに置き換えます。
簡単にするために、このガイドの残りのコード例では、次のバージョン 1.x の例で指定しているように、デフォルト設定のドライバーを使用しています。その代わりに、RetryConfig をカスタマイズすることで、独自のドライバーインスタンスを使用することもできます。

注記

このコード例では、us-east-1 を、台帳を作成した AWS リージョンに置き換えます。
バージョン 2.x には QldbDriver を初期化する RetryConfig という新しいオプションパラメータが導入されています。
簡単にするために、このガイドの残りのコード例では、次のバージョン 1.x の例で指定しているように、デフォルト設定のドライバーを使用しています。その代わりに、RetryConfig をカスタマイズすることで、独自のドライバーインスタンスを使用することもできます。
このコード例では、Keep-Alive オプションを設定して、既存の接続を再利用するドライバーを初期化します。詳細については、Node.js ドライバー向けの「セットアップの推奨事項」を参照してください。

注記

AWS_REGION 環境変数を設定して、リージョンを指定できます。詳細については、「AWS SDK for JavaScript デベロッパーガイド」の「AWS リージョンの設定」を参照してください。

ステップ 3: テーブルとインデックスを作成する

次のコード例は、CREATE TABLE ステートメントと CREATE INDEX ステートメントの実行方法を示しています。

次の関数を追加して People という名前のテーブルを作成します。

People テーブルの firstName フィールドのインデックスを作成する、以下の関数を追加します。クエリのパフォーマンスを最適化し、オプティミスティック同時実行制御 (OCC) 競合例外を制限するために、インデックスが必要です。
JavaScript
```
async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
```
TypeScript
```
async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}
```

main 関数で最初に createTable を呼び出し、次に createIndex を呼び出します。

コードを実行して、テーブルとインデックスを作成します。
JavaScript
```
$ node app.js
```
TypeScript
```
$ tsc app.ts; node app.js
```

ステップ 4: ドキュメントを挿入する

次のコード例は、INSERT ステートメントの実行方法を示しています。QLDB は PartiQL クエリ言語 (SQL 互換) と Amazon Ion データ形式 (JSON のスーパーセット) をサポートします。

次の関数を追加して People テーブルにドキュメントを挿入します。
JavaScript
```
async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
```
TypeScript
```
async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}
```
この例では、疑問符 (?) を変数プレースホルダーとして使用して、ドキュメント情報をステートメントに渡します。execute メソッドは、Amazon Ion 型と Node.js ネイティブ型の両方の値をサポートします。
ヒント
1 つの INSERT ステートメントを使用して複数のドキュメントを挿入するために、次のように型 list のパラメータをステートメントに渡すことができます。
```
// people is a list
txn.execute("INSERT INTO People ?", people);
```
リストを渡すときには、変数プレースホルダー (?) を二重山括弧 (<<...>>) で囲まないでください。マニュアルの PartiQL ステートメントでは、二重山括弧はバッグと呼ばれる順序付けされていないコレクションを表します。

main 関数で、createTable と createIndex の呼び出しを削除し、insertDocument への呼び出しを追加します。

ステップ 5: ドキュメントにクエリを実行する

次のコード例は、SELECT ステートメントの実行方法を示しています。

次の関数を追加して People テーブルのドキュメントにクエリを実行します。

main 関数で、次の fetchDocuments への呼び出しを、insertDocument への呼び出しの後に追加します。

ステップ 6: ドキュメントを更新する

次のコード例は、UPDATE ステートメントの実行方法を示しています。

次の関数を追加し、lastName を "Stiles" に変更して People テーブルのドキュメントを更新します。

main 関数で、次の updateDocuments への呼び出しを、fetchDocuments への呼び出しの後に追加します。次に、fetchDocuments を再度呼び出して、更新された結果を確認します。

コードを実行して、ドキュメントの挿入、クエリ、更新を行います。
JavaScript
```
$ node app.js
```
TypeScript
```
$ tsc app.ts; node app.js
```

完全なアプリケーションの実行

次のコード例は、app.js と app.ts の完全なバージョンを示しています。上のステップを個別に実行する代わりに、このコードを最初から最後まで実行することもできます。このアプリケーションは、quick-start という名前の台帳に対するいくつかの基本的な CRUD オペレーションを実行します。

注記

このコードを実行する前に、quick-start 台帳に People という名前のアクティブなテーブルが存在しないことを確認してください。

JavaScript


const qldb = require('amazon-qldb-driver-nodejs');

async function createTable(txn) {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn) {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn) {
    const person = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn) {
    return await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John");
}

async function updateDocuments(txn) {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
}

async function main() {
    // Use default settings
    const driver = new qldb.QldbDriver("quick-start");

    var resultList = await driver.executeLambda(async (txn) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        var result = await fetchDocuments(txn);
        return result.getResultList();
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

main();

TypeScript


import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom } from "ion-js";

async function createTable(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE TABLE People");
}

async function createIndex(txn: TransactionExecutor): Promise<void> {
    await txn.execute("CREATE INDEX ON People (firstName)");
}

async function insertDocument(txn: TransactionExecutor): Promise<void> {
    const person: Record<string, any> = {
        firstName: "John",
        lastName: "Doe",
        age: 42
    };
    await txn.execute("INSERT INTO People ?", person);
}

async function fetchDocuments(txn: TransactionExecutor): Promise<dom.Value[]> {
    return (await txn.execute("SELECT firstName, age, lastName FROM People WHERE firstName = ?", "John")).getResultList();
}

async function updateDocuments(txn: TransactionExecutor): Promise<void> {
    await txn.execute("UPDATE People SET lastName = ? WHERE firstName = ?", "Stiles", "John");
};

async function main(): Promise<void> {
    // Use default settings
    const driver: QldbDriver = new QldbDriver("quick-start");

    const resultList: dom.Value[] = await driver.executeLambda(async (txn: TransactionExecutor) => {
        console.log("Create table People");
        await createTable(txn);
        console.log("Create index on firstName");
        await createIndex(txn);
        console.log("Insert document");
        await insertDocument(txn);
        console.log("Fetch document");
        await fetchDocuments(txn);
        console.log("Update document");
        await updateDocuments(txn);
        console.log("Fetch document after update");
        return await fetchDocuments(txn);
    });

    // Pretty print the result list
    console.log("The result List is ", JSON.stringify(resultList, null, 2));
    driver.close();
}

if (require.main === module) {
    main();
}

完全なアプリケーションを実行するには、次のコマンドを入力します。

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

Node.js ドライバー

クックブックリファレンス