realZachi/pg-jev

pg-jev — PostgreSQL内部での自然言語クエリ

pg-jevは、Jev (TypeSafe社製) と呼ばれるAIモデルを活用し、自然言語の条件を使用してテーブル内の行をフィルタリング、ランク付け、分類できるPostgreSQL拡張機能です。WHERE age > 40 AND country = 'France' と書く代わりに、WHERE jev(people, 'the name is European') と記述できます。

機能

自然言語で記述した条件に基づいて各行を判定するSQL関数を追加します。

• jev(row, 'condition') — true/falseを返し、WHERE 句で使用可能
• jev_prob(row, 'condition') — 行が条件に一致する確率 (0–1) を返す
• jev_choice(row, 'question', options) — リストから最も可能性の高いオプションを選択する (例: どのチームがこのチケットを処理すべきか)
• jev_score(row, 'question', levels) — 順序尺度でランク付けする (例: この製品の高級度はどの程度か)

これらは通常のSQL関数であるため、joins、GROUP BY、ORDER BY、LIMIT、その他の WHERE 述語と組み合わせて使用できます。

仕組み

1. テーブルに対して jev() を呼び出すと、拡張機能は read-ahead を開始します。物理的な順序でテーブルをストリーミングし、行をバッチ処理します。
2. 行は 1 APIリクエストあたり20行 にパックされ、1行につき1つのイエス/ノーの質問として共有状態に送られます。モデルは20個の質問すべてを並列で評価するため、リクエストごとのオーバーヘッドが償却されます (20行のバッチで1行あたり約175トークン、単一行では約435トークン)。
3. 複数のリクエストが永続的なHTTPS接続を通じて並行して実行されます。LIMIT に達するとread-aheadは停止し、同じ WHERE 句内のより安価な述語が先に実行されるため、拒否された行がAPIに送信されることはありません。
4. 回答はセッションごとに 行の内容と質問に基づいてキャッシュ されるため、クエリの再実行や確率によるソートは2回目以降ほぼ無料です。

2,000行のテーブルでの測定結果：初回実行は約3.5秒、APIコストは約$0.012。2回目以降は約50ms (キャッシュ済み)。新しい条件での LIMIT 3 は約0.6秒です。

設計上の選択

• インデックス、埋め込み、ベクトル列は不要 — 設計上、フルスキャンを行います。エグゼキュータが問い合わせるすべての行がAPIに送信されます。
• バッチサイズ20 — 意図的な精度のトレードオフです。実測テストでは、1〜20行のバッチは100%正確でしたが、40行では92〜98%、80行では77〜94%に低下しました。
• 生成テキストではなく校正済み確率 — モデルは各行に対して確率を返すため、曖昧なケースは0.5付近になり、しきい値を調整できます。
• ローカルサーバーサポート — jev.api_url をローカルのJev互換サーバーに向けることで、データがネットワーク外に出ることを防ぎ、行ごとの課金も発生しません。

インストールと要件

PostgreSQL 14〜17、plpython3u、スーパーユーザー権限、およびTypeSafe APIキーが必要です。スーパーユーザーや plpython3u が制限されているマネージドホスト (Supabase、Neon、RDSなど) では実行できません。PGXN、ソースコード、Docker、またはセットアップを自動化するAIエージェントスキルを通じてインストールしてください。

注意点

• 行の内容はサードパーティのAPIに送信されます (ローカルサーバーを実行しない場合)。共有できないデータには使用しないでください。
• 回答キャッシュはバックエンドセッションごとに存在し、一意の行/質問ペアが増えるにつれて増加します。jev_cache_clear() でリセット可能です。
• plpython3u は信頼されていない言語であるため、関数はサーバーのOS権限で実行されます。
• 共有デプロイメント向けに支出ガード (jev.max_rows_per_statement, jev.max_chars_per_statement) が存在します。

結論

pg-jevは、自然言語とSQLの間の実用的で洗練された架け橋です。正確な値ではなく、意味 (感情、カテゴリ、トーン) に基づいてデータをフィルタリングまたはランク付けしたい場合で、行ごとの少額のAPIコストとフルスキャンを受け入れられる場合に非常に有用です。