Definisci il contesto dell'agente di dati per le origini dati BigQuery

In questa pagina viene descritto come fornire un contesto creato per gli agenti di dati che utilizzano origini dati BigQuery.

Il contesto creato è una guida che i proprietari degli agenti di dati possono fornire per definire il comportamento di un agente di dati e perfezionare le risposte dell'API. Un contesto creato efficace fornisce agli agenti di dati dell'API Analisi conversazionale un contesto utile per rispondere alle domande sulle origini dati.

Anche se il contesto creato è facoltativo, fornirne uno efficace consente all'agente di fornire risposte più accurate e pertinenti. L'agente di dati incorpora questo contesto durante la creazione e l'esecuzione per garantire che le azioni, le query e le risposte siano accurate, conformi e consapevoli dell'attività. Questo contesto viene inserito, indicizzato e utilizzato per definire il comportamento dell'agente.

Opzioni per fornire un contesto creato

Per le origini dati BigQuery, puoi fornire un contesto creato tramite una combinazione di contesto strutturato e istruzioni di sistema. Quando possibile, fornisci il contesto tramite i campi del contesto strutturato. Poi utilizza il parametro system_instruction per indicazioni supplementari non coperte dai campi strutturati, ad esempio la definizione del tono o del comportamento generale di un agente.

Dopo aver definito i campi strutturati e le istruzioni di sistema che compongono il contesto creato, puoi fornirlo all'API in una delle seguenti chiamate:

Definire i campi del contesto strutturato

In questa sezione viene descritto come fornire il contesto a un agente di dati utilizzando i campi del contesto strutturato. Puoi fornire le seguenti informazioni a un agente come contesto strutturato:

Contesto strutturato a livello di tabella

Utilizza la chiave tableReferences per fornire a un agente i dettagli delle tabelle specifiche disponibili per rispondere alle domande. Per ogni riferimento alla tabella, puoi utilizzare i seguenti campi del contesto strutturato per definire lo schema di una tabella:

  • description: un riepilogo dei contenuti e dello scopo della tabella
  • synonyms: un elenco di termini alternativi che possono essere utilizzati per fare riferimento alla tabella
  • tags: un elenco di parole chiave o tag associati alla tabella

Gli esempi seguenti mostrano come fornire queste proprietà come contesto strutturato all'interno delle richieste HTTP dirette e con l'SDK Python.

HTTP

In una richiesta HTTP diretta, fornisci queste proprietà a livello di tabella all'interno dell'oggetto schema per il riferimento alla tabella pertinente. Per un esempio completo di come strutturare il payload della richiesta completa, consulta Connettersi ai dati 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

Quando utilizzi l'SDK Python, puoi definire queste proprietà a livello di tabella nella proprietà schema di un oggetto BigQueryTableReference. L'esempio seguente mostra come creare oggetti di riferimento alla tabella che forniscono il contesto per le tabelle orders e users. Per un esempio completo di come creare e utilizzare gli oggetti di riferimento alla tabella, consulta Connettersi ai dati BigQuery data.

# 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"]

Contesto strutturato a livello di colonna

La chiave fields, nidificata all'interno dell'oggetto schema di un riferimento alla tabella, accetta un elenco di oggetti field per descrivere le singole colonne. Non tutti i campi richiedono un contesto aggiuntivo; tuttavia, per i campi di uso comune, l'inclusione di dettagli aggiuntivi può contribuire a migliorare il rendimento dell'agente.

Per ogni oggetto field, puoi utilizzare i seguenti campi del contesto strutturato per definire le proprietà fondamentali di una colonna:

  • description: una breve descrizione dei contenuti e dello scopo della colonna
  • synonyms: un elenco di termini alternativi che possono essere utilizzati per fare riferimento alla colonna
  • tags: un elenco di parole chiave o tag associati alla colonna

Gli esempi seguenti mostrano come fornire queste proprietà come contesto strutturato per il campo status all'interno della tabella orders e per il campo first_name all'interno della tabella users con richieste HTTP dirette e con l'SDK Python.

HTTP

In una richiesta HTTP diretta, puoi definire queste proprietà a livello di colonna fornendo un elenco di oggetti fields all'interno dell'oggetto schema di un riferimento alla tabella.

"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

