# @caitken-com/simple-sql-builder 中文文档

规范地址：https://npmcn.com/package/%40caitken-com/simple-sql-builder/

版本：1\.1\.0
npm 元数据更新时间：2023-10-12T07:32:56.599Z
中文译文更新时间：2026-11-09T18:48:30.493Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40caitken-com/simple-sql-builder
原文对照：https://npmcn.com/package/%40caitken-com/simple-sql-builder/?lang=original
项目主页：https://github.com/caitken-com/SimpleSqlBuilder#readme
源码仓库：https://github.com/caitken-com/SimpleSqlBuilder

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

- 包体积（解压后）：30.1 kB，4 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2023-10-08T07:03:48.938Z
- 最新版本发布：2023-10-12T07:32:56.380Z
- 近 30 天下载量：1856（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 0 个）

## 中文简介

简单的查询构建器

## 安装

```sh
npm install @caitken-com/simple-sql-builder
```

也可以使用：`pnpm add @caitken-com/simple-sql-builder`、`yarn add @caitken-com/simple-sql-builder`、`bun add @caitken-com/simple-sql-builder`

## README

# 简单的 SQL 构建器

生成可供执行的查询字符串, 内置参数从引用中跳出, 以及帮助的条款构建器 .

## 公共方法

-   选择
-   插入
-   删除
-   更新
-   加入
-   顺序
-   组
-   地点
-   拥有
-   限制
-   段落
-   从杰森
-   构建

### 选择

需要一个 _{对象}_ 带有下列密钥:

