Définir le contexte de l'agent de données pour les sources de données BigQuery

Cette page explique comment fournir un contexte créé pour les agents de données qui utilisent des sources de données BigQuery.

Le contexte créé est une guidance que les propriétaires d'agents de données peuvent fournir pour façonner le comportement d'un agent de données et affiner les réponses de l'API. Un contexte créé efficace fournit à vos agents de données de l'API Conversational Analytics un contexte utile pour répondre aux questions sur vos sources de données.

Bien que le contexte créé soit facultatif, fournir un contexte robuste permet à l'agent de fournir des réponses plus précises et pertinentes. Votre agent de données intègre ce contexte lors de sa création et de son exécution pour s'assurer que ses actions, ses requêtes et ses réponses sont précises, conformes et adaptées à l'entreprise. Ce contexte est ingéré, indexé et utilisé pour façonner le comportement de l'agent.

Options pour fournir un contexte créé

Pour les sources de données BigQuery, vous pouvez fournir un contexte créé en combinant un contexte structuré et des instructions système. Dans la mesure du possible, fournissez le contexte via des champs de contexte structurés. Utilisez ensuite le paramètre system_instruction pour obtenir des conseils supplémentaires qui ne sont pas couverts par les champs structurés, par exemple pour définir le ton ou le comportement général d'un agent.

Une fois que vous avez défini les champs structurés et les instructions système qui composent votre contexte créé, vous pouvez fournir ce contexte à l'API dans l'un des appels suivants :

Définir des champs de contexte structurés

Cette section explique comment fournir un contexte à un agent de données à l'aide de champs de contexte structurés. Vous pouvez fournir les informations suivantes à un agent en tant que contexte structuré :

Contexte structuré au niveau de la table

Utilisez la clé tableReferences pour fournir à un agent des informations sur les tables spécifiques disponibles pour répondre aux questions. Pour chaque référence de table, vous pouvez utiliser les champs de contexte structurés suivants pour définir le schéma d'une table :

  • description : résumé du contenu et de l'objectif de la table
  • synonyms: liste de termes alternatifs pouvant être utilisés pour faire référence à la table
  • tags : liste de mots clés ou de tags associés à la table

Les exemples suivants montrent comment fournir ces propriétés en tant que contexte structuré dans des requêtes HTTP directes et avec le SDK Python.

HTTP

Dans une requête HTTP directe, vous fournissez ces propriétés au niveau de la table dans l'objet schema pour la référence de table pertinente. Pour obtenir un exemple complet de la structure du corps de requête complet, consultez Se connecter aux données BigQuery.

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
        "description": "Data for orders in The Look, a fictitious ecommerce store.",
        "synonyms": ["sales"],
        "tags": ["sale", "order", "sales_order"]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
        "description": "Data for users in The Look, a fictitious ecommerce store.",
        "synonyms": ["customers"],
        "tags": ["user", "customer", "buyer"]
    }
  }
]

SDK Python

Lorsque vous utilisez le SDK Python, vous pouvez définir ces propriétés au niveau de la table sur la propriété schema d'un objet BigQueryTableReference. L'exemple suivant montre comment créer des objets de référence de table qui fournissent un contexte pour les tables orders et users. Pour obtenir un exemple complet de la création et de l'utilisation d'objets de référence de table, consultez Se connecter aux données BigQuery.

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]

Contexte structuré au niveau des colonnes

La clé fields, imbriquée dans l'objet schema d'une référence de table, accepte une liste d'objets field pour décrire les colonnes individuelles. Tous les champs n'ont pas besoin de contexte supplémentaire. Toutefois, pour les champs couramment utilisés, l'ajout de détails supplémentaires peut aider à améliorer les performances de l'agent.

Pour chaque objet field, vous pouvez utiliser les champs de contexte structurés suivants pour définir les propriétés fondamentales d'une colonne :

  • description : brève description du contenu et de l'objectif de la colonne
  • synonyms: liste de termes alternatifs pouvant être utilisés pour faire référence à la colonne
  • tags : liste de mots clés ou de tags associés à la colonne

