Powierzchnia zapytań (OSL-SQL)

POST /osl/query to jedyny endpoint konsumpcji. Analityka ustrukturyzowana, metryki, nadzorowany retrieval wektorowy i trawersacja grafu — wszystko wyrażane jest tutaj; nie uczysz się pięciu powierzchni, by odczytać domenę.

POST /osl/query
Authorization: Bearer <jwt>           # attested delegation chain, see Authentication
Content-Type: application/json

Ciało to jeden z trzech wzajemnie wykluczających się kształtów (ich mieszanie to 400 E0513); wszystkie trzy przechodzą przez ten sam nadzorowany szew i współdzielą jeden request_id:

Ciało	Czym jest
{ "osql": "…" }	OSL-SQL — semantyczny dialekt SQL (kanoniczna powierzchnia)
{ "sql": "…" }	Surowy, tylko-do-odczytu SELECT nad allowlistą tenanta (wycinek SQL)
{ "metrics": […], "group_by": […], … }	Zapytanie o metryki w stylu MetricFlow

Jeden endpoint, jedna algebra

Ujednolicony /osl/query zastępuje dawne endpointy /osl/retrieve, /osl/joint/resolve i /osl/traverse (teraz usunięte). Każdy z nich to forma OSL-SQL. To właśnie czyni zdanie „OSL to jedyna warstwa konsumpcji“ dosłownie prawdziwym.

OSL-SQL

osql to semantyczny dialekt SQL. Nazywa wyłącznie obiekty semantyczne — osl.entities.<model> i zadeklarowane kolumny, albo funkcje tabelaryczne RETRIEVE(...) / TRAVERSE(...). Nigdy nie nazywa fizycznej tabeli ani surowej kolumny.

Obniżanie jest granicą bezpieczeństwa

Silnik parsuje osql (przez sqlglot, dialekt trino) i obniża go do zamkniętego IR operatorów — deterministycznej drabiny, nad którą egzekwuje model nadzoru. Obniżanie jest totalne i default-deny: każda konstrukcja, która nie obniża się do znanego węzła IR, jest odrzucana.

Lower(), nie parser, nie allowlista

• Allowlista SQL jest niezmieniona — nigdy nie jest uczona akceptowania funkcji tabelarycznych. RETRIEVE/TRAVERSE nigdy do niej nie docierają jako SQL; obniżają się do węzłów IR kierowanych do nadzorowanych resolverów.
• Do Trino serializowane jest tylko czysto strukturalne poddrzewo, nazywające wyłącznie iceberg.curated.*. Ta noga jest nadzorowana przez ten sam szew, dosłownie, co ręcznie napisane {sql} — więc dowód bezpieczeństwa obejmuje ją bez zmian.
• Zakazane wszędzie: funkcje okna, CTE, LATERAL/UNNEST/PIVOT, podzapytania skorelowane, funkcje spoza allowlisty, więcej niż jedna noga funkcji tabelarycznej, funkcja tabelaryczna zagnieżdżona wewnątrz skalara. Wszystko → 400 E0511.

Pięć form

lower() klasyfikuje każde zapytanie do dokładnie jednej formy i waliduje jego gramatykę:

Ustrukturyzowane

SELECT segment, COUNT(*) AS n
FROM osl.entities.Customer
WHERE country IN ('ES','FR','DE')
GROUP BY segment
ORDER BY n DESC
LIMIT 100

Obniża się do to_trino() → nadzorowany szew SQL. Joiny między encjami ustrukturyzowanymi są dozwolone tylko jako equijoin na zapieczętowanym kluczu (patrz niżej).

RETRIEVE

SELECT SUMMARIZE(text) AS summary, score
FROM RETRIEVE(facet => 'meeting_transcripts',
              query => 'european equity exposure',
              top_k => 5)

Obniża się do nadzorowanego magazynu Lance + retrievalu. Goła kolumna przechodzi bez zmian; <op>(col) w SELECT to operator projekcji.

TRAVERSE

SELECT concepto, amount_eur
FROM TRAVERSE(anchor => 'customer',
              target => 'orders',
              keys   => ('c-anna', 'c-bruno'))

Obniża się do nadzorowanej trawersacji L2 od kluczy kotwicy (skok po skoku, ograniczona kardynalność + dedup).

Joint (rekord)

SELECT name, segment, recent_meeting_topics
FROM osl.entities.Customer
WHERE customer_id IN ('9c1e…f04a', 'e4f8…2a91')

Forma „rekordowa“ (entity-first): kolumny ustrukturyzowane + dowody z Lance + atrybuty derywowane dla podanych kluczy, w jednym rozwiązaniu.

Cross-modalne

SELECT x.segment, r.text, r.score
FROM osl.entities.Customer x
JOIN RETRIEVE(facet => 'meeting_transcripts',
              query => 'churn risk') r
  ON x.customer_id = r.customer_id

