Présentation des ensembles de contextes

Un ensemble de contextes est une collection d'informations spécifiques à une base de données qui permet à des outils tels que QueryData de générer des requêtes avec une grande précision. Les ensembles de contexte peuvent inclure des modèles, des facettes et des recherches de valeurs qui aident QueryData à comprendre le schéma de votre base de données et la logique métier de vos applications.

Les bases de données suivantes sont compatibles :

  • AlloyDB pour PostgreSQL
  • Cloud SQL pour MySQL
  • Cloud SQL pour PostgreSQL
  • Spanner
  • Firestore compatible avec MongoDB
  • Bigtable

Que sont les ensembles de contextes ?

Pour créer des applications agentiques efficaces, des outils tels que QueryData doivent comprendre l'organisation de vos données et votre logique métier. Vous fournissez ces informations sous la forme d'un ensemble de contextes.

Vous définissez le contexte dans des fichiers contenant des objets JSON pour chaque type de contexte. Vous pouvez créer ces fichiers de contexte à l'aide de l'agent d'ingénierie contextuelle. Vous importez ensuite le fichier de contexte dans un ensemble de contextes que vous créez dans la console Google Cloud. Ce processus permet à des outils tels que QueryData d'apprendre le schéma spécifique de la base de données et la logique métier de l'application.

Le fichier de contexte ressemble à ceci :

{
  "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"
    }
   ]
}

Format de fichier de l'ensemble de contextes

Un fichier d'ensemble de contextes se compose d'un ensemble organisé de modèles, de facettes et de recherches de valeurs au format JSON qui guident des outils tels que QueryData dans la traduction de questions en langage naturel en requêtes pour une base de données spécifique. La définition du contexte garantit une génération SQL très précise pour les schémas de requête courants.

Pour maximiser la précision, assurez-vous que l'ensemble de contexte est précis et complet dans sa couverture des requêtes d'application attendues.

Les ensembles de contexte peuvent être créés dans les régions us-central1, us-east1, europe-west4 et asia-southeast1. Vous devez sélectionner une région lorsque vous créez le premier ensemble de contextes dans un projet. Les ensembles de contexte ultérieurs utilisent la même région.

Modèles de requêtes

Les modèles de requête sont un ensemble de questions représentatives en langage naturel avec les requêtes SQL correspondantes. Elles incluent également des explications pour fournir une justification déclarative de la génération de SQL à partir du langage naturel.

Un objet de modèle de requête se présente comme suit :

{
  "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"
      }
    }
  ],
  ...
}

Les principaux composants de l'objet JSON du modèle de requête sont les suivants :

  • nl_query : exemple de requête en langage naturel gérée par des outils tels que QueryData.
  • sql : requête SQL pour la requête en langage naturel.
  • intent : objectif de la requête en langage naturel. Si elle n'est pas définie, cette valeur est définie par défaut sur la requête en langage naturel.
  • manifest : forme généralisée et générée automatiquement de l'intent.
  • parameterized_intent : forme de l'intent générée automatiquement à partir d'un modèle, avec les valeurs d'entité remplacées par des paramètres.
  • parameterized_sql : forme de requête SQL basée sur un modèle et générée automatiquement, qui correspond à l'intention paramétrée.

Attributs de la requête

Les facettes de requête sont un ensemble de conditions représentatives en langage naturel avec des prédicats SQL correspondants. Les attributs gèrent le filtrage et les conditions, ce qui permet aux modèles de requête d'effectuer des recherches par attribut.

Un objet de facette de requête se présente comme suit :

{
...
"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"
      }
    }
  ]
}

Les principaux composants de l'objet JSON de facette sont les suivants :

  • sql_snippet : extrait SQL. Pour éviter toute ambiguïté, qualifiez les noms de colonnes avec les noms de tables (par exemple, table_name.column_name).
  • intent : explication du prédicat SQL.
  • manifest : forme généralisée et générée automatiquement de l'intent.
  • parameterized_intent : forme de l'intent générée automatiquement à partir d'un modèle, avec les valeurs d'entité remplacées par des paramètres.
  • parameterized_sql_snippet : forme de sql_snippet basée sur un modèle et générée automatiquement, qui correspond à l'intent paramétré.

Requêtes de recherche de valeur

Les requêtes de recherche de valeurs sont des requêtes définies par le développeur qui utilisent des fonctions de correspondance pour trouver des valeurs et leur contexte dans une base de données. La mise en correspondance des valeurs utilise les résultats de ces requêtes pour identifier les tables et les colonnes contenant une valeur correspondante, comprendre le type de concept de la valeur et corriger les fautes d'orthographe.

L'API QueryData utilise l'association de valeurs pour convertir plus précisément le langage naturel en SQL. En utilisant des requêtes de recherche de valeurs, l'API peut corriger les fautes d'orthographe et résoudre les types de valeurs en fonction des valeurs de la base de données, ce qui améliore la précision de la conversion.

L'association de valeurs améliore la précision de la conversion du langage naturel en SQL. Par exemple, si un utilisateur demande "Y a-t-il des vols au départ de Heathrow ?", la base de données peut stocker le nom de l'aéroport sous la forme "London Heathrow". Sans association de valeurs, le code SQL généré peut filtrer par WHERE name = 'Heathrow' et ne renvoyer aucun résultat. Les requêtes de recherche de valeurs guident l'agent pour qu'il mappe "Heathrow" à la valeur de base de données correcte "London Heathrow" et à son emplacement de schéma (airports.name), ce qui garantit l'exactitude du code SQL généré.

Voici un exemple de requête de recherche de valeur :

{
  ...
  "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"
    }
  ]
}

Les principaux composants de l'objet JSON de recherche de valeur sont les suivants :

  • query : instruction SQL paramétrée qui définit la logique de mise en correspondance d'une expression de valeur avec les valeurs stockées dans une base de données. L'ensemble de résultats projette généralement la valeur correspondante, l'emplacement du schéma, le type de concept et une métrique de distance normalisée (entre 0 et 1).
  • concept_type : libellé sémantique attribué à la valeur (par exemple, district ou loan_status). Ce libellé aide à lier les valeurs et, à terme, permet aux outils tels que l'API QueryData de comprendre le rôle de l'expression de valeur dans le schéma. Il permet également de produire une instruction SQL qui cible le concept de la valeur, ainsi que la table et la colonne dans lesquelles l'expression de valeur apparaît.
  • description : description de la logique de recherche.

Limites

Les ensembles de contextes présentent les limites suivantes :

  • Les ensembles de contexte pour les bases de données ne sont compatibles qu'avec les modèles, les attributs et les recherches de valeurs.
  • Les ensembles de contexte pour les bases de données ne sont utilisés que par le point de terminaison QueryData dans l'API Conversational Analytics.

Étapes suivantes