本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# Node.js 的 Amazon QLDB 驱动程序 — 说明书参考
**重要**
终止支持通知：现有客户将能够使用 Amazon QLDB，直到 2025 年 7 月 31 日终止支持。有关更多详细信息，请参阅[将亚马逊 QLDB 账本迁移到亚马逊 Aurora PostgreSQL](https://aws.amazon.com/blogs/database/migrate-an-amazon-qldb-ledger-to-amazon-aurora-postgresql/)。
本参考指南显示了 Node.js 的 Amazon QLDB 驱动程序的常见用例。它提供的 JavaScript TypeScript 代码示例演示了如何使用驱动程序运行基本的*创建、读取、更新和删除* (CRUD) 操作。它还包括用于处理 Amazon Ion 数据的代码示例。此外，本指南还重点介绍了使事务具有幂等性和实现唯一性约束的最佳实践。
**Contents**
+ [导入驱动程序](#cookbook-nodejs.importing)
+ [实例化驱动程序](#cookbook-nodejs.instantiating)
+ [CRUD 操作](#cookbook-nodejs.crud)
+ [创建表](#cookbook-nodejs.crud.creating-tables)
+ [创建索引](#cookbook-nodejs.crud.creating-indexes)
+ [阅读文档](#cookbook-nodejs.crud.reading)
+ [使用查询参数](#cookbook-nodejs.reading-using-params)
+ [插入文档](#cookbook-nodejs.crud.inserting)
+ [在一条语句内插入多个文档](#cookbook-nodejs.crud.inserting.multiple)
+ [更新文档](#cookbook-nodejs.crud.updating)
+ [删除文档](#cookbook-nodejs.crud.deleting)
+ [在一个事务中运行多条语句](#cookbook-nodejs.crud.multi-statement)
+ [重试逻辑](#cookbook-nodejs.crud.retry-logic)
+ [实现唯一限制](#cookbook-nodejs.crud.uniqueness-constraints)
+ [使用 Amazon Ion](#cookbook-nodejs.ion)
+ [导入 Ion 模块](#cookbook-nodejs.ion.import)
+ [创建 Ion 类型](#cookbook-nodejs.ion.creating-types)
+ [获取 Ion 二进制转储](#cookbook-nodejs.ion.getting-binary)
+ [获取 Ion 文本转储](#cookbook-nodejs.ion.getting-text)
## 导入驱动程序
下面的代码示例导入驱动程序。
------
#### [ JavaScript ]
```
var qldb = require('amazon-qldb-driver-nodejs');
var ionjs = require('ion-js');
```
------
#### [ TypeScript ]
```
import { QldbDriver, TransactionExecutor } from "amazon-qldb-driver-nodejs";
import { dom, dumpBinary, load } from "ion-js";
```
------
**注意**
此示例还导入了 Amazon Ion 软件包（`ion-js`）。在本参考中运行某些数据操作时，您需要此软件包来处理 Ion 数据。要了解更多信息，请参阅 [使用 Amazon Ion](#cookbook-nodejs.ion)。
## 实例化驱动程序
以下代码示例使用默认设置创建连接到指定分类账名称的驱动程序实例。
------
#### [ JavaScript ]
```
const qldbDriver = new qldb.QldbDriver("vehicle-registration");
```
------
#### [ TypeScript ]
```
const qldbDriver: QldbDriver = new QldbDriver("vehicle-registration");
```
------
## CRUD 操作
QLDB 作为事务的一部分运行*创建、读取、更新和删除*（CRUD）操作。
**警告**
作为最佳实践，使写事务严格地幂等。
**使事务幂等**
我们建议将写事务设置为幂等，以避免重试时出现任何意想不到的副作用。如果事务可以运行多次并每次都产生相同的结果，则事务是*幂等的*。
例如，假设有一个事务，要将文档插入名为 `Person` 的表中。事务应该首先检查文档是否已经存在于表中。如果没有这种检查，表最终可能会有重复的文档。
假设 QLDB 在服务器端成功提交了事务，但客户端在等待响应时超时。如果事务不是幂等的，则在重试的情况下可以多次插入相同的文档。
**使用索引避免全表扫描**
我们还建议您在索引字段或文档 ID 上使用*相等*运算符来运行带有`WHERE`谓词子句的语句；例如，`WHERE indexedField = 123`或 `WHERE indexedField IN (456, 789)`。如果没有这种索引查找，QLDB 需要进行表扫描，这可能会导致事务超时或*乐观并发控制*（OCC）冲突。
有关 OCC 的更多信息，请参阅[Amazon QLDB 并发模型](concurrency.md)。
**隐式创建的事务**
[QldbDriver.executeLambd](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/2.2.0/classes/_src_qldbdriver_.qldbdriver.html#executelambda) a 方法接受一个接收实例的 lambda 函数 [TransactionExecutor](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/2.2.0/classes/_src_transactionexecutor_.transactionexecutor.html)，您可以使用该函数来运行语句。`TransactionExecutor` 的实例封装了隐式创建的事务。
您可以使用事务执行器的[执行](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/2.2.0/classes/_src_transactionexecutor_.transactionexecutor.html#execute)方法在 lambda 函数中运行语句。当 lambda 函数返回时，驱动程序会隐式提交事务。
**注意**
该 `execute` 方法同时支持 Amazon Ion 类型和 Node.js 本机类型。如果您将 Node.js 原生类型作为参数传递给 `execute`，则驱动程序会使用该 `ion-js` 包将其转换为 Ion 类型（前提是支持对给定 Node.js 数据类型的转换）。有关支持的数据类型和转换规则，请参阅 Ion JavaScript DOM [自述文件](https://github.com/amzn/ion-js/blob/master/src/dom/README.md)。
以下各节介绍如何运行基本的 CRUD 操作、指定自定义重试逻辑以及如何实现唯一性约束。
**Contents**
+ [创建表](#cookbook-nodejs.crud.creating-tables)
+ [创建索引](#cookbook-nodejs.crud.creating-indexes)
+ [阅读文档](#cookbook-nodejs.crud.reading)
+ [使用查询参数](#cookbook-nodejs.reading-using-params)
+ [插入文档](#cookbook-nodejs.crud.inserting)
+ [在一条语句内插入多个文档](#cookbook-nodejs.crud.inserting.multiple)
+ [更新文档](#cookbook-nodejs.crud.updating)
+ [删除文档](#cookbook-nodejs.crud.deleting)
+ [在一个事务中运行多条语句](#cookbook-nodejs.crud.multi-statement)
+ [重试逻辑](#cookbook-nodejs.crud.retry-logic)
+ [实现唯一限制](#cookbook-nodejs.crud.uniqueness-constraints)
### 创建表
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
await txn.execute("CREATE TABLE Person");
});
})();
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await txn.execute('CREATE TABLE Person');
});
}());
```
------
### 创建索引
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
await txn.execute("CREATE INDEX ON Person (GovId)");
});
})();
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await txn.execute('CREATE INDEX ON Person (GovId)');
});
}());
```
------
### 阅读文档
------
#### [ JavaScript ]
```
(async function() {
// Assumes that Person table has documents as follows:
// { "GovId": "TOYENC486FH", "FirstName": "Brent" }
await qldbDriver.executeLambda(async (txn) => {
const results = (await txn.execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'")).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
// Assumes that Person table has documents as follows:
// { "GovId": "TOYENC486FH", "FirstName": "Brent" }
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const results: dom.Value[] = (await txn.execute("SELECT * FROM Person WHERE GovId = 'TOYENC486FH'")).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
#### 使用查询参数
以下代码示例使用原生类型查询参数。
------
#### [ JavaScript ]
```
(async function() {
// Assumes that Person table has documents as follows:
// { "GovId": "TOYENC486FH", "FirstName": "Brent" }
await qldbDriver.executeLambda(async (txn) => {
const results = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', 'TOYENC486FH')).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
// Assumes that Person table has documents as follows:
// { "GovId": "TOYENC486FH", "FirstName": "Brent" }
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', 'TOYENC486FH')).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
以下代码示例使用 Ion 类型查询参数。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
const govId = ionjs.load("TOYENC486FH");
const results = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', govId)).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const govId: dom.Value = load("TOYENC486FH");
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', govId)).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
以下代码示例使用了多个查询参数。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
const results = (await txn.execute('SELECT * FROM Person WHERE GovId = ? AND FirstName = ?', 'TOYENC486FH', 'Brent')).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId = ? AND FirstName = ?', 'TOYENC486FH', 'Brent')).getResultList();
for (let result of results) {
console.log(result.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(result.get('FirstName')); // prints [String: 'Brent']
}
});
}());
```
------
以下代码示例使用查询参数列表。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
const govIds = ['TOYENC486FH','LOGANB486CG','LEWISR261LL'];
/*
Assumes that Person table has documents as follows:
{ "GovId": "TOYENC486FH", "FirstName": "Brent" }
{ "GovId": "LOGANB486CG", "FirstName": "Brent" }
{ "GovId": "LEWISR261LL", "FirstName": "Raul" }
*/
const results = (await txn.execute('SELECT * FROM Person WHERE GovId IN (?,?,?)', ...govIds)).getResultList();
for (let result of results) {
console.log(result.get('GovId'));
console.log(result.get('FirstName'));
/*
prints:
[String: 'TOYENC486FH']
[String: 'Brent']
[String: 'LOGANB486CG']
[String: 'Brent']
[String: 'LEWISR261LL']
[String: 'Raul']
*/
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const govIds: string[] = ['TOYENC486FH','LOGANB486CG','LEWISR261LL'];
/*
Assumes that Person table has documents as follows:
{ "GovId": "TOYENC486FH", "FirstName": "Brent" }
{ "GovId": "LOGANB486CG", "FirstName": "Brent" }
{ "GovId": "LEWISR261LL", "FirstName": "Raul" }
*/
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId IN (?,?,?)', ...govIds)).getResultList();
for (let result of results) {
console.log(result.get('GovId'));
console.log(result.get('FirstName'));
/*
prints:
[String: 'TOYENC486FH']
[String: 'Brent']
[String: 'LOGANB486CG']
[String: 'Brent']
[String: 'LEWISR261LL']
[String: 'Raul']
*/
}
});
}());
```
------
**注意**
当您在没有索引查找的情况下运行查询时，它会调用全表扫描。在此示例中，我们建议在`GovId`字段上设置 [索引](ql-reference.create-index.md)以优化性能。如果不开启`GovId`索引，查询可能会有更长的延迟，还可能导致 OCC 冲突异常或者事务超时。
### 插入文档
以下代码示例插入本地数据类型。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
// Check if doc with GovId:TOYENC486FH exists
// This is critical to make this transaction idempotent
const results = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', 'TOYENC486FH')).getResultList();
// Insert the document after ensuring it doesn't already exist
if (results.length == 0) {
const doc = {
'FirstName': 'Brent',
'GovId': 'TOYENC486FH',
};
await txn.execute('INSERT INTO Person ?', doc);
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
// Check if doc with GovId:TOYENC486FH exists
// This is critical to make this transaction idempotent
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', 'TOYENC486FH')).getResultList();
// Insert the document after ensuring it doesn't already exist
if (results.length == 0) {
const doc: Record = {
'FirstName': 'Brent',
'GovId': 'TOYENC486FH',
};
await txn.execute('INSERT INTO Person ?', doc);
}
});
}());
```
------
以下代码示例插入 Ion 数据类型。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
// Check if doc with GovId:TOYENC486FH exists
// This is critical to make this transaction idempotent
const results = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', 'TOYENC486FH')).getResultList();
// Insert the document after ensuring it doesn't already exist
if (results.length == 0) {
const doc = {
'FirstName': 'Brent',
'GovId': 'TOYENC486FH',
};
// Create a sample Ion doc
const ionDoc = ionjs.load(ionjs.dumpBinary(doc));
await txn.execute('INSERT INTO Person ?', ionDoc);
}
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
// Check if doc with GovId:TOYENC486FH exists
// This is critical to make this transaction idempotent
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', 'TOYENC486FH')).getResultList();
// Insert the document after ensuring it doesn't already exist
if (results.length == 0) {
const doc: Record = {
'FirstName': 'Brent',
'GovId': 'TOYENC486FH',
};
// Create a sample Ion doc
const ionDoc: dom.Value = load(dumpBinary(doc));
await txn.execute('INSERT INTO Person ?', ionDoc);
}
});
}());
```
------
此事务将文档插入 `Person` 表中。在插入之前，它首先检查文档是否已存在于表格内。**此检查使事务本质上是幂等。**即使您多次运行此事务，也不会造成任何异常副作用。
**注意**
在此示例中，我们建议在 `GovId` 字段上设置索引以优化性能。如果不开启`GovId`索引，语句可能会有更长的延迟，还可能导致 OCC 冲突异常或者事务超时。
#### 在一条语句内插入多个文档
要使用单个 [INSERT](ql-reference.insert.md) 语句插入多个文档，可以向该语句传递一个[列表](driver-working-with-ion.md#driver-ion-list)类型的参数，如下所示。
```
// people is a list
txn.execute("INSERT INTO People ?", people);
```
传递 Ion 列表时，不要将变量占位符（`?`）括在双尖括号（`<<...>>`）内。在手动 PartiQL 语句中，双尖括号表示名为*bag*的无序集合。
### 更新文档
以下代码示例使用原生数据类型。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
await txn.execute('UPDATE Person SET FirstName = ? WHERE GovId = ?', 'John', 'TOYENC486FH');
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await txn.execute('UPDATE Person SET FirstName = ? WHERE GovId = ?', 'John', 'TOYENC486FH');
});
}());
```
------
以下代码示例使用 Ion 数据类型。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
const firstName = ionjs.load("John");
const govId = ionjs.load("TOYENC486FH");
await txn.execute('UPDATE Person SET FirstName = ? WHERE GovId = ?', firstName, govId);
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const firstName: dom.Value = load("John");
const govId: dom.Value = load("TOYENC486FH");
await txn.execute('UPDATE Person SET FirstName = ? WHERE GovId = ?', firstName, govId);
});
}());
```
------
**注意**
在此示例中，我们建议在 `GovId` 字段上设置索引以优化性能。如果不开启`GovId`索引，语句可能会有更长的延迟，还可能导致 OCC 冲突异常或者事务超时。
### 删除文档
以下代码示例使用原生数据类型。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
await txn.execute('DELETE FROM Person WHERE GovId = ?', 'TOYENC486FH');
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await txn.execute('DELETE FROM Person WHERE GovId = ?', 'TOYENC486FH');
});
}());
```
------
以下代码示例使用 Ion 数据类型。
------
#### [ JavaScript ]
```
(async function() {
await qldbDriver.executeLambda(async (txn) => {
const govId = ionjs.load("TOYENC486FH");
await txn.execute('DELETE FROM Person WHERE GovId = ?', govId);
});
}());
```
------
#### [ TypeScript ]
```
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
const govId: dom.Value = load("TOYENC486FH");
await txn.execute('DELETE FROM Person WHERE GovId = ?', govId);
});
}());
```
------
**注意**
在此示例中，我们建议在 `GovId` 字段上设置索引以优化性能。如果不开启`GovId`索引，语句可能会有更长的延迟，还可能导致 OCC 冲突异常或者事务超时。
### 在一个事务中运行多条语句
------
#### [ TypeScript ]
```
// This code snippet is intentionally trivial. In reality you wouldn't do this because you'd
// set your UPDATE to filter on vin and insured, and check if you updated something or not.
async function insureCar(driver: QldbDriver, vin: string): Promise {
return await driver.executeLambda(async (txn: TransactionExecutor) => {
const results: dom.Value[] = (await txn.execute(
"SELECT insured FROM Vehicles WHERE vin = ? AND insured = FALSE", vin)).getResultList();
if (results.length > 0) {
await txn.execute(
"UPDATE Vehicles SET insured = TRUE WHERE vin = ?", vin);
return true;
}
return false;
});
};
```
------
### 重试逻辑
驱动程序 `executeLambda` 方法具有内置的重试机制，如果发生可重试的异常（例如超时或 OCC 冲突），该机制可以重试事务。最大重试次数和退避策略为可配置。
默认的重试限制为`4`，默认的退避策略以毫秒[defaultBackoffFunction](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/2.2.0/modules/_src_retry_defaultretryconfig_.html#defaultretryconfig)为基准。`10`您可以使用的实例为每个驱动程序实例以及每个事务设置重试配置。[RetryConfig](https://amazon-qldb-docs.s3.amazonaws.com/drivers/nodejs/2.2.0/classes/_src_retry_retryconfig_.retryconfig.html)
以下代码示例使用自定义重试限制和驱动程序实例的自定义退避策略指定重试逻辑。
------
#### [ JavaScript ]
```
var qldb = require('amazon-qldb-driver-nodejs');
// Configuring retry limit to 2
const retryConfig = new qldb.RetryConfig(2);
const qldbDriver = new qldb.QldbDriver("test-ledger", undefined, undefined, retryConfig);
// Configuring a custom backoff which increases delay by 1s for each attempt.
const customBackoff = (retryAttempt, error, transactionId) => {
return 1000 * retryAttempt;
};
const retryConfigCustomBackoff = new qldb.RetryConfig(2, customBackoff);
const qldbDriverCustomBackoff = new qldb.QldbDriver("test-ledger", undefined, undefined, retryConfigCustomBackoff);
```
------
#### [ TypeScript ]
```
import { BackoffFunction, QldbDriver, RetryConfig } from "amazon-qldb-driver-nodejs"
// Configuring retry limit to 2
const retryConfig: RetryConfig = new RetryConfig(2);
const qldbDriver: QldbDriver = new QldbDriver("test-ledger", undefined, undefined, retryConfig);
// Configuring a custom backoff which increases delay by 1s for each attempt.
const customBackoff: BackoffFunction = (retryAttempt: number, error: Error, transactionId: string) => {
return 1000 * retryAttempt;
};
const retryConfigCustomBackoff: RetryConfig = new RetryConfig(2, customBackoff);
const qldbDriverCustomBackoff: QldbDriver = new QldbDriver("test-ledger", undefined, undefined, retryConfigCustomBackoff);
```
------
以下代码示例使用自定义重试限制和自定义回退策略为特定 lambda 执行指定重试逻辑。此`executeLambda`配置将覆盖为驱动程序实例设置的重试逻辑。
------
#### [ JavaScript ]
```
var qldb = require('amazon-qldb-driver-nodejs');
// Configuring retry limit to 2
const retryConfig1 = new qldb.RetryConfig(2);
const qldbDriver = new qldb.QldbDriver("test-ledger", undefined, undefined, retryConfig1);
// Configuring a custom backoff which increases delay by 1s for each attempt.
const customBackoff = (retryAttempt, error, transactionId) => {
return 1000 * retryAttempt;
};
const retryConfig2 = new qldb.RetryConfig(2, customBackoff);
// The config `retryConfig1` will be overridden by `retryConfig2`
(async function() {
await qldbDriver.executeLambda(async (txn) => {
await txn.execute('CREATE TABLE Person');
}, retryConfig2);
}());
```
------
#### [ TypeScript ]
```
import { BackoffFunction, QldbDriver, RetryConfig, TransactionExecutor } from "amazon-qldb-driver-nodejs"
// Configuring retry limit to 2
const retryConfig1: RetryConfig = new RetryConfig(2);
const qldbDriver: QldbDriver = new QldbDriver("test-ledger", undefined, undefined, retryConfig1);
// Configuring a custom backoff which increases delay by 1s for each attempt.
const customBackoff: BackoffFunction = (retryAttempt: number, error: Error, transactionId: string) => {
return 1000 * retryAttempt;
};
const retryConfig2: RetryConfig = new RetryConfig(2, customBackoff);
// The config `retryConfig1` will be overridden by `retryConfig2`
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
await txn.execute('CREATE TABLE Person');
}, retryConfig2);
}());
```
------
### 实现唯一限制
QLDB 不支持唯一索引，但您可在应用程序中实现此行为。
假设您要对 `Person` 表中的 `GovId` 字段实现唯一性约束。据此，可以编写执行以下操作的事务：
1. 断言该表中没有指定 `GovId` 的现有文档。
1. 如果断言通过，请插入文档。
如果一个竞争事务同时通过断言，则只有一个事务将成功提交。另一笔事务将失败，并显示 OCC 冲突异常。
以下代码示例显示了如何实现此唯一约束。
------
#### [ JavaScript ]
```
const govId = 'TOYENC486FH';
const document = {
'FirstName': 'Brent',
'GovId': 'TOYENC486FH',
};
(async function() {
await qldbDriver.executeLambda(async (txn) => {
// Check if doc with GovId = govId exists
const results = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', govId)).getResultList();
// Insert the document after ensuring it doesn't already exist
if (results.length == 0) {
await txn.execute('INSERT INTO Person ?', document);
}
});
})();
```
------
#### [ TypeScript ]
```
const govId: string = 'TOYENC486FH';
const document: Record = {
'FirstName': 'Brent',
'GovId': 'TOYENC486FH',
};
(async function(): Promise {
await qldbDriver.executeLambda(async (txn: TransactionExecutor) => {
// Check if doc with GovId = govId exists
const results: dom.Value[] = (await txn.execute('SELECT * FROM Person WHERE GovId = ?', govId)).getResultList();
// Insert the document after ensuring it doesn't already exist
if (results.length == 0) {
await txn.execute('INSERT INTO Person ?', document);
}
});
})();
```
------
**注意**
在此示例中，我们建议在 `GovId` 字段上设置索引以优化性能。如果不开启`GovId`索引，语句可能会有更长的延迟，还可能导致 OCC 冲突异常或者事务超时。
## 使用 Amazon Ion
以下各节说明了如何使用 Amazon Ion 模块处理 Ion 数据。
**Contents**
+ [导入 Ion 模块](#cookbook-nodejs.ion.import)
+ [创建 Ion 类型](#cookbook-nodejs.ion.creating-types)
+ [获取 Ion 二进制转储](#cookbook-nodejs.ion.getting-binary)
+ [获取 Ion 文本转储](#cookbook-nodejs.ion.getting-text)
### 导入 Ion 模块
------
#### [ JavaScript ]
```
var ionjs = require('ion-js');
```
------
#### [ TypeScript ]
```
import { dom, dumpBinary, dumpText, load } from "ion-js";
```
------
### 创建 Ion 类型
以下代码示例从 Ion 文本创建 Ion 对象。
------
#### [ JavaScript ]
```
const ionText = '{GovId: "TOYENC486FH", FirstName: "Brent"}';
const ionObj = ionjs.load(ionText);
console.log(ionObj.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(ionObj.get('FirstName')); // prints [String: 'Brent']
```
------
#### [ TypeScript ]
```
const ionText: string = '{GovId: "TOYENC486FH", FirstName: "Brent"}';
const ionObj: dom.Value = load(ionText);
console.log(ionObj.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(ionObj.get('FirstName')); // prints [String: 'Brent']
```
------
以下代码示例从 Node.js 字典创建 Ion 对象。
------
#### [ JavaScript ]
```
const aDict = {
'GovId': 'TOYENC486FH',
'FirstName': 'Brent'
};
const ionObj = ionjs.load(ionjs.dumpBinary(aDict));
console.log(ionObj.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(ionObj.get('FirstName')); // prints [String: 'Brent']
```
------
#### [ TypeScript ]
```
const aDict: Record = {
'GovId': 'TOYENC486FH',
'FirstName': 'Brent'
};
const ionObj: dom.Value = load(dumpBinary(aDict));
console.log(ionObj.get('GovId')); // prints [String: 'TOYENC486FH']
console.log(ionObj.get('FirstName')); // prints [String: 'Brent']
```
------
### 获取 Ion 二进制转储
------
#### [ JavaScript ]
```
// ionObj is an Ion struct
console.log(ionjs.dumpBinary(ionObj).toString()); // prints 224,1,0,234,238,151,129,131,222,147,135,190,144,133,71,111,118,73,100,137,70,105,114,115,116,78,97,109,101,222,148,138,139,84,79,89,69,78,67,52,56,54,70,72,139,133,66,114,101,110,116
```
------
#### [ TypeScript ]
```
// ionObj is an Ion struct
console.log(dumpBinary(ionObj).toString()); // prints 224,1,0,234,238,151,129,131,222,147,135,190,144,133,71,111,118,73,100,137,70,105,114,115,116,78,97,109,101,222,148,138,139,84,79,89,69,78,67,52,56,54,70,72,139,133,66,114,101,110,116
```
------
### 获取 Ion 文本转储
------
#### [ JavaScript ]
```
// ionObj is an Ion struct
console.log(ionjs.dumpText(ionObj)); // prints {GovId:"TOYENC486FH",FirstName:"Brent"}
```
------
#### [ TypeScript ]
```
// ionObj is an Ion struct
console.log(dumpText(ionObj)); // prints {GovId:"TOYENC486FH",FirstName:"Brent"}
```
------
有关 Ion 的更多信息，请参阅上的 [Amazon Ion 文档](http://amzn.github.io/ion-docs/) GitHub。有关在 QLDB 中使用 Ion 的更多代码示例，请参阅[使用 Amazon QLDB 中的 Amazon Ion 数据类型](driver-working-with-ion.md)。