# @aws/dynamodb-expressions 中文文档

规范地址：https://npmcn.com/package/%40aws/dynamodb-expressions/

版本：0\.7\.3
npm 元数据更新时间：2026-10-15T22:06:37.476Z
中文译文更新时间：2026-11-07T11:22:48.741Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40aws/dynamodb-expressions
原文对照：https://npmcn.com/package/%40aws/dynamodb-expressions/?lang=original
项目主页：https://awslabs.github.io/dynamodb-data-mapper-js/packages/dynamodb-expressions/
源码仓库：https://github.com/awslabs/dynamodb-data-mapper-js

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：86.1 kB，33 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：aws-sdk ^2\.7\.0
- 首次发布：2017-11-20T23:38:21.083Z
- 最新版本发布：2018-08-15T19:53:38.092Z
- 近 30 天下载量：149601（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 0 个）

## 中文简介

Amazon DynamoDB 的可编译表达式对象

## 安装

```sh
npm install @aws/dynamodb-expressions
```

也可以使用：`pnpm add @aws/dynamodb-expressions`、`yarn add @aws/dynamodb-expressions`、`bun add @aws/dynamodb-expressions`

## README

# 亚马逊迪纳摩DB 表达式

[![Apache 2 License](https://img.shields.io/github/license/awslabs/dynamodb-data-mapper-js.svg?style=flat)](http://aws.amazon.com/apache-2-0/)

这个库提供了一些抽象 设计用来处理 Amazon DynamoDB表达式对于JavaScript开发者来说更加容易和自然.

## 属性路径

这个 `AttributePath` 类提供了一个简单的写法 [DynamoDB 文档 路径](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.Attributes.html#Expressions.Attributes.NestedElements.DocumentPathExamples)。 。 。 . 如果构造器收到字符串,它将通过扫描来解析路径 点数( n)`.`),它指定地图属性去引用和左括号(`[`, (中文(简体) ), 指定列表属性去引用。 譬如说, `'ProductReviews.FiveStar[0].reviewer.username'` 将理解为 提及 `username` 财产的财产 `reviewer` 财产 列表中存储的元素 `FiveStar` 顶层属性 `ProductReviews` 文档属性.

如果财产名称含有左括号或圆点,则可能用 反斜线 `\`。例如, `Product\.Reviews` 将解释为单一 顶级文档属性,而不是地图属性访问.

## 属性值

此库将使用运行时类型检测来集合遇到的值 。 若为 您的值已经以 DynamoDB 所期望的格式存在,您可以 把它交给 `AttributeValue` 用于引导其他表达式助手的构造器 不要再把价值分解出来.

## 条件表达式

DynamoDB条件表达式可能以函数调用的形式出现,或者作为函数调用的形式出现 组合值和内插运算符。 因此,该图书馆定义了 `ConditionExpression` 作为联盟 [`FunctionExpression`](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-function-expressions) 和被标记的表达式操作员类型的联盟。 表达式可能是复合的 或简单.

### 复合表达式

这些表达式包含一个或多个简单的表达式,并且是真实的或虚假的 基于其包含的子表达式的值。 公认的大院 表达式为:

#### `And` 表达式

确信子表达的所有条件都得到满足.

```typescript
import {ConditionExpression} from '@aws/dynamodb-expressions';

const andExpression: ConditionExpression = {
    type: 'And',
    conditions: [
        // one or more subexpressions
    ]
};
```

#### `Or` 表达式

认定至少有一个子表达条件得到满足.

```typescript
import {ConditionExpression} from '@aws/dynamodb-expressions';

const orExpression: ConditionExpression = {
    type: 'Or',
    conditions: [
        // one or more subexpressions
    ]
};
```

#### `Not` 表达式

认定子表达条件不满足.

```typescript
import {ConditionExpression} from '@aws/dynamodb-expressions';

const notExpression: ConditionExpression = {
    type: 'Not',
    condition: {
        type: 'LessThan',
        subject: 'foo',
        object: 100
    }
};
```

### 简单表达式

这些表达式对已知的 DynamotB 对象中的一个属性提出了断言 作为表达 `subject`编辑 `subject` 必须是字符串或字符串 [属性 路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths)。 。 。 .

本图书馆将所用特定断言称为 `ConditionExpressionPredicate`上游可与其 `subject` 但只有在配对时才成为有效的表达式 `subject`编辑 支持的条件表达式上游为:

#### `Equals` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 与 定义 `object`例如,下列上游物体声称: 主体的值为 `'bar'`数字 :

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'Equals',
    object: 'bar'
};

// you can also define an equality predicate with the `equals` helper method
import {equals} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = equals('bar');

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`object` 也许是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths),一个 [属性 价值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果收到后一种类型, 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `NotEquals` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 与 定义 `object`例如,下列上游物体声称: 主体没有值 : `'bar'`数字 :

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'NotEquals',
    object: 'bar'
};

// you can also define an equality predicate with the `equals` helper method
import {notEquals} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = notEquals('bar');

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`object` 也许是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths),一个 [属性 价值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果收到后一种类型, 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `LessThan` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 低于 定义 `object`例如,下列上游物体声称: 科目少于10:

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'LessThan',
    object: 10
};

// you can also define an equality predicate with the `equals` helper method
import {lessThan} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = lessThan(10);

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`object` 也许是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths),一个 [属性 价值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果收到后一种类型, 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `LessThanOrEqualTo` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 少于或等于 改为定义 `object`. 例如,下列上游物体声称 该主体小于或等于10:

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'LessThanOrEqualTo',
    object: 10
};

// you can also define an equality predicate with the `equals` helper method
import {lessThanOrEqualTo} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = lessThanOrEqualTo(10);

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`object` 也许是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths),一个 [属性 价值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果收到后一种类型, 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `GreaterThan` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 大于 定义 `object`例如,下列上游物体声称: 对象大于10:

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'GreaterThan',
    object: 10
};

// you can also define an equality predicate with the `equals` helper method
import {greaterThan} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = greaterThan(10);

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`object` 也许是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths),一个 [属性 价值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果收到后一种类型, 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `GreaterThanOrEqualTo` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 大于或大于 等于定义 `object`。例如,以下上游对象 声称该标的大于或等于10:

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'GreaterThanOrEqualTo',
    object: 10
};

// you can also define an equality predicate with the `equals` helper method
import {greaterThanOrEqualTo} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = greaterThanOrEqualTo(10);

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`object` 也许是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths),一个 [属性 价值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果收到后一种类型, 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `Between` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 在定义之间 `lowerBound` 财务报告和审定财务报表 `upperBound`。例如,以下上游对象 声称该主体大于或等于10,小于或等于 改为99:

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'Between',
    lowerBound: 10,
    upperBound: 99
};

// you can also define an equality predicate with the `equals` helper method
import {between} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = between(10, 99);

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

`lowerBound` 财务报告和审定财务报表 `upperBound` 也许两者都是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths), (中文(简体) ), a 一个 [属性值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果后一种类型 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

#### `Membership` 表达式上游

创建一个条件, 如果定义是真实的 `subject` 等于成员 列表中定义的值。 例如,以下上游物体声称: 主题之一 `'fizz'`, (中文(简体) ), `'buzz'`,或 `'fizzbuzz'`数字 :

```typescript
import {
    ConditionExpression,
    ConditionExpressionPredicate,
} from '@aws/dynamodb-expressions';

let equalsExpressionPredicate: ConditionExpressionPredicate = {
    type: 'Membership',
    values: ['fizz', 'buzz', 'fizzbuzz']
};

// you can also define an equality predicate with the `equals` helper method
import {inList} from '@aws/dynamodb-expressions';

equalsExpressionPredicate = inList('fizz', 'buzz', 'fizzbuzz');

// combine with a subject to create a valid condition expression
const equalsExpression: ConditionExpression = {
    ...equalsExpressionPredicate,
    subject: 'foo'
};
```

数字 `values` 数组可能是 [属性路径](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-paths), (中文(简体) ), a 一个 [属性值](https://npmcn.com/package/%40aws/dynamodb-expressions/#readme-attribute-values),或另一种类型。 如果后一种类型 将使用 `@aws/dynamodb-auto-marshaller` 软件包.

### 序列化条件表达式

要序列化条件表达式,请通过 `ConditionExpression` 对象和一个 实例 `ExpressionAttributes`。 。 。 .

## 表达式属性

Amazon DynamoDB 表达式被串行化为串行化 重要控制字符和保留词。 这个 `ExpressionAttributes` 对象将避开属性名称和属性值,以便在 任何表达 当一个完整的DynamoDB请求输入准备发送时,你可以 获取一个 `ExpressionAttributeNames` 财务报告和审定财务报表 `ExpressionAttributeValues` 形状 与输入一起发送 :

```typescript
import {
    AttributePath,
    AttributeValue,
    ExpressionAttributes,
} from '@aws/dynamodb-expressions';
const DynamoDb = require('aws-sdk/clients/dynamodb');

const attributes = new ExpressionAttributes();

// you can add a string attribute name
const escapedFoo = attributes.addName('foo');
// or a complex path
const escapedPath = attributes.addName('bar.baz[3].snap.crackle.pop');
// or an already parsed attribute path
attributes.addName(new AttributePath('path.to.nested.field'));

// raw JavaScript values added will be converted to AttributeValue objects
const escapedRaw = attributes.addValue(42);
// already marshalled values must be wrapped in an AttributeValue object
const escapedMarshalled = attributes.addValue(new AttributeValue({N: "42"}));

const client = new DynamoDb();
client.query({
    TableName: 'my_table',
    KeyConditionExpression: `${escapedFoo} = ${escapedRaw} AND ${escapedPath} = ${escapedMarshalled}`,
    ExpressionAttributeNames: attributes.names,
    ExpressionAttributeValues: attributes.values,
})
```

## 函数表达式

函数表达式代表 DynataB 将执行的指定函数 代表你们 第一个参数传递到 `FunctionExpression` 显示 函数名称并必须是字符串;所有后续参数都代表 要传递到函数的参数。 这些参数可能是: `AttributePath` (使函数评价部分 DynamoDB 文件到 函数的适用), `AttributeValue` (已经到期) 属性变量对象,或任意的 JavaScript 值(这些将转换) 编辑 `@aws/dynamodb-auto-marshaller` 软件包 `Marshaller`:

```typescript
import {
    AttributePath,
    ExpressionAttributes,
    FunctionExpression,
} from '@aws/dynamodb-expressions';

const expr = new FunctionExpression(
    'list_append', 
    new AttributePath('path.to.list'),
    'foo'
);
const attributes = new ExpressionAttributes();
// serializes as 'list_append(#attr0.#attr1.#attr2, :val3)'
const serialized = expr.serialize(attributes);
console.log(attributes.names); // {'#attr0': 'path', '#attr1': 'to', '#attr2': 'list'}
console.log(attributes.values); // {':val3': {S: 'foo'}}
```

## 数学表达式

数学表达式用于 `SET` 更新表达式的条款 从包含数字值的属性中添加或减去数字:

```typescript
import {MathematicalExpression} from '@aws/dynamodb-expressions';

const expr = new MathematicalExpression('version', '+', 1);
```

## 投影表达式

投影表达式告诉 DynamoDB 在获取中包含哪些属性 记录返回 `GetItem`, (中文(简体) ), `Query`,或 `Scan` 操作。 此库使用 `ProjectionExpression` 作为字符串和 `AttributePath` 对象.

## 更新表达式

更新表达式允许在 DynamoDB 中部分更新,以替换记录. 这一表述可能最多有四条,其中一条载有指示,规定: 记录中的值,其中包含从 记录,其中包含给一组添加值的指示,以及最后一个 包含从一组中删除值的指示.

```typescript
import {
    AttributePath,
    FunctionExpression,
    UpdateExpression,
} from '@aws/dynamodb-expressions';

const expr = new UpdateExpression();

// set a value by providing its key and the desired value
expr.set('foo', 'bar');
// you may also set properties in nested maps and lists
expr.set(
    'path.to.my.desired[2].property',
    new FunctionExpression(
        'list_append',
        new AttributePath('path.to.my.desired[2].property'),
        'baz'   
    )
);

// remove a value by providing its key or path
expr.remove('fizz.buzz.pop[0]');

// add a value to a set
expr.add('string_set', 'foo');

// delete a value from the same set
expr.delete('string_set', 'bar');
```

## 常见问题

### @aws/dynamodb-expressions 是什么？

Amazon DynamoDB 的可编译表达式对象

### 如何安装 @aws/dynamodb-expressions？

在项目目录运行 npm install @aws/dynamodb-expressions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：aws-sdk（^2\.7\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @aws/dynamodb-expressions 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @aws/dynamodb-expressions 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @aws/dynamodb-expressions 可以商用吗？

@aws/dynamodb-expressions 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @aws/dynamodb-expressions 的下载量有多少？

根据 npm 官方下载统计，@aws/dynamodb-expressions 在 2026/10/08 – 2026/11/06 这 30 天内被下载 149,601 次，日均约 4,987 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @aws/dynamodb-expressions 还在维护吗？

最新版本 0\.7\.3 发布于 2018/08/16（8 年前）；至今共发布 13 个版本，其中过去 12 个月发布了 0 个；首次发布于 2017/11/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。