Define el contexto del agente de datos para las fuentes de datos de BigQuery

En esta página, se describe cómo proporcionar contexto creado para agentes de datos que usan fuentes de datos de BigQuery.

El contexto creado es la orientación que los propietarios de los agentes de datos pueden proporcionar para dar forma al comportamiento de un agente de datos y refinar las respuestas de la API. Un contexto creado eficaz proporciona a tus agentes de datos de la API de Conversational Analytics un contexto útil para responder preguntas sobre tus fuentes de datos.

Si bien el contexto creado es opcional, proporcionar un contexto sólido permite que el agente brinde respuestas más precisas y pertinentes. Tu agente de datos incorpora este contexto durante su creación y tiempo de ejecución para garantizar que sus acciones, consultas y respuestas sean precisas, cumplan con los requisitos y tengan en cuenta la empresa. Este contexto se ingiere, se indexa y se usa para dar forma al comportamiento del agente.

Opciones para proporcionar contexto creado

Para las fuentes de datos de BigQuery, puedes proporcionar contexto creado a través de una combinación de contexto estructurado y de instrucciones del sistema. Siempre que sea posible, proporciona contexto a través de campos de contexto estructurado. Luego, usa el parámetro system_instruction para obtener orientación complementaria que no esté cubierta por los campos estructurados, como definir el tono o el comportamiento general de un agente.

Después de definir los campos estructurados y las instrucciones del sistema que componen tu contexto creado, puedes proporcionarle ese contexto a la API en una de las siguientes llamadas:

Define campos de contexto estructurado

En esta sección, se describe cómo proporcionar contexto a un agente de datos mediante campos de contexto estructurado. Puedes proporcionar la siguiente información a un agente como contexto estructurado:

Contexto estructurado a nivel de la tabla

Usa la clave tableReferences para proporcionar a un agente detalles sobre las tablas específicas que están disponibles para responder preguntas. Para cada referencia de tabla, puedes usar los siguientes campos de contexto estructurado para definir el esquema de una tabla:

  • description: Un resumen del contenido y el propósito de la tabla
  • synonyms: Una lista de términos alternativos que se pueden usar para hacer referencia a la tabla
  • tags: Una lista de palabras clave o etiquetas asociadas con la tabla

En los siguientes ejemplos, se muestra cómo proporcionar estas propiedades como contexto estructurado dentro de las solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, proporcionas estas propiedades a nivel de la tabla dentro del objeto schema para la referencia de tabla pertinente. Para obtener un ejemplo completo de cómo estructurar la carga útil de la solicitud completa, consulta Conéctate a los datos de 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"]
    }
  }
]

Python SDK

Cuando usas el SDK de Python, puedes definir estas propiedades a nivel de la tabla en la propiedad schema de un objeto BigQueryTableReference. En el siguiente ejemplo, se muestra cómo crear objetos de referencia de tabla que proporcionan contexto para las tablas orders y users. Para obtener un ejemplo completo de cómo compilar y usar objetos de referencia de tabla, consulta Conéctate a los datos de 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"]

Contexto estructurado a nivel de la columna

La clave fields, que está anidada dentro del objeto schema de una referencia de tabla, toma una lista de objetos field para describir columnas individuales. No todos los campos necesitan contexto adicional. Sin embargo, para los campos de uso frecuente, la inclusión de detalles adicionales puede ayudar a mejorar el rendimiento del agente.

Para cada objeto field, puedes usar los siguientes campos de contexto estructurado para definir las propiedades fundamentales de una columna:

  • description: Una breve descripción del contenido y el propósito de la columna
  • synonyms: Una lista de términos alternativos que se pueden usar para hacer referencia a la columna
  • tags: Una lista de palabras clave o etiquetas asociadas con la columna

En los siguientes ejemplos, se muestra cómo puedes proporcionar estas propiedades como contexto estructurado para el campo status dentro de la tabla orders y para el campo first_name dentro de la tabla users con solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, puedes definir estas propiedades a nivel de la columna proporcionando una lista de objetos fields dentro del objeto schema de una referencia de tabla.

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

Python SDK

Cuando usas el SDK de Python, puedes definir estas propiedades a nivel de la columna asignando una lista de objetos Field a la propiedad fields de la propiedad schema de una tabla.

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

