Kontextsets – Übersicht

Ein Kontextset ist eine Sammlung datenbankspezifischer Informationen, mit denen Tools wie QueryData Abfragen mit hoher Genauigkeit generieren können. Kontextsätze können Vorlagen, Facetten und Wertsuchen enthalten, die QueryData helfen, Ihr Datenbankschema und die Geschäftslogik Ihrer Anwendungen zu verstehen.

Die folgenden Datenbanken werden unterstützt:

  • AlloyDB for PostgreSQL
  • Cloud SQL for MySQL
  • Cloud SQL for PostgreSQL
  • Spanner
  • Firestore mit MongoDB-Kompatibilität
  • Bigtable

Was sind Kontextsets?

Damit Sie effektive agentische Anwendungen erstellen können, müssen Tools wie QueryData Ihre Datenorganisation und Geschäftslogik verstehen. Diese Informationen stellen Sie in Form eines Kontextsets bereit.

Sie definieren den Kontext in Dateien, die JSON-Objekte für jeden Kontexttyp enthalten. Sie können diese Kontextdateien mithilfe des Kontext-Engineering-Agenten erstellen. Anschließend laden Sie die Kontextdatei in einen Kontextsatz hoch, den Sie in der Google Cloud-Konsole erstellen. Durch diesen Prozess können Tools wie QueryData das spezifische Schema der Datenbank und die Geschäftslogik der Anwendung erlernen.

Die Kontextdatei sieht in etwa so aus:

