Kontextsets – Übersicht

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

Die folgenden Datenbanken werden unterstützt:

  • AlloyDB for PostgreSQL
  • Cloud SQL for MySQL
  • Cloud SQL for PostgreSQL
  • Spanner

Was sind Kontextsets?

Um effektive Agentenanwendungen zu erstellen, müssen Tools wie QueryData Ihre Datenorganisation und Geschäftslogik verstehen. Sie stellen diese Informationen in Form eines Kontextsets bereit.

Sie definieren den Kontext in Dateien, die JSON-Objekte für jeden Kontexttyp enthalten. Sie erstellen diese Kontextdateien mit dem Kontext-Engineering-Agenten. Anschließend laden Sie die Kontextdatei in ein Kontextset hoch, das Sie in der Google Cloud Console erstellen. So können Tools wie QueryData das spezifische Schema der Datenbank und die Geschäftslogik der Anwendung kennenlernen.

Die Kontextdatei sieht in etwa so aus:

Die Agentenkontextdatei 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"
      }
    }
  ]
}

Dateiformat für Kontextsets

Eine Kontextsetdatei besteht aus einer kuratierten Sammlung von Vorlagen und Facetten im JSON-Format, die Tools wie QueryData dabei helfen, Fragen in natürlicher Sprache in Abfragen für eine bestimmte Datenbank zu übersetzen. Durch die Definition des Kontexts wird eine hochgenaue SQL-Generierung für gängige Abfragemuster ermöglicht.

Achten Sie darauf, dass das Kontextset genau und umfassend ist, um die Genauigkeit zu maximieren.

Kontextsets können in den Regionen us-central1, us-east1, europe-west4 und asia-southeast1 erstellt werden.

Abfragevorlagen

Abfragevorlagen sind eine kuratierte 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 natürlicher Sprache zu SQL 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 für Abfragevorlagen 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 nichts festgelegt ist, wird standardmäßig die Abfrage in natürlicher Sprache verwendet.
  • manifest: Eine verallgemeinerte, automatisch generierte Form der Absicht.
  • parameterized_intent: Eine vorlagenbasierte, automatisch generierte Form der Absicht, bei der Entitätswerte durch Parameter ersetzt werden.
  • parameterized_sql: Eine vorlagenbasierte, automatisch generierte Form der SQL-Abfrage, die der parametrisierten Absicht entspricht.

Abfragefacetten

Abfragefacetten sind eine kuratierte Sammlung repräsentativer Bedingungen in natürlicher Sprache mit entsprechenden SQL-Prädikaten. Facetten verwalten Filter und Bedingungen, sodass mit Abfragevorlagen Facettensuchen durchgeführt werden können.

Ein Abfragefacettenobjekt 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 Mehrdeutigkeiten zu vermeiden, müssen 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 der Absicht.
  • parameterized_intent: Eine vorlagenbasierte, automatisch generierte Form der Absicht, bei der Entitätswerte durch Parameter ersetzt werden.
  • parameterized_sql_snippet: Eine vorlagenbasierte, automatisch generierte Form des sql_snippet, die der parametrisierten Absicht entspricht.

Wertesuchabfragen

Wertesuchabfragen sind von Entwicklern definierte Abfragen, mit denen mithilfe von Übereinstimmungsfunktionen Werte und ihr Kontext in einer Datenbank gesucht werden. Bei der Werteverknüpfung werden die Ergebnisse dieser Abfragen verwendet, um zu ermitteln, in welchen Tabellen und Spalten ein übereinstimmender Wert enthalten ist, den Konzepttyp des Werts zu verstehen und Rechtschreibfehler zu korrigieren.

Die QueryData API verwendet die Werteverknüpfung, um natürliche Sprache genauer in SQL zu konvertieren. Mithilfe von Wertesuchabfragen kann die API Rechtschreibfehler korrigieren und Wertetypen basierend auf Datenbankwerten auflösen, wodurch die Konvertierungsgenauigkeit verbessert wird.

Die Werteverknüpfung verbessert die Genauigkeit der Konvertierung von natürlicher Sprache in SQL. Wenn ein Nutzer beispielsweise fragt: „Gibt es Flüge ab Heathrow?“, wird der Flughafenname in der Datenbank möglicherweise als „London Heathrow“ gespeichert. Ohne Werteverknüpfung würde die generierte SQL-Abfrage nach WHERE name = 'Heathrow' filtern und keine Ergebnisse zurückgeben. Wertesuchabfragen weisen den Agenten an, „Heathrow“ dem korrekten Datenbankwert „London Heathrow“ und seinem Schemaspeicherort (airports.name) zuzuordnen, damit die generierte SQL-Abfrage korrekt ist.

Ein Beispiel für eine Wertesuchabfrage:

{
  ...
  "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"
    },
    {
      "query": "WITH SemanticMetrics AS ( SELECT T.\"city\" AS original_value, ( (google_ml.embedding('gemini-embedding-001', $value)::vector <=> google_ml.embedding('gemini-embedding-001', T.\"city\")::vector) / 2.0 ) AS normalized_dist FROM \"airports\" T WHERE T.\"city\" IS NOT NULL ) SELECT original_value AS value, 'airports.city' AS columns, 'Airport City' AS concept_type, normalized_dist AS distance, '{}'::text AS context FROM SemanticMetrics",
      "concept_type": "Airport City",
      "description": "Semantic search on string values for airport city names"
    }
  ]
}

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

  • query: Eine parametrisierte SQL-Anweisung, die die Logik für den Abgleich einer Wertphrase mit den Werten in einer Spalte einer Tabelle in einer Datenbank definiert. Im Ergebnissatz werden in der Regel der übereinstimmende Wert, der Schemaspeicherort, der Konzepttyp und ein normalisierter Entfernungs-Messwert (zwischen 0 und 1) projiziert.
  • concept_type: Eine semantische Bezeichnung, die dem Wert zugewiesen wird, z. B. district oder loan_status. Diese Bezeichnung hilft bei der Werteverknü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 Kontextsets gelten folgende Einschränkungen:

  • Cloud SQL for SQL Server wird nicht unterstützt.
  • Kontextsets für Datenbanken unterstützen nur Vorlagen, Facetten und Wertesuchen.
  • Kontextsets für Datenbanken werden nur vom QueryData-Endpunkt in der Conversational Analytics API verwendet.

Nächste Schritte