Quando utilizzi l'SDK Python, puoi definire queste proprietà a livello di colonna assegnando un elenco di oggetti Field alla proprietà fields della proprietà schema di una tabella.

# 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"],
    )
]

Query di esempio

La chiave example_queries accetta un elenco di oggetti example_query che definiscono le query in linguaggio naturale per aiutare l'agente a fornire risposte più accurate e pertinenti. Fornendo all'agente sia una domanda in linguaggio naturale sia la query SQL corrispondente, puoi guidarlo a fornire risultati di qualità superiore e più coerenti.

Se la domanda di un utente corrisponde semanticamente a una query di esempio definita, l'agente potrebbe eseguire direttamente la query anziché generarne una nuova. Quando un agente esegue una query esistente, la risposta dell'API include un oggetto matched_query per indicare che è stata utilizzata una query verificata. L'agente potrebbe anche citare la query nella risposta.

Query di esempio con parametri

Oltre alle query statiche, puoi definire query di esempio con parametri che consentono all'agente di sostituire i valori dinamici in un modello di query verificato. Includendo i parametri nelle query di esempio, puoi creare modelli flessibili che coprono una gamma più ampia di richieste degli utenti rispetto agli esempi statici. Quando la domanda di un utente corrisponde a un modello, l'agente esegue la query corrispondente per fornire una risposta verificata.

Puoi definire una query con parametri nel seguente modo:

  1. Nel campo naturalLanguageQuestion, utilizza le parentesi graffe per i segnaposto, ad esempio {state}.
  2. Nel campo sqlQuery, utilizza la sintassi dei parametri denominati BigQuery per la stessa variabile, ad esempio @state.
  3. Nel campo parameters, definisci il nome, il tipo di dati e la descrizione di ogni parametro.

Esempi

Gli esempi seguenti mostrano come definire query di esempio statiche e con parametri per il set di dati degli aeroporti FAA.

HTTP

In una richiesta HTTP diretta, fornisci un elenco di oggetti example_query nel campo example_queries. Per ogni oggetto, fornisci la chiave naturalLanguageQuestion (la domanda che un utente potrebbe porre) e la chiave sqlQuery corrispondente. Per le query con parametri, devi anche fornire un elenco parameters che includa il nome, il tipo di dati e la descrizione di ogni parametro.

"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

Quando utilizzi l'SDK Python, fornisci un elenco di oggetti ExampleQuery. Per ogni oggetto, fornisci i valori per i parametri natural_language_question (la domanda che un utente potrebbe porre) e sql_query. Per le query con parametri, devi anche fornire un elenco di oggetti 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.",
            ),
        ],
    )
]

Funzioni definite dall'utente

Puoi fornire funzioni definite dall'utente (UDF) per BigQuery nel contesto dell'agente utilizzando il campo user_functions. Quando fornisci routine BigQuery personalizzate, l'agente può utilizzarle se sono necessarie per rispondere a una domanda.

