@graffy/pg

中文文档
0.19.7发布于 2026/09/16Apache-2.0TypeScriptES Module构建来源已验证近 30 天下载 6898

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

中文使用文档
文档目录8 节
  1. 使用量
  2. 选项
  3. 数据库连接
  4. 数据模型
  5. 过滤器
  6. 顺序由
  7. 全文搜索
  8. 合计

邮资

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

要求 页:1 库将安装为对等依赖.

使用量

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 客户端或 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,例如:

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

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

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

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

组合

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

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

{
  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 共发布 170 个版本,首次发布于 2020/12/22;过去 12 个月发布了 21 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.19.7latest2026/09/162 个月前
0.19.62026/08/173 个月前
0.19.52026/08/033 个月前
0.19.42026/06/304 个月前
0.19.32026/05/215 个月前
0.19.22026/05/176 个月前

其他发布通道:pre → 0.19.1-alpha.3。

关于 @graffy/pg 的常见问题

@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 和提交记录判断。