Die Query-Oberfläche (OSL-SQL)

POST /osl/query ist der einzige Konsum-Endpoint. Strukturierte Analytik, Metriken, gesteuertes Vektor-Retrieval und Graph-Traversierung werden alle hier ausgedrückt — du lernst nicht fünf Oberflächen, um eine Domain zu lesen.

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

Der Body ist eine von drei wechselseitig ausschließenden Formen (sie zu mischen ist 400 E0513); alle drei laufen durch dieselbe gesteuerte Naht und teilen sich eine request_id:

Body	Was es ist
{ "osql": "…" }	OSL-SQL — der semantische SQL-Dialekt (die kanonische Oberfläche)
{ "sql": "…" }	Ein rohes read-only SELECT über die Allowlist des Tenants (der SQL-Slice)
{ "metrics": […], "group_by": […], … }	MetricFlow-artige Metrik-Query

Ein Endpoint, eine Algebra

Der vereinheitlichte /osl/query ersetzt die alten Endpoints /osl/retrieve, /osl/joint/resolve und /osl/traverse (jetzt gelöscht). Jeder ist eine Form von OSL-SQL. Genau das macht „OSL ist die einzige Konsumschicht“ buchstäblich wahr.

OSL-SQL

osql ist ein semantischer SQL-Dialekt. Er benennt nur semantische Objekte — osl.entities.<model> und deklarierte Spalten oder die Table-Functions RETRIEVE(...) / TRAVERSE(...). Er benennt niemals eine physische Tabelle oder eine rohe Spalte.

Das Lowering ist die Sicherheitsgrenze

Die Engine parst osql (via sqlglot, trino-Dialekt) und senkt es zu einem geschlossenen Operator-IR ab — die deterministische Leiter, über die das Governance-Modell durchsetzt. Das Lowering ist total und default-deny: Jedes Konstrukt, das nicht zu einem bekannten IR-Knoten absenkt, wird abgelehnt.

Lower(), nicht der Parser, nicht die Allowlist

• Die SQL-Allowlist ist unverändert — ihr wird niemals beigebracht, Table-Functions zu akzeptieren. RETRIEVE/TRAVERSE erreichen sie nie als SQL; sie senken zu IR-Knoten ab, die an gesteuerte Resolver dispatcht werden.
• Nur der rein strukturelle Teilbaum wird zu Trino serialisiert und benennt nur iceberg.curated.*. Dieses Bein wird von derselben Naht, wortgleich, gesteuert wie ein handgeschriebenes {sql} — der Sicherheitsbeweis deckt es also ohne Änderung ab.
• Überall verboten: Window-Functions, CTEs, LATERAL/UNNEST/PIVOT, korrelierte Subqueries, nicht-allowgelistete Funktionen, mehr als ein Table-Function-Bein, eine in einem Skalar verschachtelte Table-Function. Alle → 400 E0511.

Die fünf Formen

lower() klassifiziert jede Query in genau eine Form und validiert ihre Grammatik:

Strukturiert

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

Senkt zu to_trino() ab → die gesteuerte SQL-Naht. Joins zwischen strukturierten Entities sind nur als Equijoin auf versiegeltem Schlüssel erlaubt (siehe unten).

RETRIEVE

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

Senkt zum gesteuerten Lance-Store + Retrieval ab. Eine bloße Spalte wird durchgereicht; ein <op>(col) im SELECT ist ein Projektionsoperator.

TRAVERSE

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

Senkt zur gesteuerten L2-Traversierung von den Anker-Schlüsseln ab (Hop für Hop, beschränkte Kardinalität + Dedup).

Joint (Datensatz)

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

Die Entity-first-„Record“-Form: strukturierte Spalten + Lance-Evidenz + abgeleitete Attribute für die gegebenen Schlüssel, in einer Auflösung.

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

„Die Relation ist ein Filter“: RETRIEVE läuft zuerst, seine Schlüssel vorfiltern das strukturelle Bein, dann ein In-Cell-Hash-Join auf dem versiegelten Schlüssel. Siehe unten.

R3 ist nicht ausdrückbar, nicht blockiert

Der einzige cross-relationale Knoten ist ein Equijoin, dessen ON eine skalare Gleichheit auf einem versiegelten Entity-Schlüssel ist (die entity_key_columns des Modells oder das scalar_indexed-Feld einer Facette) auf beiden Beinen. Jedes andere JOIN … ON → 400 E0514.