Consultas de ejemplo

La clave example_queries toma una lista de objetos example_query que definen consultas en lenguaje natural para ayudar al agente a proporcionar respuestas más precisas y pertinentes. Si le proporcionas al agente una pregunta en lenguaje natural y su consulta en SQL correspondiente, puedes guiarlo para que proporcione resultados de mayor calidad y más coherentes.

Si la pregunta de un usuario coincide semánticamente con una consulta de ejemplo definida, el agente podría ejecutar esa consulta directamente en lugar de generar una nueva. Cuando un agente ejecuta una consulta existente, la respuesta de la API incluye un objeto matched_query para indicar que se usó una consulta verificada. El agente también puede citar esa consulta en su respuesta.

Consultas de ejemplo parametrizadas

Además de las consultas estáticas, puedes definir consultas de ejemplo parametrizadas que permitan que el agente sustituya valores dinámicos en una plantilla de consulta verificada. Si incluyes parámetros en tus consultas de ejemplo, puedes crear plantillas flexibles que abarquen una gama más amplia de consultas de usuarios que los ejemplos estáticos. Cuando la pregunta de un usuario coincide con una plantilla, el agente ejecuta la consulta correspondiente para proporcionar una respuesta verificada.

Puedes definir una consulta parametrizada de la siguiente manera:

  1. En el campo naturalLanguageQuestion, usa llaves para los marcadores de posición, como {state}.
  2. En el campo sqlQuery, usa la sintaxis de parámetros con nombre de BigQuery para la misma variable, como @state.
  3. En el campo parameters, define el nombre, el tipo de datos y la descripción de cada parámetro.

Ejemplos

En los siguientes ejemplos, se muestra cómo definir consultas de ejemplo estáticas y parametrizadas para el conjunto de datos de aeropuertos de la FAA.

HTTP

En una solicitud HTTP directa, proporciona una lista de objetos example_query en el campo example_queries. Para cada objeto, proporciona la clave naturalLanguageQuestion (la pregunta que podría hacer un usuario) y su clave sqlQuery correspondiente. Para las consultas parametrizadas, también debes proporcionar una lista parameters que incluya el nombre, el tipo de datos y la descripción de cada parámetro.

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

Python SDK

Cuando uses el SDK de Python, proporciona una lista de objetos ExampleQuery. Para cada objeto, proporciona valores para el parámetro natural_language_question (la pregunta que podría hacer un usuario) y los parámetros sql_query. Para las consultas parametrizadas, también debes proporcionar una lista de objetos 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.",
            ),
        ],
    )
]

Funciones definidas por el usuario

Puedes proporcionar funciones definidas por el usuario (UDF) para BigQuery en el contexto del agente con el campo user_functions. Cuando proporcionas rutinas personalizadas de BigQuery, el agente puede usarlas si son necesarias para responder a una pregunta.

Para cada UDF, puedes proporcionar las siguientes propiedades:

  • routineReference: Una referencia a la rutina de BigQuery que incluye el ID del proyecto, el ID del conjunto de datos y el ID de la rutina. Para usar una rutina en una región diferente de tu extremo de API (por ejemplo, si accedes a una tabla en la región us-east4 desde el extremo de API multirregional us), especifica esa región en el campo boundaryLocationId.
  • description: Un resumen del comportamiento de la función que usa el agente para determinar cuándo la función es adecuada para una respuesta.

En los siguientes ejemplos, se muestra cómo proporcionar funciones definidas por el usuario con solicitudes HTTP directas y con el SDK de Python.

HTTP

En una solicitud HTTP directa, proporciona un objeto user_functions que contenga una lista bqRoutines. Cada objeto de la lista debe contener una propiedad routineReference y 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."
    }
  ]
}

Python SDK

Cuando usas el SDK de Python, puedes definir estas rutinas asignando una lista de objetos BigQueryRoutine a la propiedad bq_routines de un objeto UserFunctions que se agrega al contexto de tu 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

Define contexto adicional en las instrucciones del sistema

Puedes usar el parámetro system_instruction para proporcionar orientación complementaria para el contexto que no admiten los campos de contexto estructurado. Si proporcionas esta orientación adicional, puedes ayudar al agente a comprender mejor el contexto de tus datos y tu caso de uso.

