pg-jev快速入门：4步安装并跑通第一条自然语言查询（附完整SQL示例）

• 人工智能
• AI 应用
• 大模型
• 后端

pg-jev 是一个 PostgreSQL 自然语言查询扩展：安装后，你可以直接在WHERE子句里写一句大白话，让 AI 模型逐行判断哪些数据符合条件。本文带你 4 步完成 pg-jev 的安装与配置，并跑通第一条自然语言查询，文末附完整 SQL 示例和常用函数速查表。

它到底能干什么？

传统 SQL 里，"找出名字听起来像欧洲人的用户"这种需求只能靠模糊匹配或手写一堆规则。pg-jev 的思路完全不同：

• 不建索引、不做 embedding、不需要向量列——每一行都由 TypeSafe 的 Jev 模型（一个返回"校准概率"而非生成文本的 System One 模型）来判断是否满足条件；
• jev()是一个普通布尔函数，可以像任何 SQL 谓词一样与AND、JOIN、GROUP BY、LIMIT、ORDER BY自由组合；
• 查询时模型会分批（默认 20 行/请求）、并发地"审问"数据行，并有会话级缓存，重复查询几乎免费。

项目说明可参考 README.md，扩展的全部 SQL 实现就在 sql/jev--0.2.1.sql。

安装前：环境要求一览

⚠️ 注意：Supabase、Neon、RDS 等托管服务若不提供超级用户或plpython3u，无法运行 pg-jev。

第 1 步：三选一安装扩展

根据场景选一条路径即可，推荐新手直接走方案 A。

方案 A：Docker 一键起环境（最快）

仓库自带 Dockerfile，一条命令构建好"PostgreSQL + plpython3 + jev"的镜像：

docker build -t pg-jev . docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pw -e TYPESAFE_API_KEY=your-key pg-jev

方案 B：从 PGXN 安装（生产推荐）

pip install pgxnclient pgxn install jev

pgxn install jev会从 PGXN 下载发行版并对 PATH 上的pg_config执行make install。若服务器的pg_config不在 PATH，可加参数--pg_config=/path/to/pg_config或使用sudo。

方案 C：从源码构建

git clone https://gitcode.com/gh_mirrors/pg/pg-jev cd pg-jev make install

构建逻辑见 Makefile（基于 PGXS，纯 PL/Python 实现，没有 C 代码需要编译）。

第 2 步：创建扩展

以超级用户身份连接数据库，执行（CASCADE会自动把依赖的plpython3u一并创建）：

CREATE EXTENSION jev CASCADE;

扩展的元信息定义在 jev.control 中，当前版本为0.2.1，要求 PostgreSQL 14–17。

第 3 步：配置 API key

两种方式任选其一（详见 sql/jev--0.2.1.sql 顶部的设置注释）：

方式一：环境变量——在 PostgreSQL 服务端进程的环境里导出TYPESAFE_API_KEY（Docker 方案中已用-e传入）。

方式二：按会话或角色设置

SET jev.api_key = 'your-key'; -- 当前会话生效 ALTER ROLE analyst SET jev.api_key = 'your-key'; -- 对某个角色持久生效

第 4 步：跑通第一条自然语言查询

现在见证魔法时刻 ✨ 建一张小表，然后用大白话做过滤：

CREATE TABLE people (id int PRIMARY KEY, name text, country text); INSERT INTO people VALUES (1, 'Lukas Müller', 'Germany'), (2, 'Yuki Tanaka', 'Japan'), (3, 'Jean Dupont', 'France'), (4, 'Ana García', 'Spain'); -- 第一条自然语言查询：不用 LIKE，不用正则 SELECT * FROM people WHERE jev(people, 'the name is European');

完整 SQL 示例：三种常见玩法

① 按概率排序（找出"最可能"的行）

SELECT subject, jev_prob(tickets, 'the customer is angry') AS p FROM tickets ORDER BY p DESC LIMIT 20;

② 自动分类（让模型从选项中挑一个）

SELECT jev_choice(tickets, 'which team should handle this?', ARRAY['billing', 'technical', 'security', 'sales']) AS team, count(*) FROM tickets GROUP BY 1;

③ 分级打分（把语义映射到有序刻度上）

SELECT name, jev_score(products, 'how luxurious is this product?', ARRAY['budget', 'mid-range', 'premium', 'luxury']) AS luxury FROM products ORDER BY luxury DESC;

以上完整示例也可在回归测试 test/sql/01_basic.sql 中找到——它用一张cities表演示了谓词过滤、阈值、jev_score、jev_choice、缓存与开销防护等全部用法，配合 test/mock_api.py 这个确定性模拟 API 运行，不需要真实调用。

常用函数速查表 💡

写好查询的 3 个实用建议

1. 条件要具体：'the customer threatens to leave, dispute a charge, or take legal action'远好于'churn risk'——模型只回答你字面上问的那个问题。
2. 算术和精确匹配交给 SQL：让模型判断"语义"，日期计算、精确等值过滤仍写在普通 SQL 里，还能帮jev()减少请求的行数。
3. 控制花费：jev()本质是全表扫描，每行都会发给 API。共享部署可开启花费防护：SET jev.max_rows_per_statement = 1000;；行内容会发送到第三方 API，敏感数据慎用。

遇到问题？先查这些文件

到这里，你已经在 4 步内装好了 pg-jev，并掌握了"用一句话写 WHERE 子句"的完整姿势。下一条可以试试把jev_prob的结果和传统谓词组合起来：WHERE age > 40 AND jev(people, 'the name is European')——自然语言与传统 SQL，从此可以无缝混搭 🎉

• 人工智能
• AI 应用
• 大模型
• 后端