La superfície de query (OSL-SQL)

POST /osl/query és l’únic endpoint de consum. L’analítica estructurada, les mètriques, el retrieval vectorial governat i la travessa de grafs s’expressen tots aquí — no aprens cinc superfícies per llegir un domini.

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

El body és una de tres formes mútuament excloents (barrejar-les és 400 E0513); totes tres passen per la mateixa junta governada i comparteixen un request_id:

Body	Què és
{ "osql": "…" }	OSL-SQL — el dialecte SQL semàntic (la superfície canònica)
{ "sql": "…" }	Un SELECT de només lectura sobre l’allowlist del tenant (el slice SQL)
{ "metrics": […], "group_by": […], … }	Query de mètriques a l’estil MetricFlow

Un endpoint, una àlgebra

El /osl/query unificat substitueix els antics endpoints /osl/retrieve, /osl/joint/resolve i /osl/traverse (ara eliminats). Cadascun és una forma d’OSL-SQL. Això és el que fa que “OSL és l’única capa de consum” sigui literalment cert.

OSL-SQL

osql és un dialecte SQL semàntic. Anomena només objectes semàntics — osl.entities.<model> i columnes declarades, o les funcions de taula RETRIEVE(...) / TRAVERSE(...). Mai anomena una taula física ni una columna crua.

El lowering és la frontera de seguretat

El motor parseja osql (via sqlglot, dialecte trino) i el baixa a una IR d’operadors tancada — l’escala determinista sobre la qual aplica el model de governança. El lowering és total i default-deny: qualsevol construcció que no baixi a un node d’IR conegut es refusa.

Lower(), no el parser, no l'allowlist

• L’allowlist SQL és inalterada — mai se li ensenya a acceptar funcions de taula. RETRIEVE/TRAVERSE mai hi arriben com a SQL; baixen a nodes d’IR despatxats a resolutors governats.
• Només el subarbre purament estructural es serialitza a Trino, anomenant només iceberg.curated.*. Aquesta pota es governa per la mateixa junta, literalment, que un {sql} escrit a mà — així la prova de seguretat la cobreix sense canvis.
• Prohibit a tot arreu: funcions de finestra, CTEs, LATERAL/UNNEST/PIVOT, subqueries correlacionades, funcions fora de l’allowlist, més d’una pota de funció de taula, una funció de taula niada dins d’un escalar. Tot → 400 E0511.

Les cinc formes

lower() classifica cada query en exactament una forma i valida la seva gramàtica:

Estructurat

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

Baixa a to_trino() → la junta SQL governada. Els joins entre entitats estructurades només s’admeten com un equijoin de clau segellada (vegeu més avall).

RETRIEVE

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

Baixa al store Lance + retrieval governats. Una columna nua passa directament; un <op>(col) al SELECT és un operador de projecció.

TRAVERSE

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

Baixa a la travessa L2 governada des de les claus àncora (hop-by-hop, cardinalitat acotada + dedup).

Joint (registre)

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

La forma “registre” entity-first: columnes estructurades + evidència Lance + atributs derivats per a les claus donades, en una sola resolució.

Cross-modal

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

“La relació és un filtre”: RETRIEVE corre primer, les seves claus prefiltren la pota estructural, després un hash join in-cell sobre la clau segellada. Vegeu més avall.

R3 és inexpressable, no bloquejat

L’únic node cross-relacional és un equijoin l’ON del qual és una igualtat escalar sobre una clau d’entitat segellada (les entity_key_columns del model, o el camp scalar_indexed d’una faceta) a totes dues potes. Qualsevol altre JOIN … ON → 400 E0514.

No hi ha cap sintaxi que passi un segon argument relacional a un operador de similitud o LLM — un join semàntic relació×relació en temps de query (el no-objectiu R3) és una propietat estructural de la gramàtica, no una blocklist a mantenir.

El join cross-modal, executat

X JOIN RETRIEVE(...) ON X.k = R.k no és un join relacional de dues taules físiques. S’executa així:

1. RETRIEVE (governat) → passatges, cadascun portant la seva clau desnormalitzada.
2. Porta en clar → els valors de clau, o refusa (403 E0515).
3. Prefiltre estructurat: … WHERE k IN (<keys>) → to_trino → SQL governat (la llista IN es construeix amb la conversió de literals de sqlglot — segura contra injecció).
4. Hash join in-cell sobre la clau segellada, projectant les columnes de cada pota.

Porta cross-modal fail-closed (E0515)

Abans de llegir la pota estructural, el motor demostra que la clau de join està en clar per al subjecte a la pota RETRIEVE — decidit només a partir de la sortida governada observable (redacted_fields / el sentinella ⟦redacted⟧ / l’absència), mai a partir de l’snapshot de la política. Una clau emmascarada mai correlaciona amb una clau de passatge en clar.

Operadors de projecció

A la forma RETRIEVE, <op>(col) al SELECT és un operador de projecció (RFC 0004). Són mapes unaris — mai un join.

Classe	Operadors	Corre sobre	Si falta
Encoder (determinista)	SIMILARITY, CLASSIFY, TAG, RANK, DEDUP, OUTLIER, CLUSTER	Embeddings ja presents al chunk	—
Decoder (inferència) requereix LLM	EXTRACT, SUMMARIZE, SCORE, GENERATE, COMPLETE	Un backend LLM	503 E0521

Seguretat d'accés preservada

Una projecció opera sobre input ja governat, així que mai pot ampliar l’accés. Les ops encoder són deterministes; les ops decoder són no deterministes (això és inferència, no una bretxa). Una op generativa la sortida de la qual falla la validació → 400 E0522.

Bodies de SQL cru i MetricFlow

{ "sql": "<SELECT>" } és un SELECT de només lectura validat contra l’allowlist del tenant amb el punt d’aplicació de polítiques aplicat (row filters + projection des de l’snapshot compost). { "metrics": …, "group_by": … } segueix la semàntica de MetricFlow. Tots dos comparteixen la mateixa junta governada que osql.

Estat de la resolució MetricFlow

El resolutor MetricFlow → SQL encara està planificat; un body amb metrics però sense sql/osql retorna 422 E1001. El slice SQL governat ({sql}) i osql estan implementat.

Codis d’estat

Codi	Significat
200	Èxit
400	Malformat / fora de gramàtica (E0511), objecte no declarat (E0512), el body barreja formes (E0513), JOIN sense clau segellada (E0514), sql buit (E0246)
403	Deny de la PDP (E2101/E2102), clau cross-modal no en clar (E0515), objecte fora de l’allowlist (E0512)
422	Vàlid però no resoluble — p. ex. MetricFlow encara no implementat (E1001)
503	Falta l’snapshot de la PDP (E2001, fail-closed), op decoder sense backend LLM (E0521)
502	Fallada d’execució de Trino (E0510)

Vegeu Errors i codis d’estat per a l’envelope complet.

Accés i capacitatsCom la cadena de delegació d'un subjecte, els grants i les versions de redacció decideixen què pot veure una query — fail-closed per construcció.

Estat de la spec

La superfície OSL-SQL és RFC 0005 (Status: Draft, 2026-07-02); el planificador, l’executor i les cinc formes estan implementats. RFC 0002 (semantic_match) està Substituïda — el retrieval ara és la font de relació RETRIEVE, no un predicat WHERE.