Es gibt keine Syntax, die einem Ähnlichkeits- oder LLM-Operator ein zweites relationales Argument übergibt — ein relation×relation-semantischer Join zur Query-Zeit (das Nicht-Ziel R3) ist eine strukturelle Eigenschaft der Grammatik, keine zu pflegende Blocklist.

Der cross-modale Join, ausgeführt

X JOIN RETRIEVE(...) ON X.k = R.k ist kein relationaler Join zweier physischer Tabellen. Er läuft als:

1. RETRIEVE (gesteuert) → Passagen, jede trägt ihren denormalisierten Schlüssel.
2. Klartext-Gate → die Schlüsselwerte, oder Ablehnung (403 E0515).
3. Strukturierter Prefilter: … WHERE k IN (<keys>) → to_trino → gesteuertes SQL (die IN-Liste wird mit sqlglot-Literal-Konvertierung gebaut — injection-sicher).
4. In-Cell-Hash-Join auf dem versiegelten Schlüssel, projiziert die Spalten jedes Beins.

Fail-closed cross-modales Gate (E0515)

Bevor das strukturelle Bein gelesen wird, beweist die Engine, dass der Join-Schlüssel für das Subject im RETRIEVE-Bein Klartext ist — entschieden nur aus dem beobachtbaren gesteuerten Output (redacted_fields / das ⟦redacted⟧-Sentinel / Abwesenheit), niemals aus dem Policy-Snapshot. Ein maskierter Schlüssel korreliert niemals mit einem Klartext-Passagen-Schlüssel.

Projektionsoperatoren

In der RETRIEVE-Form ist <op>(col) im SELECT ein Projektionsoperator (RFC 0004). Sie sind unäre Abbildungen — niemals ein Join.

Klasse	Operatoren	Läuft	Falls fehlend
Encoder (deterministisch)	SIMILARITY, CLASSIFY, TAG, RANK, DEDUP, OUTLIER, CLUSTER	Auf Embeddings, die bereits im Chunk sind	—
Decoder (Inferenz) braucht LLM	EXTRACT, SUMMARIZE, SCORE, GENERATE, COMPLETE	Ein LLM-Backend	503 E0521

Zugriffssicherheit bleibt erhalten

Ein Projektionsoperator operiert auf bereits gesteuertem Input, kann also den Zugriff niemals erweitern. Encoder-Ops sind deterministisch; Decoder-Ops sind nicht-deterministisch (das ist Inferenz, kein Bruch). Ein generativer Op, dessen Output die Validierung nicht besteht → 400 E0522.

Rohe SQL- & MetricFlow-Bodies

{ "sql": "<SELECT>" } ist ein read-only SELECT, validiert gegen die Allowlist des Tenants, mit angewandtem Policy Enforcement Point (Zeilenfilter + Projektion aus dem komponierten Snapshot). { "metrics": …, "group_by": … } folgt der MetricFlow-Semantik. Beide teilen sich dieselbe gesteuerte Naht wie osql.

Status der MetricFlow-Resolution

Der MetricFlow → SQL-Resolver ist noch geplant; ein Body mit metrics, aber ohne sql/osql gibt 422 E1001 zurück. Der gesteuerte SQL-Slice ({sql}) und osql sind implementiert.

Statuscodes

Code	Bedeutung
200	Erfolg
400	Fehlerhaft / außerhalb der Grammatik (E0511), nicht-deklariertes Objekt (E0512), Body mischt Formen (E0513), JOIN nicht auf versiegeltem Schlüssel (E0514), leeres sql (E0246)
403	PDP-Deny (E2101/E2102), cross-modaler Schlüssel nicht Klartext (E0515), Objekt außerhalb der Allowlist (E0512)
422	Gültig, aber nicht auflösbar — z. B. MetricFlow noch nicht implementiert (E1001)
503	PDP-Snapshot fehlt (E2001, fail-closed), Decoder-Op ohne LLM-Backend (E0521)
502	Trino-Ausführungsfehler (E0510)

Siehe Fehler & Statuscodes für das vollständige Envelope.

Zugriff & CapabilitiesWie die Delegationskette, Grants und Redaktionsversionen eines Subjects entscheiden, was eine Query sehen kann — fail-closed per Konstruktion.

Spec-Status

Die OSL-SQL-Oberfläche ist RFC 0005 (Status: Draft, 2026-07-02); der Planner, der Executor und alle fünf Formen sind implementiert. RFC 0002 (semantic_match) ist Abgelöst — Retrieval ist jetzt die RETRIEVE-Relationsquelle, kein WHERE-Prädikat.