| 段落 | 类型 | 注释 |
| --- | --- | --- |
| 图表 | _{字符串/对象}_ | `'table_name'` 编号 : `{'table_name': 'alias'}` ^ |
| 栏 | _{字符串} \[_ | 要获取的列列表 |
| 查询 | _{对象}_ | \[可选 预建内置查询. ^`table` 此选项不需要 . `{'alias': 'pre-built query'}` |

回归自我,可连锁.

```
// Simple query example
let query = new SimpleSqlBuilder()
.select({
    'table': {'users': 'user'},
    'columns': [
        'user.first_name',
        'user.last_name',
        'YEAR(user.date_added) AS alumni'
    ]
})
.build();

/** Output:
SELECT `user`.`first_name`, `user`.`last_name`, YEAR(`user`.`date_added`) AS `alumni`
FROM `users` AS `user`
*/
---


// Inner query example
let inner = new SimpleSqlBuilder()
.select({
    'table': {'orders': 't'},
    'columns': [
        'MAX(t.date_added) AS date_added',
    ]
})
.where([
    ['t.type', '=', '?'],
])
.group([
    't.type',
])
.params([
    'Fish',
])
.build();

// Main/outer query
let query = new SimpleSqlBuilder()
.select({
    'query': {'joiner': inner},
    'columns': [
        'order.*',
    ]
})
.joins([
    {
        'type': 'inner',
        'table': { 'orders': 'order' },
        'using': [
            'date_added'
        ]
    }
])
.where([
    ['order.type', '=', '?'],
])
.group([
    'order.type'
])
.params([
    'Fish'
])
.build();

/* Output:
SELECT `order`.*
FROM (
    SELECT MAX(`t`.`date_added`) AS `date_added`
    FROM `orders` AS `t`
    WHERE `t`.`type` = 'Fish'
    GROUP BY `t`.`type`
) AS `joiner`
INNER JOIN `orders` AS `order` USING (`date_added`)
WHERE `order`.`type` = 'Fish'
GROUP BY `order`.`type`
*/
```

### 插入

需要一个 _{对象}_ 带有下列密钥:

| 段落 | 类型 | 注释 |
| --- | --- | --- |
| 图表 | _{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么_ | `'table_name'` |
| 栏 | _{对象}_ | `{column: value}` 双对 |
| 复制 | _{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么_ | \[可选 更新重复条款 . **注意: 字符串未脱出** |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.insert({
    'table': 'users',
    'columns': {
        'first_name', '?',
        'last_name', '?',
        'age': '?'
    },
    'duplicates': 'age = age + 1'
})
.params([
    'John',
    'Doe',
    30
]);
```

### 删除

需要一个 _{对象}_ 带有下列密钥:

| 段落 | 类型 | 注释 |
| --- | --- | --- |
| 图表 | _{字符串/对象}_ | `'table_name'` 编号 : `{'table_name': 'alias'}` |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.delete({
    'table': {'users': 'user'}
})
.where([
    ['user.id','=','?'],
])
.params([
    47,
]);
```

### 更新

需要一个 _{对象}_ 带有下列密钥:

| 段落 | 类型 | 注释 |
| --- | --- | --- |
| 图表 | _{字符串/对象}_ | `'table_name'` 编号 : `{'table_name': 'alias'}` |
| 栏 | _{对象}_ | `{column: value}` 双对 |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.update({
    'table': {'users': 'user'},
    'columns': {
        'age': '?'
    }
})
.where([
    ['user.id','=','?'],
])
.params([
    47,
    30,
]);
```

### 加入

需要一个 _{对象 \[\]}_ 带有下列密钥:

| 段落 | 类型 | 注释 |
| --- | --- | --- |
| 类型 | _{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么_ | `inner` 编号 : `outer` 编号 : `left` 编号 : `right` 编号 : `cross` |
| 图表 | _{字符串/对象}_ | `'table_name'` 编号 : `{'table_name': 'alias'}` |
| 条件 | _\[阵列\]_ | @ 见 `where` 需要更多信息 ^ |
| 使用 | _{字符串} \[_ | \[可选 内部查询的列列表 。 ^`conditions` 此选项不需要 . |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.select({
    'table': {'users': 'user'},
    'columns': ['user.*']
})
.joins([
    {
        'type': 'left',
        'table': {'orders': 'order'},
        'conditions': [
            ['order.user_id', '=', 'user.id']
        ]
    },
    // Repeat for each join...
]);
```

### 顺序

需要一个 _\[阵列\]_ 联 合 国 `strings` 或者说 `objects`数字 :

| 类型 | 注释 |
| --- | --- |
| _{字符串 \[\] / 对象 \[\]}_ | `'alias.column'` 编号 : `{'alias.column': 'asc' / 'desc'}` |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.order([
    'user.id',
    {'user.first_name': 'desc'},
]);
```

### 组

需要一个 _\[阵列\]_ 联 合 国 `strings`数字 :

| 类型 | 注释 |
| --- | --- |
| _{字符串} \[_ | `'alias.column'` |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.group([
    'user.age',
    'user.last_name',
]);
```

### 地点

需要一个 _\[阵列\]_ 下列任何条件:

| 类型 | 注释 |
| --- | --- |
| _\[阵列\]_ | `[column, operator, value]` 所有运算符见下文. |
| _{对象}_ | `{or / and: []}` 有关键词的关闭 `or` 或者说 `and` 以组合各种条件. |
| _{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么_ | 允许高级 SQL 函数 . **注意: 字符串没有逃脱 .** |

回归自我,可连锁.

```
let query = new SimpleSqlBuilder()
.where([
    ['user.active', '=', true],
    {
        'or': [
            ['user.first_name', '=', '?'],
            ['user.last_name', '=', '?'],
        ]
    },
])
.params([
    'John',
    'Doe'
]);

// Output: WHERE `user`.`active` = 1 AND (`user`.`first_name` = 'John' OR `user`.`last_name` = 'Doe')
```

#### 运算符 :

-   `=` 平等无相. `['user.age', '=', '?']`。 。 。 .
-   `<=` 少或等为相. `['user.age', '<=', '?']`。 。 。 .
-   `>=` 超过或等相. `['user.age', '>=', '?']`。 。 。 .
-   `<` 少过. `['user.age', '<', '?']`。 。 。 .
-   `>` 超过. `['user.age', '>', '?']`。 。 。 .
-   `!=` 不相等义. `['user.age', '!=', '?']`。 。 。 .
-   `<>` 不相等义. `['user.age', '<>', '?']`。 。 。 .
-   `is` _通常使用值为_ `null`。 。 。 . `['user.age', 'is', null]`。 。 。 .
-   `is not` _通常使用值为_ `null`。 。 。 . `['user.age', 'is not', null]`。 。 。 .
-   `between` 价值必须是 _数组_ 联 合 国 `["start", "end"]` 数值. `['user.age', 'between', ['?','?']]`。 。 。 .
-   `in` 价值必须是 _\[阵列\]_ `['user.age', 'in', ['?','?','?']]`。 。 。 .
-   `not in` 价值必须是 _\[阵列\]_ `['user.age', 'not in', ['?','?','?']]`。 。 。 .
-   `contains` 执行 a `LIKE` 列值的条件 _包含_ 给定值 `value`。 。 。 . `['user.age', 'contains', '?']`。 。 。 .
-   `begins` 执行 a `LIKE` 列值的条件 _开始_ 给定 `value`。 。 。 . `['user.age', 'beings', '?']`。 。 。 .
-   `ends` 执行 a `LIKE` 列值的条件 _结束_ 给定 `value`。 。 。 . `['user.age', 'ends', '?']`。 。 。 .

### 拥有

需要一个 _\[阵列\]_ 条件 @ 见 `where` 更多信息.

回归自我,可连锁.

### 限制

需要一个 _{数字} /{阵列}_数字 : `10` 编号 : `[offset, limit]`

回归自我,可连锁.

```
// Limit
let query = new SimpleSqlBuilder()
.limit(10);

---

// Offset, limit
let query = new SimpleSqlBuilder()
.limit([100, 15]);
```

### 段落

需要两个 _\[阵列\]_ 价值,或 _{对象}_ 联 合 国 `key:value` 双人.

回归自我,可连锁.

```
// Numeric array of params
let query = new SimpleSqlBuilder()
.where([
    ['user.first_name', '=', '?'],
    ['user.age', '=', '?'],
    ['user.nickname', '=', '?'],
])
.params([
    'John',
    30,
    'John',
]);

---

// Placeholder key-value params
let query = new SimpleSqlBuilder()
.where([
    ['user.first_name', '=', '?:name'],
    ['user.age', '=', '?:age'],
    ['user.nickname', '=', '?:name'],
])
.params({
    'name': 'John',
    'age': 30
});
```

### 从杰森

静态方法 _{\\FN黑体\\FS22\\BORD1\\SHAD0\\3AHBE\\4AH00\\FSCX67\\FSCY66\\2CHFFFFFF\\3CH808080}你觉得呢_ 与任何 _高于公共方法_ 作为密钥并返回输出 `build` 方法.

回返 _{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么_ 完成的SQL语句.

```
let query = SimpleSqlBuilder.fromJson({
    'select': {
        'table': {'users': 'user'},
        'columns': ['user.*']
    },
    'where': [
        ['user.first_name', '=', '?'],
    ],
    'params': [
        'John'
    ],
    'limit': 10
});

console.log(query);

// Output: SELECT `user`.* FROM `users` AS `user` WHERE `user`.`first_name` = 'John' LIMIT 10
```

### 构建

回返 _{\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}你来干什么_ 完成的SQL语句.

```
let query = new SimpleSqlBuilder()
.select({
    'table': {'users': 'user'},
    'columns': ['user.*']
})
.where([
    ['user.first_name', '=', '?'],
])
.limit(10)
.params([
    'John',
])
.build();

console.log(query);

// Output: SELECT `user`.* FROM `users` AS `user` WHERE `user`.`first_name` = 'John' LIMIT 10
```

## 常见问题

### @caitken-com/simple-sql-builder 是什么？

简单的查询构建器

### 如何安装 @caitken-com/simple-sql-builder？

在项目目录运行 npm install @caitken-com/simple-sql-builder，或使用 pnpm add / yarn add / bun add。

### @caitken-com/simple-sql-builder 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/caitken-com\_\_simple-sql-builder 是否存在。

### @caitken-com/simple-sql-builder 支持 ESM 还是 CommonJS？

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

### @caitken-com/simple-sql-builder 可以商用吗？

@caitken-com/simple-sql-builder 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @caitken-com/simple-sql-builder 的下载量有多少？

根据 npm 官方下载统计，@caitken-com/simple-sql-builder 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,856 次，日均约 62 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @caitken-com/simple-sql-builder 还在维护吗？

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