Las instrucciones del sistema constan de una serie de componentes y objetos clave que proporcionan al agente de datos detalles sobre la fuente de datos y orientación sobre el rol del agente cuando responde preguntas. Puedes proporcionar instrucciones del sistema al agente de datos en el parámetro system_instruction como una cadena con formato YAML.

En la siguiente plantilla, se muestra una estructura YAML sugerida para la cadena, que puedes proporcionar al parámetro system_instruction para una fuente de datos de BigQuery, incluidas las claves disponibles y los tipos de datos esperados. Si bien esta plantilla proporciona una estructura sugerida con componentes importantes para definir las instrucciones del sistema, no incluye todos los formatos posibles de instrucciones del 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.

Las siguientes secciones contienen ejemplos de componentes clave de las instrucciones del sistema:

system_instruction

Usa la clave system_instruction para definir el rol y el arquetipo del agente. Esta instrucción inicial establece el tono y el estilo de las respuestas de la API, y ayuda al agente a comprender su propósito principal.

Por ejemplo, puedes definir un agente como analista de ventas para una tienda de comercio electrónico ficticia de la siguiente manera:

-   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

Si bien defines las propiedades fundamentales de una tabla (como su descripción y sinónimos) como contexto estructurado, también puedes usar la clave tables dentro de las instrucciones del sistema para proporcionar lógica empresarial complementaria. Para las fuentes de datos de BigQuery, esto incluye usar la clave fields para definir aggregations predeterminadas para columnas específicas.

En el siguiente bloque de código YAML de muestra, se muestra cómo puedes usar la clave tables dentro de las instrucciones del sistema para anidar campos que proporcionan orientación complementaria para la tabla 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 clave relationships de las instrucciones del sistema contiene una lista de relaciones de unión entre tablas. Si defines relaciones de unión, puedes ayudar al agente a comprender cómo unir datos de varias tablas cuando responde preguntas.

Por ejemplo, puedes definir una relación orders_to_user entre la tabla bigquery-public-data.thelook_ecommerce.orders y la tabla bigquery-public-data.thelook_ecommerce.users de la siguiente manera:

-   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 clave glossaries de las instrucciones del sistema enumera las definiciones de términos empresariales, jerga y abreviaturas que son pertinentes para tus datos y tu caso de uso. Si proporcionas definiciones de glosario, puedes ayudar al agente a interpretar y responder con precisión las preguntas que usan un lenguaje empresarial específico. Si un agente usa un término del glosario para responder una pregunta, puede citar ese término en su respuesta.

Por ejemplo, puedes definir términos como estados empresariales comunes y "OMPF" según tu contexto empresarial específico de la siguiente manera:

- 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

Usa la clave additional_descriptions para proporcionar instrucciones o contexto generales que no se ajusten a otros campos de contexto estructurado o de instrucciones del sistema. Si proporcionas descripciones adicionales en las instrucciones del sistema, puedes ayudar al agente a comprender mejor el contexto de tus datos y tu caso de uso.

Por ejemplo, puedes usar la clave additional_descriptions para proporcionar información sobre tu organización de la siguiente manera:

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

Ejemplo: Contexto creado para un agente de ventas

En el siguiente ejemplo para un agente de analista de ventas ficticio, se muestra cómo proporcionar contexto creado mediante una combinación de contexto estructurado y de instrucciones del sistema.

Ejemplo: Contexto estructurado

Puedes proporcionar contexto estructurado con detalles sobre tablas, columnas y consultas de ejemplo para guiar al agente, como se muestra en los siguientes ejemplos del SDK de HTTP y Python.

HTTP

En el siguiente ejemplo, se muestra cómo definir contexto estructurado en una solicitud 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'"
    }
  ]
}

Python SDK

En el siguiente ejemplo, se muestra cómo definir contexto estructurado con el SDK de 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'",
  )
]

Ejemplo: Instrucciones del sistema

Las siguientes instrucciones del sistema complementan el contexto estructurado definiendo el arquetipo del agente y proporcionando orientación que no admiten los campos estructurados, como definiciones de relaciones, términos del glosario, descripciones adicionales y detalles complementarios de la tabla orders. En este ejemplo, debido a que la tabla users está completamente definida con contexto estructurado, no es necesario volver a definirla en las instrucciones del 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.