Per ogni UDF, puoi fornire le seguenti proprietà:

  • routineReference: un riferimento alla routine BigQuery che include l'ID progetto, l'ID set di dati e l'ID routine. Per utilizzare una routine in una regione diversa dall'endpoint API (ad esempio, se accedi a una tabella nella regione us-east4 dall'endpoint API multiregionale us), specifica la regione nel campo boundaryLocationId.
  • description: un riepilogo del comportamento della funzione utilizzato dall'agente per determinare quando la funzione è appropriata per una risposta.

Gli esempi seguenti mostrano come fornire funzioni definite dall'utente con richieste HTTP dirette e con l'SDK Python.

HTTP

In una richiesta HTTP diretta, fornisci un oggetto user_functions contenente un elenco bqRoutines. Ogni oggetto nell'elenco deve contenere una proprietà routineReference e un campo 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

Quando utilizzi l'SDK Python, puoi definire queste routine assegnando un elenco di oggetti BigQueryRoutine alla proprietà bq_routines di un oggetto UserFunctions aggiunto al contesto dell'agente.

# 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

Definire un contesto aggiuntivo nelle istruzioni di sistema

Puoi utilizzare il parametro system_instruction per fornire indicazioni supplementari per il contesto non supportato dai campi del contesto strutturato. Fornendo queste indicazioni aggiuntive, puoi aiutare l'agente a comprendere meglio il contesto dei dati e del caso d'uso.

Le istruzioni di sistema sono costituite da una serie di componenti e oggetti chiave che forniscono all'agente di dati i dettagli sull'origine dati e indicazioni sul ruolo dell'agente quando risponde alle domande. Puoi fornire le istruzioni di sistema all'agente di dati nel parametro system_instruction come stringa in formato YAML.

Il seguente modello mostra una struttura YAML suggerita per la stringa, che puoi fornire al parametro system_instruction per un'origine dati BigQuery, inclusi i tasti disponibili e i tipi di dati previsti. Sebbene questo modello fornisca una struttura suggerita con componenti importanti per la definizione delle istruzioni di sistema, non include tutti i formati possibili delle istruzioni di sistema.

- 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.

Le seguenti sezioni contengono esempi di componenti chiave delle istruzioni di sistema:

system_instruction

Utilizza la chiave system_instruction per definire il ruolo e l'utente tipo dell'agente. Questa istruzione iniziale imposta il tono e lo stile delle risposte dell'API e aiuta l'agente a comprendere il suo scopo principale.

Ad esempio, puoi definire un agente come analista delle vendite per un negozio di e-commerce fittizio nel seguente modo:

-   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

Sebbene tu definisca le proprietà fondamentali di una tabella (come la descrizione e i sinonimi) come contesto strutturato, puoi anche utilizzare la chiave tables all'interno delle istruzioni di sistema per fornire una logica di business supplementare. Per le origini dati BigQuery, ciò include l'utilizzo della chiave fields per definire le aggregations predefinite per colonne specifiche.

Il seguente blocco di codice YAML di esempio mostra come utilizzare la chiave tables all'interno delle istruzioni di sistema per nidificare i campi che forniscono indicazioni supplementari per la tabella 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 chiave relationships nelle istruzioni di sistema contiene un elenco di relazioni di unione tra le tabelle. Definendo le relazioni di unione, puoi aiutare l'agente a comprendere come unire i dati di più tabelle quando risponde alle domande.

Ad esempio, puoi definire una relazione orders_to_user tra la tabella bigquery-public-data.thelook_ecommerce.orders e la tabella bigquery-public-data.thelook_ecommerce.users nel seguente modo:

-   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 chiave glossaries nelle istruzioni di sistema elenca le definizioni dei termini aziendali, del gergo e delle abbreviazioni pertinenti ai dati e al caso d'uso. Fornendo le definizioni del glossario, puoi aiutare l'agente a interpretare e rispondere con precisione alle domande che utilizzano un linguaggio aziendale specifico. Se un agente utilizza un termine del glossario per rispondere a una domanda, potrebbe citare il termine nella risposta.

Ad esempio, puoi definire termini come gli stati aziendali comuni e "OMPF" in base al contesto aziendale specifico nel seguente modo:

- 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

Utilizza la chiave additional_descriptions per fornire istruzioni o contesto generali che non rientrano in altri campi del contesto strutturato o delle istruzioni di sistema. Fornendo descrizioni aggiuntive nelle istruzioni di sistema, puoi aiutare l'agente a comprendere meglio il contesto dei dati e del caso d'uso.

Ad esempio, puoi utilizzare la chiave additional_descriptions per fornire informazioni sulla tua organizzazione nel seguente modo:

-   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.'

Esempio: contesto creato per un agente di vendita

Il seguente esempio per un agente di analisi delle vendite fittizio mostra come fornire un contesto creato utilizzando una combinazione di contesto strutturato e istruzioni di sistema.

Esempio: contesto strutturato

Puoi fornire un contesto strutturato con dettagli su tabelle, colonne e query di esempio per guidare l'agente, come mostrato negli esempi di SDK HTTP e Python riportati di seguito.

HTTP

L'esempio seguente mostra come definire un contesto strutturato in una richiesta 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'esempio seguente mostra come definire un contesto strutturato con l'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'",
  )
]

Esempio: istruzioni di sistema

Le seguenti istruzioni di sistema integrano il contesto strutturato definendo l'utente tipo dell'agente e fornendo indicazioni non supportate dai campi strutturati, come definizioni delle relazioni, termini del glossario, descrizioni aggiuntive e dettagli supplementari della tabella orders. In questo esempio, poiché la tabella users è completamente definita con il contesto strutturato, non è necessario ridefinirla nelle istruzioni di sistema.

-   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.