Panoramica dei set di contesti

Un set di contesti è la conoscenza del dominio che alimenta QueryData. Definisce il funzionamento della logica di business prima che l'applicazione venga pubblicata, in modo che QueryData possa rispondere alle domande in linguaggio naturale con un'accuratezza quasi del 100% e una bassa latenza online.

Sebbene il contesto del dominio possa assumere molte forme, i set di contesto supportano tre tipi di contesto specializzati:

  • Modelli di query: query SQL pre-approvate per domande aziendali comuni.
  • Facet di query: filtri modulari, come "casa per famiglia" o "vista sull'oceano", che si collegano dinamicamente ai modelli.
  • Ricerche di valori: ricerche di entità che mappano le frasi degli utenti a valori esatti del database e risolvono l'ambiguità.

Sono supportati i seguenti database:

  • AlloyDB per PostgreSQL
  • Cloud SQL per MySQL
  • Cloud SQL per PostgreSQL
  • Spanner
  • Firestore con compatibilità MongoDB
  • Bigtable

Cosa sono i set di contesti

Puoi creare e ottimizzare i set di contesti in fase di progettazione utilizzando l'agente di progettazione del contesto. L'agente di context engineering esegue un benchmark golden rappresentativo tramite QueryData, assegna un punteggio ai risultati e perfeziona in modo iterativo (hill-climbing) il set di contesti. Quindi, confronta la versione finale con un set di test di holdout non visto per evitare l'overfitting e carica automaticamente il set di contesto suGoogle Cloud.

L'abbinamento del database con un set di contesto selezionato offre due vantaggi principali in fase di produzione:

  • Precisione quasi del 100% che generalizza: gli schemi del database descrivono tabelle e colonne, ma non possono indicare a un modello quale distanza viene considerata "vicina" o quale valutazione rende una scuola "buona". I set di contesto basano QueryData sulle regole aziendali verificate della tua organizzazione, mentre i pattern parametrizzati consentono a un set di contesto compatto di generalizzare tra variazioni di frasi, combinazioni di filtri e valori delle entità.
  • Esecuzione online rapida e bassa latenza: il context engineering sposta il costoso ragionamento sullo schema offline in fase di progettazione:
    • Esecuzione con corrispondenza di contesto con un set di contesti: esecuzione rapida in un unico passaggio tramite corrispondenza di modelli precompilati e ricerche di valori indicizzati.
    • Sintesi zero-shot per query impreviste senza modelli: richiede da 2 a 3 volte più tempo perché il modello deve esplorare i metadati dello schema e sintetizzare l'SQL in fase di runtime.
    • Esplorazione agentica aperta utilizzando strumenti SQL non elaborati: spesso richiede più di 30 secondi a causa di query di prova ed errore a più turni e loop di correzione degli errori.

Architettura di posizionamento del contesto

Quando prepari un database per QueryData, inserisci ogni tipo di conoscenza del dominio nel livello di contesto corrispondente al suo ambito e al suo comportamento di recupero:

Livello Meccanismo Cosa includere Contromisure
Tier 1: Schema catalog comments Istruzioni COMMENT ON TABLE e COMMENT ON COLUMN del database (o descrizioni dello schema databaseTableReferences in linea) Significati concisi delle colonne, unità di misura (ad esempio centesimi rispetto a dollari o timestamp UTC), valori enum chiusi (ad esempio 'PENDING', 'SETTLED', 'FAILED') e note di ritiro Inserito ogni volta che la tabella è nell'ambito. Mantieni i commenti concisi in modo che non appesantiscano il prompt dello schema.
Livello 2: contesto del prompt globale Istruzioni per l'agente di orchestrazione esterno (incluse in QueryData prompt) o DataAgent system_instruction Invarianti tra tabelle, fusi orari predefiniti per i report, filtri globali per l'eliminazione temporanea (ad esempio deleted_at IS NULL), bridge di ID entità uniti e date di passaggio all'era storica Incluso in ogni richiesta senza filtro di recupero top-K. Sii conciso (meno di 1500 token).
Livello 3A: modelli di query templates nel file JSON del set di contesti Da 8 a 25 backbone componibili di join, aggregazione e granularità di più tabelle con segnaposto dei parametri $1, $2 Rimuovi tutti i commenti -- e /* ... */ in modo che la compressione JSON su una singola riga non commenti l'SQL finale. Evita di impostare come hardcoded i limiti delle policy condizionali nei modelli generali.
Livello 3B: facet delle query facets nel file JSON del set di contesti Vocabolario del dominio, metriche denominate e predicati di filtro di coorte o policy con ambito Qualifica ogni colonna con il nome della tabella (table_name.column_name, mai alias di tabella) e indica i limiti di applicabilità esatti in intent.
Tier 4: Value search queries value_searches nel file JSON del set di contesti Risoluzione di entità con nomi propri, sinonimi o cardinalità elevata approssimativi nelle tabelle di ricerca Limita alle tabelle di ricerca o di dimensione indicizzate (meno di 100.000 righe) o alle viste materializzate SELECT DISTINCT aggiornate con CTE interna ORDER BY ... LIMIT 10. Non utilizzarlo per piccoli enum chiusi o tabelle dei fatti non indicizzate.

