# @graffy/pg 中文文档

规范地址：https://npmcn.com/package/%40graffy/pg/

版本：0\.19\.7
npm 元数据更新时间：2026-09-16T04:47:08.184Z
中文译文更新时间：2026-11-17T04:02:49.605Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40graffy/pg
原文对照：https://npmcn.com/package/%40graffy/pg/?lang=original
项目主页：https://github.com/usegraffy/graffy#readme
源码仓库：https://github.com/usegraffy/graffy

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

- 包体积（解压后）：50.4 kB，26 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：4 个
- peer 依赖：pg ^8\.0\.0
- 首次发布：2020-12-22T13:05:37.292Z
- 最新版本发布：2026-09-16T04:47:07.820Z
- 近 30 天下载量：6898（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：170（近 12 个月 21 个）

## 中文简介

Graffy的标准Postgres模块. 此模块将 Postgres 表格作为 Graffy 子树挂载 .

## 安装

```sh
npm install @graffy/pg
```

也可以使用：`pnpm add @graffy/pg`、`yarn add @graffy/pg`、`bun add @graffy/pg`

## README

# 邮资

Graffy的标准Postgres模块. 此模块将 Postgres 表格作为 Graffy 子树挂载 .

要求 [页:1](https://github.com/brianc/node-postgres) 库将安装为对等依赖.

## 使用量

```js
import pg from '@graffy/pg';
import Graffy from '@graffy/core';
import link from '@graffy/link';

const store = new Graffy();
store.use(path, pg(options));
```

### 选项

-   `table`,表格的名称。 如未提供,则在 `path` 已使用。 这张表格必须存在.
-   `idCol`:要用作标识的列的名称。 默认为 `id`。此栏必须存在,必须是主要关键或有独特的制约.
-   `verCol`:存储Graffy版本编号的列名. 此栏必须存在,而且必须有 `DEFAULT` SQL 表达式定义 - 此表达式被评价来计算版本号. Graffy 版本必须单调地增加,所以这个表达式一般基于 `CURRENT_TIMESTAMP`。 。 。 .
-   `joins`: 其它有外来密钥引用本表中ID列的表格,我们希望用该其他表格的列通过"join"来过滤此表. 值是加入选项的关联名称地图 .
    -   合并名称是指在过滤表达式中用于引用合并表格的名称。 通常,这些是这些表格的名称.
    -   加入选项是具有可选属性的对象 `table`, (中文(简体) ), `idCol`, (中文(简体) ), `refCol` 财务报告和审定财务报表 `verCol`。 。 。 . `refCol` 是合并表格中引用此条目的列名称.
-   `connection`(单位:千美元) [页:1](https://github.com/brianc/node-postgres) 客户端或 Pool 对象( 建议), 或构建新 Pool 对象的参数 。 可选的.

### 数据库连接

Graffy Postgres 可以通过包含 a 来配置每个请求使用特定的 pg.client 对象 `pgClient` 属性。 这对执行交易,分出,行级安全等都有用.

若无 `pgClient` 用于特定的操作, Graffy Postgres 返回到“ 全球” pg. client 或 pg. 池对象定义 `connection` 参数。 如果没有 `connection` 参数被通过,将使用 PSQL 环境变量创建一个新的 pg.Pool.

## 数据模型

Graffy Postgres将每个属性解释为一列的名称,但 `$count`, (中文(简体) ), `$sum` 如下文汇总部分所述.

这也解释了 `$key` 用于指定过滤、排序、页码和聚合参数.

### 过滤器

查询过滤器基于JSON,有点像蒙戈DB.

1.  过滤表达式遵循 a **属性**, (中文(简体) ), **运算符**, (中文(简体) ), **价值** 秩序。 秩序。 值为平分值(字符串或数字).
2.  属性名称总是对象密钥. 可能跟点有关 `.`。 。 。 .
3.  操作员也被放置在物体中,并具有领先性 `$`。 。 。 .
4.  值为JSON值.
5.  对象中的多个属性结合 `AND`。数组中的项目与 `OR`。 。 。 .
6.  支持的操作员有:
    -   `$eq`: 在大多数情况下可选.
    -   `$lt`, (中文(简体) ), `$lte`, (中文(简体) ), `$gt`, (中文(简体) ), `$gte`区域
    -   `$re`, (中文(简体) ), `$ire`: Regex 匹配(大小写敏感和不敏感版本)
    -   `$text`: 全文搜索, 总是大小写不敏感
    -   `$not`: 修改其他过滤器或倒置一个条件
    -   `$and`, (中文(简体) ), `$or`: 组合条件; 在大多数情况下可选
    -   `$all`, (中文(简体) ), `$has`, (中文(简体) ), `$any`: 对集合的元素(列表或地图)应用条件

#### 基础

1.  `{ foo: 5 }` 财务报告和审定财务报表 `{ foo: { $eq: 5 } }` 编译到 SQL `foo = 5`。 。 。 .
2.  `{ foo: { $gt: 5, $lt: 6 } }` 变成 `foo > 5 AND foo < 6`。 。 。 .
3.  `{ foo: { $ire: '^wor.*' } }` 变成 `foo ~* "^wor.*"`。 。 。 .
4.  `{ foo: { $text: 'potatoes' } }` 变成 `foo @@ websearch_to_tsquery('potatoes')`。 。 。 . 为了成功, `foo` 必须是 TSVector 列.

#### 或者说

1.  `{ foo: [5, 6] }` 表示 _等价为5或等价为6_,编译器足够聪明,可以简化到 `foo IN (5, 6)`没有单独的美元.
2.  `{ foo: [ 5, { $gt: 6 } ] }` 变成 `foo = 5 OR foo > 6`
3.  `[ { foo: 6 }, { bar: 7 } ]` 变成 `foo = 6 OR bar = 7`

#### 没有

1.  `{ foo: { $not: 6 } }` 变成 `foo <> 6` (SQL 不等于运算符)
2.  `{ foo: { $not: [5, 6] }` 变成 `foo NOT IN (5, 6)`
3.  `{ foo: { $not: [ 5, { $gt: 6 } ] } }` 变成 `NOT (foo = 5 OR foo > 6)`

#### 逻辑

1.  默认,对象表示 `AND` 数组表示 `OR`数字 : `[ { foo: 5, bar: 6 }, { baz: 7, qux: 4 } ]` 变成 `(foo = 5 AND bar = 6) OR (baz = 7 AND qux = 4)`
    
2.  使用 `$and` 财务报告和审定财务报表 `$or` 操作员明确在两种上下文中使用任何结构:
    
    `{ $and: [ { $or: { foo: 5, bar: 6 } }, { $or: { baz: 7, qux: 4 } } ] }` 变成 `(foo = 5 OR bar = 6) AND (baz = 7 OR qux = 4)`。 。 。 .
    

#### 包含和包含的

1.  `{ tags: { $cts: ['foo', 'bar'] } }` 变成 `tags @> '{"foo","bar"}'`。 。 。 . 标记必须包含两者 _o_ 财务报告和审定财务报表 _栏_。请注意,此处的各种条件没有 `OR` 语义.
2.  `{ tags: { $ctd: ['foo', 'bar', 'baz'] } }` 变成 `tags <@ '{"foo","bar","baz"}'`。 。 。 . 每个标签必须是其中之一 _o_, (中文(简体) ), _栏_ 或者说 _巴兹_。 。 。 .

#### 联合

1.  `joinName: { ...expression }`, (中文(简体) ),

#### 页:1

1.  我们放下几个蒙戈DB操作员,同时保留其能力:
    -   `$ne`: 不使用$.
    -   `$in`: 使用一连串的数值;它是含$or和$eq的组合.
    -   `$nin`: 使用$not和一系列数值.
    -   `$exists`: 使用 `null` 或者说 `{ $not: null }`。邮资不区分 `undefined` 财务报告和审定财务报表 `null`,Graffy也一样(至少在这个背景下;它很复杂)
2.  葛来菲 `$has` 与 MongoDB 相当 `$all` (每个条件都由阵列中至少一个元素满足). 葛来菲 `$all` (数组的每个元素都符合条件)没有直接的MongoDB等同物,但可以表示为 `{ $not: { $elemMatch: { $not: (cond) } } }`
3.  Graffy对大小写不敏感regex有单独的运算符,在数据库对象中配置文本搜索地块而不是查询. 这让MongoDB的Regex `$options`,全文 `$language` 等 不必要的.
4.  Graffy 对 MongoDB 运算符没有等效值 `$type`, (中文(简体) ), `$expr`, (中文(简体) ), `$jsonSchema`, (中文(简体) ), `$where`, (中文(简体) ), `$mod`, (中文(简体) ), `$size` 和地理空间运营商.

### 顺序由

Graffy过滤器对象的根必须是对象. (使用时) `$or` (如果需要的话) 财产 `$order` 指定顺序。 它的值必须是一系列的顺序指定符,每个都可能是字符串属性名. 顺序是默认递增的; 属性名称可能与 `!` 切换到下降.

### 全文搜索

全文查询通常有三个要求:

-   过滤器 : `{ tsv: { $text: 'query' } }`。只返回匹配结果.
-   顺序 : `{ $order: [{ $text: ['tsv', 'query'] }], ... }`. 按相关性排序结果.
-   预测 : `{ tsv: { query: true } }`返回相匹配的文档片段.

在三个方面, `tsv` 是 TSVector 类型的计算列.

### 合计

在Graffy PG中,使用 `$group` 参数以$key 表示,特殊属性例如 `$count`, (中文(简体) ), `$sum` 在投影中显示. `$group` 也许 `true` 或数组.

考虑一个有栏目的书表 `authorId` 财务报告和审定财务报表 `copiesSold`我们想要在 `copiesSold` 栏.

#### 没有分组

假设我们想要我们数据库中所有书籍的总销量. 我们用 `$group: true`,例如:

```js
{
  books: {
  $key: { $group: true },
  $sum: { copiesSold: true }
}
```

注意如何指定要和的字段; 这样可以指定多个字段 .

一如既往,结果将反映查询:

```js
books: [{
  $key: { $group: true },
  $sum: { copiesSold: 12345 }
}]
```

#### 组合

现在我们假设我们要每个作者分别的总和. 由于我们可能有许多作者,我们可能需要对结果进行纠缠.

组合属性( 如 . `authorId`)也可以包括在投影中,这些值甚至可能被用于构建链接.

```js
{
  books: {
  $key: { $group: ['authorId'], $first: 30 },
  authorId: true,
  author: { namme: true }, // Link to ['users', authorId]
  $sum: { copiesSold: true }
}
```

#### 聚合函数

Graffy 支持以下集合函数.

-   `$count` 行; 仅指定为 `$count: true`,没有 任何田地下。 (所有其他集合函数需要指定字段. )
-   `$sum`, (中文(简体) ), `$avg`, (中文(简体) ), `$max`, (中文(简体) ), `$min`
-   `$card` (心率),或列中唯一值的数目

## 常见问题

### @graffy/pg 是什么？

Graffy的标准Postgres模块\. 此模块将 Postgres 表格作为 Graffy 子树挂载 \.

### 如何安装 @graffy/pg？

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

### @graffy/pg 支持 TypeScript 吗？

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

### @graffy/pg 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @graffy/pg 可以商用吗？

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

### @graffy/pg 的下载量有多少？

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

### @graffy/pg 还在维护吗？

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

