====== PG-JEV ======

//Vytvořeno: **28.9.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/realZachi/pg-jev|PG-JEV]] je rozšíření pro PostgreSQL, které přidává funkce modelu Jev pro vyhodnocení, filtrování, řazení a klasifikaci řádků přirozeným jazykem. Dotaz nevyžaduje vektorový index, embeddingy ani vektorový sloupec; rozšíření předává celý řádek jako strukturovaný vstup do TypeSafe API.

===== Princip =====

Podmínka se předává funkci společně s řádkem. Například následující dotaz vybere z tabulky ''people'' osoby, jejichž jméno model vyhodnotí jako evropské:

<code sql>
SELECT * FROM people
WHERE jev(people, 'the name is European');
</code>

První vyhodnocení konkrétní kombinace tabulky a podmínky spustí read-ahead — rozšíření dopředu načítá řádky a odesílá je ve skupinách do API. U běžných tabulek čte řádky ve fyzickém pořadí pomocí TID rozsahů, u pohledů používá stránkování.

Výchozí dávka obsahuje 20 řádků na API požadavek. Parametr ''jev.concurrency'' má ve výchozím nastavení hodnotu 16 a určuje počet souběžných požadavků. Odpovědi ukládá cache v rámci backendové relace podle obsahu řádku.

===== Dostupné funkce =====

  * ''jev(row, condition [, threshold])'' vrací boolean hodnotu pro použití ve ''WHERE''.
  * ''jev_prob(row, condition)'' vrací pravděpodobnost v rozsahu 0 až 1.
  * ''jev_score'' a ''jev_score_norm'' vrací skóre podle zadaných uspořádaných úrovní.
  * ''jev_choice'' vybírá nejpravděpodobnější možnost.
  * ''jev_confidence'' a ''jev_eval'' zpřístupňují confidence a úplnou odpověď modelu.
  * ''jev_stats()'', ''jev_cache_clear()'' a ''jev_version()'' slouží ke kontrole statistik, vymazání cache a zjištění verze rozšíření.

===== Instalace =====

Rozšíření vyžaduje PostgreSQL ve verzích 14 až 17, jazyk ''plpython3u'', oprávnění superuživatele PostgreSQL a API klíč TypeSafe. Na hostovaných PostgreSQL službách bez superuživatele nebo ''plpython3u'', například Supabase, Neon a RDS, jej nelze provozovat.

Na Debianu nebo Ubuntu je podle dokumentace projektu potřeba nejprve nainstalovat balíček ''postgresql-plpython3-NN'', kde ''NN'' odpovídá hlavní verzi PostgreSQL.

==== Z PGXN ====

<code bash>
pip install pgxnclient
pgxn install jev
psql -c "CREATE EXTENSION jev CASCADE"
</code>

==== Ze zdrojových kódů ====

<code bash>
git clone https://github.com/realZachi/pg-jev.git && cd pg-jev
make install
psql -c "CREATE EXTENSION jev CASCADE"
</code>

==== Docker ====

Projekt obsahuje také Docker image. API klíč se předává proměnnou prostředí ''TYPESAFE_API_KEY''.

<code bash>
docker build -t pg-jev .
docker run -d -p 5432:5432 -e POSTGRES_PASSWORD=pw \
  -e TYPESAFE_API_KEY=your-key pg-jev
</code>

===== Nastavení =====

Konfigurace používá PostgreSQL GUC parametry. Lze je proto nastavit pomocí ''SET'', ''ALTER ROLE'', ''ALTER DATABASE'' nebo v souboru ''postgresql.conf''.

Důležité parametry zahrnují ''jev.api_key'', ''jev.model'', ''jev.concurrency'', velikost dávky, URL API, timeout a keepalive. Výchozí model je ''jev-latest''; lze použít i připnutou verzi, například ''jev-1.13.0''.

Rozšíření obsahuje limity ''jev.max_rows_per_statement'' a ''jev.max_chars_per_statement''. Po překročení omezí počet řádků nebo znaků odesílaných v rámci jednoho SQL příkazu. Tyto limity pomáhají chránit náklady na API.

===== Doporučení pro dotazy =====

Přesnou shodu, aritmetiku a práci s daty je vhodné nechat v SQL. Jev má řešit až sémantickou část dotazu. Levné SQL podmínky mají být před ''jev()'', aby se řádky vyřazené databází neposílaly do API.

<code sql>
SELECT * FROM people
WHERE country = 'CZ'
  AND jev(people, 'the person works in a technical role');
</code>

Pokud tabulka obsahuje mnoho sloupců, je vhodné vytvořit pohled jen s poli potřebnými pro rozhodnutí. Zmenší se tím vstup odesílaný modelu.

''LIMIT'' může zastavit read-ahead dříve, než rozšíření vyhodnotí celou tabulku. Nejde ale o indexové vyhledávání: rozšíření zpracovává řádky, které PostgreSQL executor vyžádá pro vyhodnocení dotazu.

===== Omezení a bezpečnost =====

Obsah vyhodnocovaných řádků odchází do API třetí strany. Před nasazením je proto potřeba vyhodnotit, zda data smějí opustit databázový server.

Cache není sdílená mezi backendovými relacemi. Anonymní typ ''record'', který může vzniknout například z některých poddotazů nebo CTE, neumí read-ahead dávkovat a rozšíření jej vyhodnocuje po jednom řádku.

''plpython3u'' je nedůvěryhodný jazyk PostgreSQL. Rozšíření může vytvořit jen superuživatel a jeho funkce běží s oprávněními operačního systému procesu databázového serveru. Instalace proto vyžaduje stejnou obezřetnost jako jiný kód běžící přímo u PostgreSQL.

===== Vývoj a testování =====

Regresní testy projektu používají deterministickou mock API, takže nemají volat živé API.

<code bash>
make docker-test
make installcheck
</code>

Projekt je licencovaný pod PostgreSQL License.

===== Zdroje =====

  * [[https://github.com/realZachi/pg-jev|PG-JEV – zdrojové kódy, instalace, konfigurace a omezení]]