Tipi di contesto in un set di contesti

In fase di runtime, QueryData combina tutti e tre i tipi di contesto in un unico passaggio. Ad esempio, se un utente chiede:

"Trovami case vicino a buone scuole a Del Mar per una famiglia con un bambino e con vista sull'oceano"

QueryData risolve la richiesta in quattro passaggi coordinati:

  1. Un modello di query fornisce la struttura di base della query per "case vicino a buone scuole a $1", applicando regole aziendali per la distanza (entro 3 km) e il ranking della scuola (5 o superiore).
  2. I facet delle query inseriscono filtri modulari per "casa per famiglia" (3-4 camere da letto, 2 o più bagni) e "vista sull'oceano" (ricerca di somiglianza vettoriale).
  3. Una ricerca di valori trova 'Del Mar' nella colonna cities.city_name e verifica il tipo di concetto.
  4. Le spiegazioni degli intent vengono combinate in un'unica spiegazione certificata restituita insieme ai risultati della query: "Case a Del Mar entro 3 km da scuole con ranking pari o superiore a 5, con 3-4 camere da letto e vista sull'oceano".

Modelli di query

I template di query sono un insieme selezionato di domande rappresentative in linguaggio naturale con query SQL corrispondenti. Includono anche spiegazioni per fornire una motivazione certificata del modo in cui è stata interpretata una domanda.

Ad esempio, se un utente chiede a un'applicazione immobiliare "Trova case vicino a buone scuole a Del Mar", lo schema del database da solo non definisce quale distanza è considerata "vicina", quale valutazione rende una scuola "buona" o come classificare le proprietà corrispondenti. Un modello di query acquisisce l'esatta interpretazione aziendale, ad esempio le proprietà entro 3 km da una scuola con un ranking pari o superiore a 5, ordinate in base a un punteggio ponderato di ranking e prossimità, e la generalizza per qualsiasi città.

I componenti principali di un modello di query sono i seguenti:

  • Esempio di domanda in linguaggio naturale: una domanda rappresentativa posta in un linguaggio semplice, ad esempio "Trova case vicino a buone scuole a Del Mar".
  • Esempio di query SQL: la query SQL verificata che risponde alla domanda in base alle tue regole aziendali.
  • Pattern di domanda generalizzato: un pattern generato automaticamente con valori specifici sostituiti da descrizioni generiche, ad esempio "Trova case vicino a buone scuole in una determinata città", utilizzato per trovare corrispondenze con le domande in arrivo in base alle variazioni di formulazione.
  • Spiegazione dell'intent: una spiegazione certificata e in un linguaggio semplice delle regole aziendali applicate dalla query, ad esempio "Trova case in $1 entro 3 km da una scuola con un ranking di almeno 5".
  • Query SQL con parametri: la query SQL eseguibile corrispondente alla spiegazione dell'intent, che utilizza parametri come $1.
Quando crei modelli di query per i database SQL, segui queste best practice:

  • Rimuovi i commenti SQL: rimuovi tutti i commenti di riga -- e i commenti di blocco /* ... */ da sql e parameterized_sql, soprattutto prima di comprimere l'SQL su più righe in un'unica riga JSON in cui un commento -- commenterebbe il resto dell'istruzione.
  • Mantieni i template incentrati sulle strutture di base: utilizza i template per acquisire pattern di join, raggruppamento e aggregazione riutilizzabili per più tabelle (in genere da 8 a 25 template per set di contesto). Inserisci i limiti delle policy condizionali o i predicati WHERE specifici per le coorti nei facet delle query anziché impostarli come hardcoded nei modelli generali.

Facet di query

I facet di query sono un insieme selezionato di condizioni rappresentative in linguaggio naturale con predicati SQL corrispondenti. I facet gestiscono i filtri e le condizioni, consentendo ai modelli di query di eseguire ricerche per facet senza richiedere un modello separato per ogni combinazione di filtri.

