realZachi/pg-jev

Ask your Postgres tables questions in plain language. A PostgreSQL extension powered by TypeSafe's 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 술어와 함께 사용할 수 있습니다.

작동 원리

테이블에서 jev()를 호출하면 확장 프로그램은 read-ahead를 시작합니다. 물리적 순서대로 테이블을 스트리밍하며 행을 배치 처리합니다.
행은 API 요청당 20개씩 묶여 단일 공유 상태로 전송되며, 행당 하나의 예/아니오 질문이 포함됩니다. 모델은 20개의 질문을 병렬로 평가하므로 요청당 오버헤드가 상쇄됩니다 (20개 배치 시 행당 약 175 토큰, 단일 행 시 약 435 토큰).
여러 요청이 지속적인 HTTPS 연결을 통해 동시에 실행됩니다. LIMIT에 도달하면 read-ahead가 중지되며, 동일한 WHERE 절 내의 더 저렴한 술어가 먼저 실행되므로 거부된 행은 API로 전송되지 않습니다.
답변은 세션별로 행 내용과 질문을 기준으로 캐시되므로, 쿼리를 다시 실행하거나 확률로 정렬하는 작업은 두 번째부터 거의 비용이 들지 않습니다.

2,000개 행 테이블에서의 측정 결과: 첫 실행 시 약 3.5초, API 비용 약 $0.012; 두 번째 실행 시 약 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 비용과 전체 스캔을 감수할 의향이 있다면 매우 유용합니다.