„Relacja to filtr“: najpierw uruchamia się RETRIEVE, jego klucze wstępnie filtrują nogę strukturalną, a potem hash join w komórce na zapieczętowanym kluczu. Patrz niżej.

R3 jest niewyrażalne, nie blokowane

Jedynym węzłem cross-relacyjnym jest equijoin, którego ON to skalarna równość na zapieczętowanym kluczu encji (entity_key_columns modelu albo pole scalar_indexed fasety) na obu nogach. Każdy inny JOIN … ON → 400 E0514.

Nie istnieje składnia, która przekazałaby drugi argument relacyjny operatorowi podobieństwa lub LLM — semantyczny join relacja×relacja w query time (nie-cel R3) jest strukturalną własnością gramatyki, a nie blocklistą do utrzymywania.

Join cross-modalny — wykonanie

X JOIN RETRIEVE(...) ON X.k = R.k to nie jest relacyjny join dwóch fizycznych tabel. Wykonuje się tak:

1. RETRIEVE (nadzorowany) → fragmenty, każdy niosący swój zdenormalizowany klucz.
2. Bramka jawności → wartości kluczy albo odmowa (403 E0515).
3. Prefiltr strukturalny: … WHERE k IN (<keys>) → to_trino → nadzorowany SQL (lista IN jest budowana konwersją literałów sqlglot — odporna na injection).
4. Hash join w komórce na zapieczętowanym kluczu, projektujący kolumny każdej nogi.

Bramka cross-modalna fail-closed (E0515)

Zanim odczyta nogę strukturalną, silnik dowodzi, że klucz joina jest jawny (cleartext) dla podmiotu w nodze RETRIEVE — rozstrzygane wyłącznie na podstawie obserwowalnego, nadzorowanego wyjścia (redacted_fields / sentinel ⟦redacted⟧ / brak), nigdy ze snapshotu polityki. Zamaskowany klucz nigdy nie skoreluje się z jawnym kluczem fragmentu.

Operatory projekcji

W formie RETRIEVE <op>(col) w SELECT to operator projekcji (RFC 0004). Są to mapy unarne — nigdy join.

Klasa	Operatory	Działa na	Gdy brak
Encoder (deterministyczny)	SIMILARITY, CLASSIFY, TAG, RANK, DEDUP, OUTLIER, CLUSTER	Na embeddingach już w chunku	—
Decoder (inferencja) wymaga LLM	EXTRACT, SUMMARIZE, SCORE, GENERATE, COMPLETE	Backend LLM	503 E0521

Bezpieczeństwo dostępu zachowane

Projekcja operuje na już-nadzorowanym wejściu, więc nigdy nie może rozszerzyć dostępu. Operacje encoder są deterministyczne; operacje decoder są niedeterministyczne (to inferencja, nie naruszenie). Operacja generatywna, której wyjście nie przejdzie walidacji → 400 E0522.

Ciała raw SQL i MetricFlow

{ "sql": "<SELECT>" } to tylko-do-odczytu SELECT walidowany względem allowlisty tenanta, z zastosowanym punktem egzekwowania polityk (filtry wierszy + projekcja ze złożonego snapshotu). { "metrics": …, "group_by": … } podąża za semantyką MetricFlow. Oba współdzielą ten sam nadzorowany szew co osql.

Status rozwiązywania MetricFlow

Resolver MetricFlow → SQL jest wciąż planowane; ciało z metrics, ale bez sql/osql zwraca 422 E1001. Nadzorowany wycinek SQL ({sql}) i osql są zaimplementowane.

Kody statusu

Kod	Znaczenie
200	Sukces
400	Zniekształcone / poza gramatyką (E0511), obiekt niezadeklarowany (E0512), ciało miesza kształty (E0513), JOIN nie na zapieczętowanym kluczu (E0514), puste sql (E0246)
403	Deny PDP (E2101/E2102), klucz cross-modalny niejawny (E0515), obiekt poza allowlistą (E0512)
422	Poprawne, ale nierozwiązywalne — np. MetricFlow jeszcze niezaimplementowany (E1001)
503	Brak snapshotu PDP (E2001, fail-closed), operacja decoder bez backendu LLM (E0521)
502	Niepowodzenie wykonania Trino (E0510)

Zobacz Błędy i kody statusu po pełny envelope.

Dostęp i zdolnościJak łańcuch delegacji podmiotu, nadania i wersje redakcji decydują, co może zobaczyć zapytanie — fail-closed z konstrukcji.

Status specyfikacji

Powierzchnia OSL-SQL to RFC 0005 (Status: Draft, 2026-07-02); planer, wykonawca i wszystkie pięć form są zaimplementowane. RFC 0002 (semantic_match) jest Zastąpione — retrieval jest teraz źródłem relacji RETRIEVE, a nie predykatem WHERE.