{
  "templates": [
    {
      "nl_query": "Count Prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" ='Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  "facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ],
  "value_searches": [
    {
      "query": "SELECT $value as value, 'accounts.account_type' as columns, 'Account Type' as concept_type, 0 as distance, '{}'::text as context FROM \"accounts\" T WHERE T.\"account_type\" = $value",
      "concept_type": "Account Type",
      "description": "Exact match for account types"
    }
   ]
}

Dateiformat des Kontextsets

Eine Kontextset-Datei besteht aus einer ausgewählten Sammlung von Vorlagen, Facetten und Wertsuchen im JSON-Format, die Tools wie QueryData dabei unterstützen, Fragen in natürlicher Sprache in Abfragen für eine bestimmte Datenbank zu übersetzen. Durch die Definition des Kontexts wird eine hochpräzise SQL-Generierung für gängige Abfragemuster sichergestellt.

Um die Genauigkeit zu maximieren, muss der Kontextsatz genau und umfassend sein und die erwarteten Anwendungsabfragen abdecken.

Kontextsätze können in den Regionen us-central1, us-east1, europe-west4 und asia-southeast1 erstellt werden. Sie müssen eine Region auswählen, wenn Sie den ersten Kontextsatz in einem Projekt erstellen. Spätere Kontextgruppen verwenden dieselbe Region.

Abfragevorlagen

Abfragevorlagen sind eine Sammlung repräsentativer Fragen in natürlicher Sprache mit entsprechenden SQL-Abfragen. Sie enthalten auch Erklärungen, um eine deklarative Begründung für die Generierung von SQL aus natürlicher Sprache zu liefern.

Ein Abfragevorlagenobjekt sieht in etwa so aus:

{
  "templates": [
    {
      "nl_query": "Count prague loan accounts",
      "sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = 'Prague'",
      "intent": "How many accounts associated with loans are located in the Prague region?",
      "manifest": "How many accounts associated with loans are located in a given city?",
      "parameterized": {
        "parameterized_intent": "How many accounts associated with loans are located in $1",
        "parameterized_sql": "SELECT COUNT(T1.account_id) FROM bird_dev_financial.account AS T1 INNER JOIN bird_dev_financial.loan AS T2 ON T1.account_id = T2.account_id INNER JOIN bird_dev_financial.district AS T3 ON T1.district_id = T3.district_id WHERE T3.\"A3\" = $1"
      }
    }
  ],
  ...
}

Die Hauptkomponenten des JSON-Objekts der Abfragevorlage sind:

  • nl_query: Ein Beispiel für eine Abfrage in natürlicher Sprache, die von Tools wie QueryData verarbeitet wird.
  • sql: Die SQL-Abfrage für die Abfrage in natürlicher Sprache.
  • intent: Das Ziel oder der Zweck der Abfrage in natürlicher Sprache. Wenn nicht festgelegt, wird dieser Wert standardmäßig auf die Abfrage in natürlicher Sprache gesetzt.
  • manifest: Eine verallgemeinerte, automatisch generierte Form des Intents.
  • parameterized_intent: Eine automatisch generierte Vorlage des Intents, bei der Entitätswerte durch Parameter ersetzt werden.
  • parameterized_sql: Eine automatisch generierte Vorlage der SQL-Abfrage, die der parametrisierten Absicht entspricht.

Abfrageattribute

Abfrageattribute sind eine ausgewählte Gruppe repräsentativer Bedingungen in natürlicher Sprache mit entsprechenden SQL-Prädikaten. Attribute verwalten Filter und Bedingungen, sodass Abfragevorlagen attributbasierte Suchen durchführen können.

Ein Abfrage-Facettenobjekt sieht in etwa so aus:

{
...
"facets": [
    {
      "sql_snippet": "employee.\"A11\" BETWEEN 6000 AND 10000",
      "intent": "Average salary between 6000 and 10000",
      "manifest": "Average salary between a given number and a given number",
      "parameterized": {
         "parameterized_intent": "Average salary between $1 and $2",
         "parameterized_sql_snippet": "employee.\"A11\" BETWEEN $1 AND $2"
      }
    }
  ]
}

Die Hauptkomponenten des JSON-Objekts für Facetten sind:

  • sql_snippet: Ein SQL-Snippet. Um Unklarheiten zu vermeiden, sollten Sie Spaltennamen mit Tabellennamen qualifizieren (z. B. table_name.column_name).
  • intent: Eine Erklärung des SQL-Prädikats.
  • manifest: Eine verallgemeinerte, automatisch generierte Form des Intents.
  • parameterized_intent: Eine automatisch generierte Vorlage des Intents, bei der Entitätswerte durch Parameter ersetzt werden.
  • parameterized_sql_snippet: Eine vorlagenbasierte, automatisch generierte Form des sql_snippet, die der parametrisierten Absicht entspricht.

Suchanfragen bewerten

Suchanfragen nach Werten sind von Entwicklern definierte Abfragen, die mithilfe von Abgleichsfunktionen Werte und ihren Kontext in einer Datenbank finden. Bei der Wertverknüpfung werden die Ergebnisse dieser Abfragen verwendet, um zu ermitteln, welche Tabellen und Spalten einen übereinstimmenden Wert enthalten, den Konzepttyp des Werts zu verstehen und Rechtschreibfehler zu korrigieren.

Die QueryData API verwendet die Wertverknüpfung, um natürliche Sprache genauer in SQL zu konvertieren. Durch die Verwendung von Suchanfragen für Werte kann die API Rechtschreibfehler korrigieren und Werttypen anhand von Datenbankwerten auflösen, was die Conversion-Genauigkeit verbessert.

Die Wertverknüpfung verbessert die Genauigkeit der Konvertierung von natürlicher Sprache in SQL. Wenn ein Nutzer beispielsweise fragt: „Gibt es Flüge ab Heathrow?“, speichert die Datenbank den Flughafennamen möglicherweise als „London Heathrow“. Ohne Wertverknüpfung filtert das generierte SQL möglicherweise nach WHERE name = 'Heathrow' und gibt keine Ergebnisse zurück. Wertsuchanfragen weisen den KI-Agenten an, „Heathrow“ dem richtigen Datenbankwert „London Heathrow“ und dem zugehörigen Schemaspeicherort (airports.name) zuzuordnen. So wird sichergestellt, dass die generierte SQL-Abfrage korrekt ist.

Beispiel für eine Suchanfrage nach einem Wert:

{
  ...
  "value_searches": [
    {
      "query": "SELECT $value as value, 'airports.iata' as columns, 'Airport IATA Code' as concept_type, 0 as distance, '{}'::text as context FROM \"airports\" T WHERE T.\"iata\" = $value",
      "concept_type": "Airport IATA Code",
      "description": "Exact match (Standard SQL) for 3-letter airport codes"
    },
    {
      "query": "WITH TrigramMetrics AS ( SELECT T.\"name\" AS original_value, (T.\"name\" <-> $value::text) AS normalized_dist FROM \"airports\" T WHERE T.\"name\" % $value::text ) SELECT original_value AS value, 'airports.name' AS columns, 'Airport Name' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM TrigramMetrics",
      "concept_type": "Airport Name",
      "description": "Fuzzy match using standard trigram for partial airport names"
    }
  ]
}

Die Hauptkomponenten des JSON-Objekts für die Wertsuche sind:

  • query: Eine parametrisierte SQL-Anweisung, die die Logik für den Abgleich einer Wertphrase mit den in einer Datenbank gespeicherten Werten definiert. Das Ergebnisset projiziert in der Regel den übereinstimmenden Wert, den Schemaspeicherort, den Konzepttyp und einen normalisierten Distanzmesswert (zwischen 0 und 1).
  • concept_type: Ein semantisches Label, das dem Wert zugewiesen ist, z. B. district oder loan_status. Dieses Label hilft bei der Wertverknüpfung und schließlich bei Tools wie der QueryData API, die Rolle der Wertphrase im Schema zu verstehen. Außerdem wird eine SQL-Anweisung erstellt, die auf das Konzept für den Wert sowie auf die Tabelle und Spalte abzielt, in der die Wertphrase vorkommt.
  • description: Eine Beschreibung der Suchlogik.

Beschränkungen

Für Kontextgruppen gelten die folgenden Einschränkungen:

  • Kontextsätze für Datenbanken unterstützen nur Vorlagen, Facetten und Wertesuchen.
  • Kontextsätze für Datenbanken werden nur vom Endpunkt QueryData in der Conversational Analytics API verwendet.

Nächste Schritte