Les exemples suivants montrent comment fournir ces propriétés en tant que contexte structuré pour le champ status dans la table orders et pour le champ first_name dans la table users avec des requêtes HTTP directes et avec le SDK Python.

HTTP

Dans une requête HTTP directe, vous pouvez définir ces propriétés au niveau des colonnes en fournissant une liste d'objets fields dans l'objet schema d'une référence de table.

"tableReferences": [
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "orders",
    "schema": {
      "fields": [{
          "name": "status",
          "description": "The current status of the order.",
      }]
    }
  },
  {
    "projectId": "bigquery-public-data",
    "datasetId": "thelook_ecommerce",
    "tableId": "users",
    "schema": {
      "fields": [{
          "name": "first_name",
          "description": "The first name of the user.",
          "tags": "person",
      }]
    }
  }
]

SDK Python

Lorsque vous utilisez le SDK Python, vous pouvez définir ces propriétés au niveau des colonnes en attribuant une liste d'objets Field à la propriété fields de la propriété schema d'une table.

# Define column context for the 'orders' table
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    )
]

# Define column context for the 'users' table
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    )
]

Exemples de requêtes

La clé example_queries accepte une liste d'objets example_query qui définissent des requêtes en langage naturel pour aider l'agent à fournir des réponses plus précises et pertinentes. En fournissant à l'agent une question en langage naturel et la requête SQL correspondante, vous pouvez l'aider à fournir des résultats de meilleure qualité et plus cohérents.

Si la question d'un utilisateur correspond sémantiquement à un exemple de requête défini, l'agent peut exécuter directement cette requête plutôt que d'en générer une nouvelle. Lorsqu'un agent exécute une requête existante, la réponse de l'API inclut un matched_query objet pour indiquer qu'une requête validée a été utilisée. L'agent peut également citer cette requête dans sa réponse.

Exemples de requêtes paramétrées

En plus des requêtes statiques, vous pouvez définir des exemples de requêtes paramétrées qui permettent à l'agent de remplacer des valeurs dynamiques dans un modèle de requête validé. En incluant des paramètres dans vos exemples de requêtes, vous pouvez créer des modèles flexibles qui couvrent un plus large éventail de requêtes utilisateur que les exemples statiques. Lorsqu'une question d'utilisateur correspond à un modèle, l'agent exécute la requête correspondante pour fournir une réponse validée.

Vous pouvez définir une requête paramétrée comme suit :

  1. Dans le champ naturalLanguageQuestion, utilisez des accolades pour les espaces réservés, par exemple {state}.
  2. Dans le champ sqlQuery, utilisez la syntaxe de paramètre nommé BigQuery pour la même variable, par exemple @state.
  3. Dans le champ parameters, définissez le nom, le type de données et la description de chaque paramètre.

Exemples

Les exemples suivants montrent comment définir des exemples de requêtes statiques et paramétrées pour l'ensemble de données des aéroports de la FAA.

HTTP

Dans une requête HTTP directe, fournissez une liste d'objets example_query dans le champ example_queries. Pour chaque objet, fournissez la clé naturalLanguageQuestion (la question qu'un utilisateur peut poser) et la clé sqlQuery correspondante. Pour les requêtes paramétrées, vous devez également fournir une liste parameters qui inclut le nom, le type de données et la description de chaque paramètre.

"example_queries": [
  {
    "naturalLanguageQuestion": "How many airports are there?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`"
  },
  {
    "naturalLanguageQuestion": "How many airports are in {state} with an elevation that is greater than {elevation}?",
    "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports` WHERE LOWER(state_abbreviation) = @state AND elevation > @elevation",
    "parameters": [
      {
        "name": "state",
        "dataType": "STRING",
        "description": "The state abbreviation in lowercase.",
      },
      {
        "name": "elevation",
        "dataType": "FLOAT64",
        "description": "The elevation in feet.",
      }
    ]
  }
]

SDK Python

