Retrieval (RETRIEVE)

Il retrieval è una sorgente di relazione dentro OSL-SQL: la table function RETRIEVE(...). Non c’è più un endpoint /osl/retrieve separato — fai SELECT da RETRIEVE(...) in un body POST /osl/query.

Era un endpoint, ora è una forma

/osl/retrieve è stato rimosso. Il suo resolver governato è ora il backend della forma RETRIEVE (e del tool MCP doc_search). Stessa applicazione, un’unica superficie.

La forma

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

• facet — una UnstructuredFacet dichiarata.
• query — testo naturale; il motore lo embedda con il modello dichiarato nel facet.
• top_k — deve soddisfare ≤ facet.retrieval.max_top_k.
• I filtri di metadata sono applicati dallo store governato (predicati di riga per soggetto) prima del trim di overfetch dell’ACL.

Ogni passage restituito porta un blocco cite (source · doc · chunk) e la sua chiave di entità denormalizzata, così i risultati possono essere attribuiti e correlati.

Passage (forma)

{
  "text": "Anna wants to increase EU equity exposure […]",
  "score": 0.91,
  "customer_id": "9c1e…f04a",
  "cite": { "source": "gong://…", "doc_id": "meet-2026-05-08-7a3c", "chunk_id": "chk-…" },
  "redacted_fields": []
}

Con un'op di proiezione

SELECT SUMMARIZE(text) AS summary, score
FROM RETRIEVE(facet => 'meeting_transcripts', query => 'churn risk', top_k => 3)

SUMMARIZE/SIMILARITY/… sono operatori di proiezione — mappe unarie su passages già governati.

Come viene governato il retrieval

• Versione di oscuramento. Il facet è servito alla versione di oscuramento richiesta dal soggetto — exact-or-deny. I campi di metadata oscurati sono elencati in redacted_fields.
• ACL row-level. Deny-by-default: un attore senza concessione ottiene zero passages.
• Isolamento. La query apre solo la tabella Lance della versione selezionata — nessun side-channel verso vettori meno oscurati.

Il cross-modale è fail-closed

Quando una gamba RETRIEVE è unita in join a un’entità strutturata (… JOIN RETRIEVE(...) ON x.k = r.k), la chiave di join deve essere in chiaro nell’output governato del passage o il join non restituisce nulla (403 E0515). Una chiave mascherata non correla mai con una in chiaro. Vedi il join cross-modale.

Correlati

• La superficie di query (OSL-SQL) — tutte e cinque le forme.
• Accesso e capacità — concessioni, versioni di oscuramento, MEET.
• Per un’anteprima governata di pochi chunk, usa POST /osl/sample.