Ad esempio, un utente può estendere "Trova case vicino a buone scuole a Del Mar" con condizioni aggiuntive:

  • "…per una famiglia di principianti", che corrisponde a un filtro SQL strutturato come properties.bedrooms BETWEEN 3 AND 4 AND properties.bathrooms >= 2.0.
  • "…con vista sull'oceano", che utilizza operatori AI del database come ai.if o la ricerca di somiglianze vettoriali (<=>) su colonne non strutturate come listing_description, listing_image_embeddings e customer_reviews.

I componenti principali di un facet di query sono i seguenti:

  • Snippet SQL: la condizione di filtro SQL riutilizzabile, ad esempio properties.bedrooms BETWEEN 3 AND 4 AND properties.bathrooms >= 2.0. Per evitare ambiguità, qualifica ogni nome di colonna con il nome completo della tabella, ad esempio table_name.column_name. Non utilizzare nomi di colonne semplici o alias di tabelle come t1.column_name.
  • Pattern di condizione generalizzato: il pattern di linguaggio naturale a cui corrisponde l'aspetto, ad esempio "Adatto per una famiglia di principianti".
  • Spiegazione dell'intent: una spiegazione certificata della condizione di filtro, restituita come parte della logica di risposta complessiva, inclusi i limiti di applicabilità esatti (ad esempio, a quale gruppo di entità, stato o finestra di date si applica la condizione).
  • Snippet SQL con parametri: il frammento SQL eseguibile corrispondente alla spiegazione dell'intent.

Query di ricerca di valore

Le query di ricerca dei valori sono query definite dallo sviluppatore che utilizzano funzioni di corrispondenza, come la corrispondenza esatta, la somiglianza di trigrammi approssimativa o la ricerca vettoriale semantica, per trovare i valori e il loro contesto all'interno di un database. QueryData utilizza il collegamento dei valori su questi risultati per identificare quali tabelle e colonne contengono un valore corrispondente, comprendere il tipo di concetto del valore, correggere gli errori ortografici e rilevare l'ambiguità prima di eseguire SQL.

Ad esempio, se un utente chiede a un'applicazione immobiliare "Proprietà vendute a Westwod nell'ultimo mese", un modello basato solo sullo schema potrebbe filtrare per `WHERE name = 'Westwod'` e non restituire risultati. Le query di ricerca dei valori utilizzano la corrispondenza fuzzy per risolvere l'errore ortografico "Westwod" nel valore del database 'Westwood'. Inoltre, se 'Westwood' esiste in più tipi di concetti nel database, ad esempio City, Municipality e Brokerage, il collegamento dei valori rileva l'ambiguità in modo che QueryData possa chiedere all'utente di chiarire a quale concetto si riferiva, anziché indovinare.

I componenti principali di una query di ricerca di valore sono i seguenti:

  • Query di ricerca: una query SQL con parametri che utilizza la corrispondenza esatta, la somiglianza dei trigrammi (pg_trgm) o la ricerca vettoriale per trovare un valore all'interno di una colonna.
  • Tipo di concetto: un'etichetta semantica, ad esempio City, Municipality o Brokerage, che specifica cosa rappresenta il valore e quale colonna filtrare.
  • Descrizione: una breve descrizione della logica di ricerca. Quando progetti value_searches per i database SQL, segui queste regole per evitare errori delle query di runtime e scansioni delle tabelle con latenza elevata:

    • Inserisci ORDER BY e LIMIT all'interno di una CTE o di una sottoquery, mai al livello più alto: in fase di runtime, QueryData può combinare più query value_searches con UNION ALL. Per assicurarti che ogni query limiti la propria scansione dell'indice, inserisci ORDER BY ... LIMIT 10 all'interno di un'espressione di tabella comune (CTE) WITH o di una sottoquery derivata anziché al livello più alto.
    • Esegui query su tabelle di ricerca indicizzate, mai su tabelle dei fatti di grandi dimensioni o enum chiusi: esegui ricerche di valori solo su tabelle di ricerca o di dimensioni di piccole dimensioni (meno di 100.000 righe) supportate da un indice trigramma o vettoriale oppure su una vista materializzata SELECT DISTINCT aggiornata estratta da una tabella più grande. Non eseguire mai value_searches direttamente su tabelle di fatti o log con milioni di righe, non calcolare mai gli incorporamenti in linea per riga sulle colonne della tabella al momento della query e ometti value_searches per piccoli enum chiusi (documenta invece i valori degli enum chiusi nei commenti delle colonne).

    Passaggi successivi