Lorsque vous utilisez le SDK Python, fournissez une liste d'objets ExampleQuery. Pour chaque objet, fournissez des valeurs pour le paramètre natural_language_question (la question qu'un utilisateur peut poser) et les paramètres sql_query. Pour les requêtes paramétrées, vous devez également fournir une liste d'objets QueryParameter.

example_queries = [
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many airports are there?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`"
    ),
    geminidataanalytics.ExampleQuery(
        natural_language_question="How many airports are in {state} with an elevation that is greater than {elevation}?",
        sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports` WHERE LOWER(state_abbreviation) = @state AND elevation > @elevation",
        parameters=[
            geminidataanalytics.QueryParameter(
                name="state",
                data_type="STRING",
                description="The state abbreviation in lowercase.",
            ),
            geminidataanalytics.QueryParameter(
                name="elevation",
                data_type="FLOAT64",
                description="The elevation in feet.",
            ),
        ],
    )
]

Fonctions définies par l'utilisateur

Vous pouvez fournir des fonctions définies par l'utilisateur (UDF) pour BigQuery dans le contexte de l'agent à l'aide du champ user_functions. Lorsque vous fournissez des routines BigQuery personnalisées, l'agent peut les utiliser si elles sont nécessaires pour répondre à une question.

Pour chaque UDF, vous pouvez fournir les propriétés suivantes :

  • routineReference : référence à la routine BigQuery qui inclut l'ID du projet, l'ID d'ensemble de données et l'ID de routine. Pour utiliser une routine dans une région différente de celle de votre point de terminaison d'API (par exemple, si vous accédez à une table dans la région us-east4 à partir du point de terminaison de l'API multirégional us), spécifiez cette région dans le champ boundaryLocationId.
  • description : résumé du comportement de la fonction utilisé par l'agent pour déterminer quand la fonction est appropriée pour une réponse.

Les exemples suivants montrent comment fournir des fonctions définies par l'utilisateur avec des requêtes HTTP directes et avec le SDK Python.

HTTP

Dans une requête HTTP directe, fournissez un objet user_functions contenant une liste bqRoutines. Chaque objet de la liste doit contenir une propriété routineReference et un champ description.

"user_functions": {
  "bqRoutines": [
    {
      "routineReference": {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "routineId": "my_custom_function"
      },
      "description": "Calculates adjusted revenue by using custom logic."
    }
  ]
}

SDK Python

Lorsque vous utilisez le SDK Python, vous pouvez définir ces routines en attribuant une liste d'objets BigQueryRoutine à la propriété bq_routines d'un objet UserFunctions ajouté au contexte de votre agent.

# Define a BigQuery routine (UDF)
bq_routine = geminidataanalytics.BigQueryRoutine()
bq_routine.routine_reference.project_id = "bigquery-public-data"
bq_routine.routine_reference.dataset_id = "thelook_ecommerce"
bq_routine.routine_reference.routine_id = "my_custom_function"
bq_routine.description = "Calculates adjusted revenue by using custom logic."

# Add the routine to the agent's context
user_functions = geminidataanalytics.UserFunctions()
user_functions.bq_routines = [bq_routine]

# Assign to context
context.user_functions = user_functions

Définir un contexte supplémentaire dans les instructions système

Vous pouvez utiliser le paramètre system_instruction pour fournir des conseils supplémentaires pour un contexte qui n'est pas compatible avec les champs de contexte structurés. En fournissant ces conseils supplémentaires, vous pouvez aider l'agent à mieux comprendre le contexte de vos données et de votre cas d'utilisation.

Les instructions système se composent d'une série de composants clés et d'objets qui fournissent à l'agent de données des informations sur la source de données et des conseils sur le rôle de l'agent lorsqu'il répond à des questions. Vous pouvez fournir des instructions système à l'agent de données dans le paramètre system_instruction sous la forme d'une chaîne au format YAML.

Le modèle suivant montre une structure YAML suggérée pour la chaîne, que vous pouvez fournir au paramètre system_instruction pour une source de données BigQuery, y compris les clés disponibles et les types de données attendus. Bien que ce modèle fournisse une structure suggérée avec des composants importants pour définir des instructions système, il n'inclut pas tous les formats d'instructions système possibles.

- system_instruction: str # A description of the expected behavior of the agent. For example: You are a sales agent.
- tables: # A list of tables to describe for the agent.
  - table: # Details about a single table that is relevant for the agent.
    - name: str # The name of the table.
    - fields: # Details about columns (fields) within the table.
      - field: # Details about a single column within the current table.
        - name: str # The name of the column.
        - aggregations: list[str] # Commonly used or default aggregations for the column.
  - relationships: # A list of join relationships between tables.
    - relationship: # Details about a single join relationship.
      - name: str # The name of this join relationship.
      - description: str # A description of the relationship.
      - relationship_type: str # The join relationship type: one-to-one, one-to-many, many-to-one, or many-to-many.
      - join_type: str # The join type: inner, outer, left, right, or full.
      - left_table: str # The name of the left table in the join.
      - right_table: str # The name of the right table in the join.
      - relationship_columns: # A list of columns that are used for the join.
        - left_column: str # The join column from the left table.
        - right_column: str # The join column from the right table.
- glossaries: # A list of definitions for glossary business terms, jargon, and abbreviations.
  - glossary: # The definition for a single glossary item.
    - term: str # The term, phrase, or abbreviation to define.
    - description: str # A description or definition of the term.
    - synonyms: list[str] # Alternative terms for the glossary entry.
- additional_descriptions: # A list of any other general instructions or content.
  - text: str # Any additional general instructions or context not covered elsewhere.

Les sections suivantes présentent des exemples de composants clés pour les instructions système :

system_instruction

Utilisez la clé system_instruction pour définir le rôle et le persona de l'agent. Cette instruction initiale définit le ton et le style des réponses de l'API, et aide l'agent à comprendre son objectif principal.

Par exemple, vous pouvez définir un agent en tant qu'analyste des ventes pour une boutique d'e-commerce fictive comme suit :

-   system_instruction: You are an expert sales analyst for a fictitious
    ecommerce store. You will answer questions about sales, orders, and customer
    data. Your responses should be concise and data-driven.

tables

Bien que vous définissiez les propriétés fondamentales d'une table (telles que sa description et ses synonymes) en tant que contexte structuré, vous pouvez également utiliser la clé tables dans les instructions système pour fournir une logique métier supplémentaire. Pour les sources de données BigQuery, cela inclut l'utilisation de la clé fields pour définir des aggregations par défaut pour des colonnes spécifiques.

L'exemple de bloc de code YAML suivant montre comment utiliser la clé tables dans vos instructions système pour imbriquer des champs qui fournissent des conseils supplémentaires pour la table bigquery-public-data.thelook_ecommerce.orders :

-   tables:
  -   table:
    -   name: bigquery-public-data.thelook_ecommerce.orders
    -   fields:
      -   field:
        -   name: num_of_items
        -   aggregations: 'sum, avg'

relationships

La clé relationships de vos instructions système contient une liste des relations de jointure entre les tables. En définissant des relations de jointure, vous pouvez aider l'agent à comprendre comment joindre des données provenant de plusieurs tables lorsqu'il répond à des questions.

Par exemple, vous pouvez définir une relation orders_to_user entre la table bigquery-public-data.thelook_ecommerce.orders et la table bigquery-public-data.thelook_ecommerce.users comme suit :

-   relationships:
  -   relationship:
    -   name: orders_to_user
    -   description: >-
        Connects customer order data to user information with the user_id and id fields to allow an aggregated view of sales by customer demographics.
    -   relationship_type: many-to-one
    -   join_type: left
    -   left_table: bigquery-public-data.thelook_ecommerce.orders
    -   right_table: bigquery-public-data.thelook_ecommerce.users
    -   relationship_columns:
      -   left_column: user_id
      -   right_column: id

glossaries

La clé glossaries de vos instructions système liste les définitions de termes métier, le jargon et les abréviations qui ont une pertinence pour vos données et votre cas d'utilisation. En fournissant des définitions de glossaire, vous pouvez aider l'agent à interpréter les questions qui utilisent un langage métier spécifique et à y répondre avec précision. Si un agent utilise un terme de glossaire pour répondre à une question, il peut citer ce terme dans sa réponse.

Par exemple, vous pouvez définir des termes tels que les états d'activité courants et "OMPF" en fonction de votre contexte métier spécifique comme suit :

- glossaries:
  - glossary:
    - term: complete
    - description: Represents an order status where the order has been completed.
    - synonyms: 'finish, done, fulfilled'
  - glossary:
    - term: shipped
    - description: Represents an order status where the order has been shipped to the customer.
  - glossary:
    - term: returned
    - description: Represents an order status where the customer has returned the order.
  - glossary:
    - term: OMPF
    - description: Order Management and Product Fulfillment

additional_descriptions

Utilisez la clé additional_descriptions pour fournir des instructions générales ou un contexte qui ne correspond pas à d'autres champs de contexte structurés ou d'instructions système. En fournissant des descriptions supplémentaires dans vos instructions système, vous pouvez aider l'agent à mieux comprendre le contexte de vos données et de votre cas d'utilisation.

Par exemple, vous pouvez utiliser la clé additional_descriptions pour fournir des informations sur votre organisation comme suit :

-   additional_descriptions:
  -   text: All the sales data pertains to The Look, a fictitious ecommerce store.
  -   text: 'Orders can be of three categories: food, clothes, and electronics.'

Exemple : Contexte créé pour un agent commercial

L'exemple suivant pour un agent d'analyse des ventes fictif montre comment fournir un contexte créé en combinant un contexte structuré et des instructions système.

Exemple : Contexte structuré

Vous pouvez fournir un contexte structuré avec des détails sur les tables, les colonnes et des exemples de requêtes pour guider l'agent, comme illustré dans les exemples HTTP et SDK Python suivants.

HTTP

L'exemple suivant montre comment définir un contexte structuré dans une requête HTTP :

{
  "bq": {
    "tableReferences": [
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "orders",
        "schema": {
          "description": "Data for orders in The Look, a fictitious ecommerce store.",
          "synonyms": ["sales"],
          "tags": ["sale", "order", "sales_order"],
          "fields": [
            {
              "name": "status",
              "description": "The current status of the order."
            },
            {
              "name": "num_of_items",
              "description": "The number of items in the order."
            }
          ]
        }
      },
      {
        "projectId": "bigquery-public-data",
        "datasetId": "thelook_ecommerce",
        "tableId": "users",
        "schema": {
          "description": "Data for users in The Look, a fictitious ecommerce store.",
          "synonyms": ["customers"],
          "tags": ["user", "customer", "buyer"],
          "fields": [
            {
              "name": "first_name",
              "description": "The first name of the user.",
              "tags": ["person"]
            },
            {
              "name": "last_name",
              "description": "The last name of the user.",
              "tags": ["person"]
            },
            {
              "name": "age_group",
              "description": "The age demographic group of the user."
            },
            {
              "name": "email",
              "description": "The email address of the user.",
              "tags": ["contact"]
            }
          ]
        }
      }
    ]
  },
  "example_queries": [
    {
      "naturalLanguageQuestion": "How many orders are there?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`"
    },
    {
      "naturalLanguageQuestion": "How many orders were shipped?",
      "sqlQuery": "SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'"
    },
    {
      "naturalLanguageQuestion": "How many unique customers are there?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`"
    },
    {
      "naturalLanguageQuestion": "How many users in the 25-34 age group have a cymbalgroup email address?",
      "sqlQuery": "SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'"
    }
  ]
}

SDK Python

L'exemple suivant montre comment définir un contexte structuré avec le SDK Python :

# Define context for the 'orders' table
bigquery_table_reference_1 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_1.project_id = "bigquery-public-data"
bigquery_table_reference_1.dataset_id = "thelook_ecommerce"
bigquery_table_reference_1.table_id = "orders"

bigquery_table_reference_1.schema = geminidataanalytics.Schema()
bigquery_table_reference_1.schema.description = "Data for orders in The Look, a fictitious ecommerce store."
bigquery_table_reference_1.schema.synonyms = ["sales"]
bigquery_table_reference_1.schema.tags = ["sale", "order", "sales_order"]
bigquery_table_reference_1.schema.fields = [
    geminidataanalytics.Field(
        name="status",
        description="The current status of the order.",
    ),
    geminidataanalytics.Field(
        name="num_of_items",
        description="The number of items in the order."
    )
]

# Define context for the 'users' table
bigquery_table_reference_2 = geminidataanalytics.BigQueryTableReference()
bigquery_table_reference_2.project_id = "bigquery-public-data"
bigquery_table_reference_2.dataset_id = "thelook_ecommerce"
bigquery_table_reference_2.table_id = "users"

bigquery_table_reference_2.schema = geminidataanalytics.Schema()
bigquery_table_reference_2.schema.description = "Data for users in The Look, a fictitious ecommerce store."
bigquery_table_reference_2.schema.synonyms = ["customers"]
bigquery_table_reference_2.schema.tags = ["user", "customer", "buyer"]
bigquery_table_reference_2.schema.fields = [
    geminidataanalytics.Field(
        name="first_name",
        description="The first name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="last_name",
        description="The last name of the user.",
        tags=["person"],
    ),
    geminidataanalytics.Field(
        name="age_group",
        description="The age demographic group of the user.",
    ),
    geminidataanalytics.Field(
        name="email",
        description="The email address of the user.",
        tags=["contact"],
    )
]

# Define example queries
example_queries = [
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders are there?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many orders were shipped?",
      sql_query="SELECT COUNT(*) FROM `bigquery-public-data.thelook_ecommerce.orders` WHERE status = 'shipped'",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many unique customers are there?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users`",
  ),
  geminidataanalytics.ExampleQuery(
      natural_language_question="How many users in the 25-34 age group have a cymbalgroup email address?",
      sql_query="SELECT COUNT(DISTINCT id) FROM `bigquery-public-data.thelook_ecommerce.users` WHERE users.age_group = '25-34' AND users.email LIKE '%@cymbalgroup.com'",
  )
]

Exemple : Instructions système

Les instructions système suivantes complètent le contexte structuré en définissant le persona de l'agent et en fournissant des conseils qui ne sont pas compatibles avec les champs structurés, tels que les définitions de relations, les termes de glossaire, les descriptions supplémentaires et les détails supplémentaires de la table orders. Dans cet exemple, étant donné que la table users est entièrement définie avec un contexte structuré, il n'est pas nécessaire de la redéfinir dans les instructions système.

-   system_instruction: >-
    You are an expert sales analyst for a fictitious ecommerce store. You will answer questions about sales, orders, and customer data. Your responses should be concise and data-driven.
-   tables:
    -   table:
        -   name: bigquery-public-data.thelook_ecommerce.orders
        -   fields:
            -   field:
                -   name: num_of_items
                -   aggregations: 'sum, avg'
-   relationships:
    -   relationship:
        -   name: orders_to_user
        -   description: >-
            Connects customer order data to user information with the user_id and id fields.
        - relationship_type: many-to-one
        - join_type: left
        - left_table: bigquery-public-data.thelook_ecommerce.orders
        - right_table: bigquery-public-data.thelook_ecommerce.users
        - relationship_columns:
            - left_column: user_id
            - right_column: id
- glossaries:
    - glossary:
        - term: complete
        - description: Represents an order status where the order has been completed.
        - synonyms: 'finish, done, fulfilled'
    - glossary:
        - term: OMPF
        - description: Order Management and Product Fulfillment
- additional_descriptions:
    - text: All the sales data pertains to The Look, a fictitious ecommerce store.