Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Genera consultas en SQL con preguntas en lenguaje natural

El lenguaje natural de AlloyDB AI te permite compilar aplicaciones de IA generativa para el usuario que traducen preguntas en lenguaje natural en consultas en SQL en tu base de datos. Puedes instalar la extensión alloydb_ai_nl, registrar el esquema de tu base de datos, agregar contexto de dominio y plantillas de consultas, y generar instrucciones en SQL a partir de entradas de lenguaje natural.

Para habilitar la extensión alloydb_ai_nl, que es la API de compatibilidad con lenguaje natural de AlloyDB para PostgreSQL, debes seguir estos pasos de alto nivel:

Instala la extensión de alloydb_ai_nl.
Define una configuración de lenguaje natural para tu aplicación.
Registra un esquema.
Agrega contexto.
Agrega plantillas de consulta.
Definir tipos de conceptos y crear un índice de valores
Genera sentencias de SQL con una interfaz de lenguaje natural.

Antes de comenzar

Comprender cómo conectarse a la base de datos de AlloyDB y ejecutar comandos de PostgreSQL Para obtener más información, consulta Descripción general de la conexión y Elige cómo conectarte a AlloyDB.
Completa la base de datos con los datos y el esquema a los que el usuario final desea acceder.

Habilita la extensión requerida

Antes de instalar y usar el lenguaje natural de AlloyDB AI, debes habilitar la extensión agregando la marca alloydb_ai_nl.enabled.

Dado que los objetos de lenguaje natural de AlloyDB AI creados en la instancia principal se propagan a las réplicas de solo lectura y a las réplicas entre regiones, asegúrate de habilitar la marca de lenguaje natural de AlloyDB AI en cada instancia de AlloyDB para PostgreSQL. Para obtener más información, consulta Configura las marcas de base de datos de una instancia.

Crea un clúster y habilita la integración de Gemini Enterprise Agent Platform

Crea un clúster y una instancia de AlloyDB. Usas la instancia de AlloyDB para crear la base de datos y el esquema de la aplicación.
Habilita la integración de Agent Platform. Para obtener más información, consulta Cómo realizar la integración con Agent Platform.

Roles obligatorios

Para instalar la extensión de alloydb_ai_nl y otorgar acceso a otros usuarios, debes tener el siguiente rol de Identity and Access Management (IAM) en el proyecto de Google Cloud que estás usando:

roles/alloydb.admin (el rol de IAM predefinido de administrador de AlloyDB)

Para obtener más información, consulta Administra usuarios de PostgreSQL con autenticación estándar.

Prepara el entorno

Para prepararte para generar consultas de lenguaje natural, debes instalar la extensión obligatoria, crear una configuración y registrar un esquema.

Instala la extensión de `alloydb_ai_nl`

La extensión alloydb_ai_nl usa la extensión google_ml_integration, que interactúa con modelos de lenguaje grandes (LLM), incluidos los modelos de Gemini en Agent Platform.

Para instalar la extensión alloydb_ai_nl, conéctate a la base de datos y ejecuta el siguiente comando:

CREATE EXTENSION alloydb_ai_nl cascade;

Actualiza la extensión `alloydb_ai_nl`

Asegúrate de tener la versión más reciente de la extensión de alloydb_ai_nl. Si ya instalaste la extensión, verifica si hay una nueva versión disponible y actualízala si no estás usando la versión más reciente. Para obtener más información sobre la extensión alloydb_ai_nl, consulta la descripción general del lenguaje natural de AlloyDB AI.

Determina si necesitas actualizar la extensión. Si la default_version es posterior a la installed_version, actualiza la extensión.
```
SELECT * FROM pg_available_extensions where name = 'alloydb_ai_nl';
```
Actualiza la extensión.
```
ALTER EXTENSION alloydb_ai_nl UPDATE;
```

Crea una configuración de lenguaje natural y registra un esquema

El lenguaje natural de AlloyDB AI usa nl_config para asociar aplicaciones a ciertos esquemas, plantillas de consultas y extremos de modelos. nl_config es una configuración que asocia una aplicación a un esquema, plantillas y otros contextos. Una aplicación grande también puede usar diferentes parámetros de configuración para distintas partes de la aplicación, siempre que especifiques la configuración correcta cuando se envíe una pregunta desde esa parte de la aplicación. Puedes registrar un esquema completo o registrar objetos de esquema específicos, como tablas, vistas y columnas.

Para crear una configuración de lenguaje natural, usa el siguiente ejemplo:
```
SELECT
  alloydb_ai_nl.g_create_configuration(
    'my_app_config'        -- configuration_id
  );
```
gemini-2.0-flash:generateContent es el extremo del modelo.

Registra un esquema para una configuración especificada con el siguiente ejemplo:

SELECT
  alloydb_ai_nl.g_manage_configuration(
    operation => 'register_schema',
    configuration_id_in => 'my_app_config',
    schema_names_in => '{my_schema}'
  );

Agrega contexto

El contexto incluye cualquier tipo de información que puedas usar para responder una pregunta del usuario final, como la siguiente:

Estructura y relaciones del esquema
Resúmenes y descripciones de columnas
Valores de columna y su semántica
Reglas o declaraciones de lógica empresarial específicas de la aplicación o el dominio

Agrega contexto general para reglas específicas de la aplicación

Los elementos de contexto general incluyen reglas específicas de la aplicación, declaraciones de lógica empresarial o cualquier terminología específica de la aplicación y del dominio que no esté vinculada a un objeto de esquema específico.

Para agregar contexto general a las reglas específicas de la aplicación y a la terminología específica de la aplicación o el dominio, sigue estos pasos:

Para agregar un elemento de contexto general para la configuración especificada, ejecuta la siguiente consulta:
```
SELECT
  alloydb_ai_nl.g_manage_configuration(
    'add_general_context',
    'my_app_config',
    general_context_in => '{"If the user asks for a good seat, assume that means a window or aisle seat."}'
  );
```
La instrucción anterior ayuda al lenguaje natural de AlloyDB AI a proporcionar respuestas de mayor calidad a las preguntas en lenguaje natural de los usuarios.
Para ver los contextos generales de la configuración especificada, ejecuta la siguiente consulta:
```
SELECT alloydb_ai_nl.list_general_context(nl_config TEXT);
```

Genera y revisa el contexto del esquema

El contexto del esquema describe los objetos del esquema, incluidas las tablas, las vistas, las vistas materializadas y las columnas. Este contexto se almacena como el COMMENT de cada objeto de esquema.

Para generar contextos para objetos de esquema, llama a las siguientes APIs. Para obtener los mejores resultados, asegúrate de que las tablas de la base de datos contengan datos representativos.

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of a provided nl_config.
SELECT
  alloydb_ai_nl.generate_schema_context(
    'my_app_config' -- nl_config
  );

Ejecuta la siguiente consulta para revisar los contextos de esquema generados:
```
SELECT schema_object, object_context
FROM alloydb_ai_nl.generated_schema_context_view;
```
Los contextos de esquema generados se almacenan en la vista anterior.

Opcional: Actualiza los contextos del esquema generados.

SELECT
  alloydb_ai_nl.update_generated_relation_context(
    'my_schema.my_table',
    'This table contains archival records, if you need latest records use records_new table.'
  );

SELECT
  alloydb_ai_nl.update_generated_column_context(
    'my_schema.my_table.column1',
    'The seat_class column takes single letters like "E" for economy, "P" for premium economy, "B" for business and "F" for First.'
  );

Aplica el contexto. Cuando aplicas el contexto, este se aplica de inmediato y se borra de la vista generated_schema_context_view.

-- For all schema objects (tables, views, materialized views and columns)
-- within the scope of nl_config.
SELECT
  alloydb_ai_nl.apply_generated_schema_context(
    'my_app_config' --nl_config
  );

Opcional: Verifica el contexto generado. La siguiente API te permite verificar los contextos del esquema, que se usan cuando generas instrucciones de SQL.

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.get_relation_context(
    'my_schema.my_table'
  );

-- For column.
SELECT
  alloydb_ai_nl.get_column_context(
    'my_schema.my_table.column1'
  );

Aplica el contexto del esquema generado.
```
SELECT alloydb_ai_nl.apply_generated_schema_context(
  'nla_demo_cfg',
  TRUE);
```
Pasar TRUE reemplaza el contexto existente para los objetos registrados en "nla_demo_cfg".

Opcional: Configura manualmente el contexto del esquema.

-- For table, view or materialized view.
SELECT
  alloydb_ai_nl.set_relation_context(
    'my_schema.my_table',
    'One-to-many mapping from product to categories'
  );

-- For column.
SELECT
  alloydb_ai_nl.set_column_context(
    'my_schema.my_table.column1',
    'This column provides additional tagged info for the product in  Json format, e.g., additional color or size information of the product - tags: { "color": "red", "size": "XL"}'
  );

Crea plantillas de consultas

Para mejorar la calidad de las aplicaciones de IA generativa creadas con LLM, puedes agregar plantillas. Una plantilla de consulta es un conjunto seleccionado de preguntas representativas o comunes en lenguaje natural, con las consultas en SQL correspondientes, así como explicaciones para proporcionar un fundamento declarativo para la generación de lenguaje natural a SQL (NL2SQL). La aplicación está diseñada principalmente para especificar las plantillas, pero la extensión alloydb_ai_nl también puede generarlas automáticamente en función de las consultas en SQL que se usan con frecuencia. Cada plantilla debe estar asociada a un nl_config.

La extensión alloydb_ai_nl usa un template_store para incorporar de forma dinámica plantillas de SQL pertinentes en el proceso de generación de una instrucción de SQL para responder la pregunta del usuario final. El comando template_store hace lo siguiente:

Identifica plantillas con intenciones similares a la pregunta en lenguaje natural que hizo el usuario final.
Identifica la instrucción de SQL parametrizada correspondiente.
Sintetiza una instrucción de SQL creando instancias de parámetros con valores de la pregunta en lenguaje natural.

Si no hay una plantilla con la misma intención que la pregunta que hizo el usuario final, alloydb_ai_nl usa todas las plantillas y el contexto pertinentes para redactar una sentencia de SQL.

Agrega una plantilla a la tienda de plantillas

Para agregar plantillas, debes especificar la pregunta con un parámetro llamado intent y la consulta en SQL.

Para agregar una plantilla al almacén de plantillas, ejecuta la siguiente consulta:

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'How many accounts associated with loans are located in the Prague region?',
    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''',
    check_intent => TRUE
  );

Cuando check_intent es TRUE, alloydb_ai_nl realiza una verificación semántica para confirmar que la intención proporcionada coincide con la instrucción de SQL pasada. Si el intent no coincide con la instrucción de SQL, no se agrega la plantilla.

El SQL y el intent se parametrizan con alloydb_ai_nl. La vista alloydb_ai_nl.template_store_view expone las sentencias de SQL parametrizadas y sus intents.

SELECT psql
FROM alloydb_ai_nl.template_store_view
WHERE intent = 'How many accounts associated with loans are located in the Prague region?';

Esta instrucción devuelve lo siguiente:

SELECT COUNT(T1.account_id)
FROM account AS T1 INNER JOIN loan AS T2
  ON T1.account_id = T2.account_id
INNER JOIN district AS T3
  ON T1.district_id = T3.district_id WHERE T3."A3" = $1

Proporciona una parametrización personalizada

Para proporcionar una parametrización personalizada para una instrucción de SQL con la interfaz manual de la función add_template, ejecuta la sentencia en el siguiente ejemplo:

SELECT
  alloydb_ai_nl.add_template(
     nl_config_id => 'my_app_config',
     intent => 'Among the accounts opened, how many customers born before 1950 resided in Slokolov at the time of account opening?',
     sql => $$SELECT COUNT(DISTINCT T2.client_id)
              FROM district AS T1 INNER JOIN client AS T2
                ON T1.district_id = T2.district_id
             INNER JOIN account AS T3 ON T2.client_id IN (
                   SELECT client_id FROM disp WHERE account_id = T3.account_id)
             WHERE to_char(T2.birth_date::timestamp, 'YYYY') < '1950'
               AND T1."A2" = 'Slokolov'$$,
  parameterized_sql => $$SELECT COUNT(DISTINCT T2.client_id)
                         FROM district AS T1 INNER JOIN client AS T2
                           ON T1.district_id = T2.district_id
                   INNER JOIN account AS T3 ON T2.client_id IN (
                         SELECT client_id FROM disp WHERE account_id = T3.account_id)
                   WHERE to_char(T2.birth_date::timestamp, 'YYYY') < $2
                     AND T1."A2" = $1$$,
  parameterized_intent => $$Among the accounts opened, how many customers born before $2 resided in $1 at the time of account opening?$$,
  manifest => $$Among the accounts opened, how many customers born before a given date resided in a given city at the time of account opening?$$,
  check_intent => TRUE);

En la definición anterior, se proporciona la parametrización de la instrucción de SQL. Los parámetros son $1 y $2, respectivamente, para Slokolov y 1950. Se proporciona un manifiesto como una versión generalizada del intent, en el que los valores de los literales se reemplazan por descripciones genéricas de los valores.

En este ejemplo, el valor de 1950 en el intent se reemplaza por a given date, y el valor de Slokolov se reemplaza en el manifiesto por a given city. Cuando se proporciona un valor TRUE para el argumento opcional check_intent, se realiza una verificación de intents basada en LLM durante add_template. Durante esta verificación, cuando la instrucción de SQL proporcionada no captura el propósito y el objetivo de la declaración de intención proporcionada, add_template falla y el motivo se proporciona como resultado.

En el siguiente ejemplo, el propósito de la plantilla, como se indica en la intención, es recuperar el ID de cuenta de las cuentas asociadas con la carga y que se encuentran en una región. La instrucción de SQL proporcionada devuelve la cantidad de cuentas, en lugar de la lista de IDs de cuenta, como se muestra en el siguiente ejemplo.

SELECT
  alloydb_ai_nl.add_template(
    nl_config_id => 'my_app_config',
    intent => 'List the account id for all accounts that associated with loans and are located in the Prague region.',
    sql => 'SELECT COUNT(T1.account_id)
            FROM account AS T1 INNER JOIN loan AS T2
              ON T1.account_id = T2.account_id
            INNER JOIN district AS T3
              ON T1.district_id = T3.district_id
            WHERE T3."A3" = ''Prague''',
    check_intent => TRUE
  );

Cuando check_intent se establece en TRUE, no puedes agregar la plantilla anterior al almacén de plantillas. Si ejecutas la declaración anterior, se muestra un error similar al siguiente:

ERROR:  Checking intent failed, for nl_question:List the account id for all accounts that associated with loans and are located in the Prague region...reason:The SQL query only counts the number of account IDs, but the question asks for a list of the account IDs.

Administrar plantillas

Puedes administrar las plantillas en el almacén de plantillas con las siguientes APIs:

-- To disable a template:
SELECT alloydb_ai_nl.disable_template(INPUT template_id);

-- To enable a template which has been disabled:
SELECT alloydb_ai_nl.enable_template(INPUT template_id);

-- To permanently remove a template:
SELECT alloydb_ai_nl.drop_template(INPUT template_id);

Cuando creas una plantilla, se habilita de forma predeterminada. Una plantilla inhabilitada permanece en la tienda de plantillas, pero alloydb_ai_nl no la usa para sintetizar consultas. Puedes habilitar una plantilla inhabilitada con alloydb_ai_nl.enable_template. Si ejecutas alloydb_ai_nl.drop_template, se quitará la plantilla de forma permanente de la tienda de plantillas.

Puedes usar alloydb_ai_nl.template_store_view para extraer el template_id de una plantilla, según su contenido. Por ejemplo, para encontrar el identificador de las plantillas que tienen el intent accounts that associated with loans, ejecuta la siguiente consulta, que devuelve un identificador de plantilla y determina si la plantilla está habilitada desde alloydb_ai_nl.template_store_view:

SELECT id, enabled
FROM alloydb_ai_nl.template_store_view
WHERE intent ILIKE '%accounts that associated with loans%';

Actualiza una plantilla

Cuando uses las plantillas en alloydb_ai_nl.template_store_view, asegúrate de que la intención de cada plantilla sea coherente con lo siguiente:

La instrucción de SQL
La instrucción de SQL parametrizada
El intent parametrizado
El manifiesto de la plantilla

alloydb_ai_nl puede recuperar plantillas pertinentes si la incorporación que se mantiene para las plantillas corresponde al contenido de la plantilla.

Para actualizar una plantilla, sigue estos pasos:

Identifica el template_id con alloydb_ai_nl.template_store_view.
Quita la plantilla.
Vuelve a definir la nueva plantilla con la modificación requerida usando la función alloydb_ai_nl.add_template.

Crea fragmentos de consulta

Puedes especializar las plantillas en el momento de la consulta con fragmentos, que ayudan a las plantillas de consulta a realizar búsquedas por facetas, como preguntas en lenguaje natural. Un fragmento es un conjunto seleccionado de condiciones de lenguaje natural representativas o comunes con predicados de SQL correspondientes. La aplicación debe especificar los fragmentos.

Cada fragmento debe estar asociado con un nl_config_id y con un array de tablas y vistas con alias a los que se aplica el predicado del fragmento. Puedes verificar el propósito de un fragmento cuando el argumento check_intent se establece en TRUE. La extensión alloydb_ai_nl puede usar una plantilla con una combinación de fragmentos para sintetizar la respuesta a una consulta en lenguaje natural.

La extensión alloydb_ai_nl usa fragment_store para incorporar de forma dinámica las condiciones en fragmentos relevantes en el proceso de generación de una instrucción de SQL para responder la pregunta del usuario final. Primero, template_store identifica plantillas con intenciones similares a la pregunta en lenguaje natural que hizo el usuario final. A continuación, se recuperan los fragmentos que pueden proporcionar especialización a las plantillas identificadas. El reemplazo de parámetros se aplica tanto a las plantillas como a los fragmentos para sintetizar una instrucción de SQL.

Los valores de los parámetros se extraen de la pregunta en lenguaje natural y el LLM los reemplaza con los patrones implícitos de las plantillas y los fragmentos pertinentes. Sin embargo, si la combinación de plantillas y fragmentos no tiene el mismo propósito para la pregunta que hizo el usuario final, alloydb_ai_nl usa todas las plantillas y el contexto pertinentes para componer una instrucción SQL.

Cómo agregar un fragmento

Para agregar un fragmento, ejecuta las siguientes consultas de ejemplo con la función alloydb_ai_nl.add_fragment. Cada fragmento debe estar asociado con un identificador nl_config_id de la aplicación.

-- A fragment that cannot be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['account AS T'],
  intent => 'Accounts with issuance after transaction',
  fragment => 'T.frequency = ''POPLATEK PO OBRATU''',
  check_intent => True);

-- A fragment that can be parameterized.
SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['district AS T'],
  intent => 'Average salary between 6000 and 10000',
  fragment => 'T."A11" BETWEEN 6000 AND 10000',
  check_intent => True);

Cuando se ejecuta alloydb_ai_nl.add_fragment, la extensión alloydb_ai_nl extrae un manifiesto del intent proporcionado, y la extensión parametriza el intent y la condición para el fragmento, si es posible. Las vistas, como alloydb_ai_nl.fragment_store_view, exponen los fragmentos disponibles, como se muestra en el siguiente ejemplo:

SELECT manifest, scope, fragment, intent, pfragment, pintent
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = 'Average salary between 6000 and 10000';

La consulta devuelve un conjunto de resultados similar al siguiente:

manifest  | Average salary between a given number and a given number
scope     | district AS T
fragment  | T."A11" BETWEEN 6000 AND 10000
intent    | Average salary between 6000 and 10000
pfragment | T."A11" BETWEEN $2 AND $1
pintent   | Average salary between $2 and $1

Un manifiesto en un fragmento se genera automáticamente a partir del intent y representa una versión generalizada del intent. Por ejemplo, los números 6000 y 10000 del intent se reemplazan por a given number en el manifiesto. Los números se reemplazan, respectivamente, por $2 y $1 en las columnas pfragment y pintent. Las columnas pfragment y pintent en alloydb_ai_nl.fragment_store_view son, respectivamente, la representación parametrizada de fragment y intent.

Para proporcionar una parametrización personalizada de un fragmento, usa la versión manual de alloydb_ai_nl.add_fragment, como se muestra en el siguiente ejemplo:

SELECT alloydb_ai_nl.add_fragment(
  nl_config_id => 'my_app_config',
  table_aliases => ARRAY['bird_dev_financial.district AS T'],
  intent => $$districts in 'Prague'$$,
  parameterized_intent => $$districts in $1$$,
  fragment => $$T."A3" = 'Prague'$$,
  parameterized_fragment => $$T."A3" = $1$$,
  manifest => $$districts in a given city$$,
  check_intent => TRUE);

Administra fragmentos

Para administrar fragmentos, usa las siguientes APIs:

-- To disable a fragment:
SELECT alloydb_ai_nl.disable_fragment(INPUT fragment_id);

-- To enable a fragment which has been disabled:
SELECT alloydb_ai_nl.enable_fragment(INPUT fragment_id);

-- To permanently remove a fragment:
SELECT alloydb_ai_nl.drop_fragment(INPUT fragment_id);

Puedes usar la vista alloydb_ai_nl.fragment_store_view para extraer el fragment_id de un fragmento, según su contenido. Por ejemplo, para encontrar el identificador de un fragmento que tiene el intent Average salary between 6000 and 10000, ejecuta la siguiente consulta de ejemplo:

SELECT id
FROM alloydb_ai_nl.fragment_store_view
WHERE intent = "Average salary between 6000 and 10000";

Actualiza un fragmento

Cuando actualices un fragmento, asegúrate de que su intent sea coherente con lo siguiente:

El manifiesto y la instrucción de SQL del fragmento
La instrucción de SQL parametrizada
El intent parametrizado

Para establecer la coherencia cuando actualizas un fragmento, sigue estos pasos:

Quita el fragmento que deseas modificar con la función alloydb_ai_nl.drop_fragment.
Inserta el fragmento actualizado con la función alloydb_ai_nl.add_fragment.

Genera plantillas automáticamente

Después de tener un conjunto de datos representativo en tus tablas, te recomendamos que ejecutes consultas en SQL que correspondan a las preguntas comunes que es probable que hagan tus usuarios finales. Asegúrate de que las consultas tengan planes de consulta completos y que funcionen bien.

Después de ejecutar las consultas, el lenguaje natural de AlloyDB AI puede generar plantillas automáticamente según el historial de consultas. Puedes llamar a las siguientes APIs para generar plantillas. Debes revisar y aplicar las plantillas generadas antes de que entren en vigencia.

La generación automática de plantillas se basa en las consultas más utilizadas en el registro de consultas, google_db_advisor_workload_statements. Las consultas se filtran según los siguientes criterios:

Declaraciones SELECT
Ejecutables: La consulta se puede procesar correctamente con el comando EXPLAIN.
Sin duplicación: la consulta no se usó antes para generar plantillas.
Todas las tablas y vistas a las que se hace referencia están dentro del alcance de nl_config.

Para generar automáticamente, revisar y aplicar plantillas, sigue estos pasos:

Solicita a AlloyDB que genere plantillas basadas en tu historial de consultas:
```
SELECT
  alloydb_ai_nl.generate_templates(
    'my_app_config',
);
```
Usa la vista proporcionada, alloydb_ai_nl.generated_templates_view, para revisar el generated_templates.

En el siguiente resultado, se muestra la cantidad de plantillas generadas:
```
-[ RECORD 1 ]------+--
generate_templates | 1
```

Revisa las plantillas generadas con la vista generated_templates_view.

SELECT *
FROM alloydb_ai_nl.generated_templates_view;

A continuación, se muestra un ejemplo del resultado que se devuelve:

-[ RECORD 1 ]----------------------------------------------------------------
id          | 1
config      | my_app_config
type        | Template
manifest    | How many clients have a birth year of a given number?
nl          | How many clients have a birth year of 1997?
sql         | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = '1997';
intent      | How many clients have a birth year of 1997?
psql        | select count(*) from public.client as T where
             to_char(T.birth_date::timestamp, 'YYYY') = $1;
pintent     | How many clients have a birth year of $1?
comment     |
explanation |
weight      | 1

El manifest en el resultado que se muestra es una plantilla general o una descripción amplia del tipo de pregunta o de la operación que se puede realizar. pintent es una versión parametrizada de intent y generaliza intent reemplazando el valor específico (1997) por un marcador de posición ($1).

Para actualizar una plantilla generada, ejecuta la siguiente sentencia de ejemplo:

SELECT alloydb_ai_nl.update_generated_template(
  id => 1,
  manifest => 'How many clients are born in a given year?',
  nl => 'How many clients are born in 1997?',
  intent => 'How many clients are born in 1997?',
  pintent => 'How many clients are born in $1?'

);

Aplica las plantillas. Las plantillas que aplicas se agregan de inmediato a la tienda de plantillas y se borran de la vista de revisión.
```
-- For all templates generated under the nl config.
SELECT
  alloydb_ai_nl.apply_generated_templates('my_app_config');
```

Configura la seguridad para el lenguaje natural

Para configurar la seguridad del lenguaje natural de AlloyDB AI, consulta Administra la seguridad para aplicaciones de datos con vistas seguras parametrizadas.

Cómo definir tipos de conceptos y valores de índice

Define tipos de conceptos y de índices de valores para proporcionar una comprensión más profunda de las preguntas que se realizan. Un tipo de concepto es una categoría o clase de entidades que identifica el significado semántico de las palabras y las frases, en lugar de solo su forma literal.

Por ejemplo, dos nombres de países pueden ser iguales, incluso si uno está en mayúsculas, por ejemplo, USA, y el otro está en minúsculas, por ejemplo, usa. En este caso, el nombre del país es el tipo de concepto. Otros ejemplos de tipos de conceptos incluyen el nombre de una persona, el nombre de una ciudad y una fecha.

Un índice de valores es un índice sobre los valores de las columnas que forman parte de la configuración en lenguaje natural nl_config, basado en los tipos de conceptos asociados con cada columna. Un índice de valores permite la coincidencia eficiente de frases de valor para la pregunta que se hace y los valores de la base de datos.

Para definir los tipos de conceptos y un índice de valores, sigue estos pasos con los ejemplos proporcionados. En los ejemplos, se asocia una columna a un tipo de concepto, se crea y actualiza un índice de valores, y se usa un conjunto de sinónimos para realizar una búsqueda de valores.

Para asociar una columna con un tipo de concepto, ejecuta la siguiente consulta:

SELECT
  alloydb_ai_nl.associate_concept_type(
    column_names_in => 'my_schema.country.country_name',
    concept_type_in => 'country_name',
    nl_config_id_in => 'my_app_config'
  );

Para crear un índice de valores basado en todas las columnas que forman parte de una configuración de lenguaje natural y están asociadas con un tipo de concepto, ejecuta la siguiente sentencia:
```
SELECT
  alloydb_ai_nl.create_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
Cuando asocies tipos de conceptos a columnas nuevas, actualiza el índice de valores para reflejar los cambios.
```
SELECT
  alloydb_ai_nl.refresh_value_index(
    nl_config_id_in => 'my_app_config'
  );
```
Para habilitar el lenguaje natural de AlloyDB AI para que coincida con los sinónimos de un valor, ejecuta la siguiente instrucción de ejemplo:
```
SELECT
  alloydb_ai_nl.insert_synonym_set(
    ARRAY [
      'USA',
      'US',
      'United States',
      'United States of America'
    ]
  );
```
Aunque los datos de tus tablas pueden usar un valor específico, por ejemplo, si se usa United States para identificar un país, puedes definir un conjunto de sinónimos que contenga todos los sinónimos de United States. Si alguno de los sinónimos aparece en la pregunta en lenguaje natural, el lenguaje natural de AlloyDB AI hace coincidir los sinónimos con los valores de tus tablas.

Realiza una búsqueda de valores para encontrar los valores correctos de la base de datos, dado un array de frases de valor.

SELECT
  alloydb_ai_nl.get_concept_and_value(
    value_phrases_in => ARRAY['United States'],
    nl_config_id_in  => 'my_app_config'
  );

Por ejemplo, si un usuario hace una pregunta como "¿Cuál es la población de Estados Unidos?" que usa la siguiente consulta get_sql, el lenguaje natural de AlloyDB AI usa la función get_concept_and_value con la frase de valor United States para realizar una búsqueda aproximada en los índices de valor. Una búsqueda parcial es una técnica de búsqueda que encuentra coincidencias incluso cuando la búsqueda no coincide exactamente con los datos correspondientes.

El lenguaje natural encuentra un resultado, el valor USA, que se acerca a la consulta de búsqueda y usa ese resultado para generar la consulta en SQL.

SELECT
  alloydb_ai_nl.get_sql(
    nl_config_id    => 'my_app_config',
    nl_question     => 'What is the population of the United States?',
    additional_info => json_build_object('enrich_nl_question', TRUE)
  ) ->> 'sql';

Los tipos de conceptos integrados definidos por el lenguaje natural de AlloyDB AI se enumeran en la siguiente tabla.

Nombre del concepto	Descripción
`generic_entity_name`	Se puede usar una sola columna con tipo especificado de cadena para un nombre de entidad genérico. Por ejemplo: SELECT alloydb_ai_nl.associate_concept_type('public.item.item_name', 'generic_entity_name')
`country_name`, `city_name`, `region_name`	Nombres de países, ciudades y regiones. El uso es exactamente el mismo que el del tipo de concepto `generic_entity_name`.
`full_person_name`	Es el nombre de la persona, que consta de nombre, apellido y segundo nombre. Se pueden usar hasta tres columnas con tipo especificado de tipo de cadena para el nombre completo de una persona. Se puede omitir cualquiera de las columnas cuando se asocian columnas de nombres al `full_person_name`. Un ejemplo es . SELECT alloydb_ai_nl.associate_concept_type('public.person.last_name,public.person.first_name,public.person.middle_name','full_person_name')
`ssn`	Es una sola columna de cadena que contiene un número de seguridad social. Por ejemplo: SELECT alloydb_ai_nl.associate_concept_type('public.person.ssn','ssn')
`date`	Es una fecha o una marca de tiempo. Por ejemplo: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Generar automáticamente asociaciones de tipos de conceptos

Para asociar automáticamente columnas con tipos de conceptos, usa la función de asociación de tipos de conceptos automatizada de la API de lenguaje natural de AlloyDB AI. Una asociación de tipo de concepto define la relación entre un tipo de concepto y una o más columnas de la base de datos, lo que es un requisito previo para crear índices de valores.

Para generar automáticamente asociaciones de tipos de conceptos, sigue estos pasos:

Para generar asociaciones, llama a las siguientes APIs.

-- To cover all relations within the scope of a provided nl_config.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To cover a specific relation.
SELECT alloydb_ai_nl.generate_concept_type_associations(
  nl_config => 'my_app_config',
  relation_name => 'my_app_table'
);

Ejecuta la siguiente consulta para revisar las asociaciones generadas.
```
SELECT * FROM alloydb_ai_nl.generated_value_index_columns_view;
```

Opcional: Actualiza las asociaciones generadas.

-- NULL means keeping the original value.
SELECT alloydb_ai_nl.update_generated_concept_type_associations(
  id => 1,
  column_names => NULL,
  concept_type => 'generic_entity_name',
  additional_info => NULL
);

Opcional: Quita una asociación generada.

SELECT alloydb_ai_nl.drop_generated_concept_type_association(id => 1);

Aplica las asociaciones generadas.

-- To apply all associations under a nl config.
SELECT alloydb_ai_nl.apply_generated_concept_type_associations(
  nl_config => 'my_app_config'
);

-- To apply a specific association by id.
SELECT alloydb_ai_nl.apply_generated_concept_type_association(
  id => 1
);

Actualiza el índice de valores para reflejar los cambios.

SELECT alloydb_ai_nl.refresh_value_index(
  nl_config_id_in => 'my_app_config'
);

Genera sentencias de SQL a partir de entradas de lenguaje natural

Puedes usar el lenguaje natural de AlloyDB AI para generar sentencias de SQL a partir de entradas de lenguaje natural. Cuando ejecutas la instrucción de SQL generada, proporciona los datos de la base de datos que necesitas para responder la pregunta en lenguaje natural.

Para usar el lenguaje natural y obtener resultados de tu base de datos con la función alloydb_ai_nl.get_sql, usa el siguiente ejemplo:

SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  );

Se muestra el siguiente resultado en formato JSON:

{
  "sql": "SELECT T3.balance FROM public.client AS T1 INNER JOIN public.account AS T2 ON T1.district_id = T2.district_id INNER JOIN public.trans AS T3 ON T2.account_id = T3.account_id WHERE T1.client_id = 4 AND T3.trans_id = 851",
  "prompt": "",
  "retries": 0,
  "error_msg": "",
  "nl_question": "What is the sum that client number 4's account has following transaction 851?"
}

Opcional: Para extraer la consulta en SQL generada como una cadena de texto, agrega ->>'sql':
```
SELECT
  alloydb_ai_nl.get_sql(
    'my_app_config', -- nl_config
    'What is the sum that client number 4''s account has following transaction 851?' -- nl question
  ) ->> 'sql';
```
El operador ->> se usa para extraer un valor JSON como texto. La función alloydb_ai_nl.get_sql devuelve un objeto JSON, que es la parte de la instrucción que recupera el valor asociado con la clave sql. Este valor es la consulta en SQL generada.

Genera resúmenes de resultados a partir de entradas de lenguaje natural

Puedes usar el lenguaje natural de AlloyDB AI para generar resúmenes de resultados a partir de entradas de lenguaje natural. La función alloydb_ai_nl.get_sql_summary ejecuta de forma segura la pregunta en lenguaje natural en la tabla subyacente, resume una muestra del conjunto de resultados y devuelve el resumen en lenguaje natural.

Para producir un resumen de los resultados de una pregunta en lenguaje natural en tu base de datos, usa la función alloydb_ai_nl.get_sql_summary como se muestra en el siguiente ejemplo:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?');

Cuando se llama a la sentencia anterior, se produce el siguiente objeto JSON de ejemplo:

{
  "answer": "The result set indicates that there are 13 accounts that chose issuance after a transaction and are located in the East Bohemia region. The earliest opening date among these accounts is August 21, 1993. Other information about these accounts is not provided in the result set."
}

Puedes proteger las tablas y vistas a las que accede una consulta en alloydb_ai_nl.get_sql_summary con una o más vistas seguras parametrizadas. Los nombres de los parámetros y sus valores están disponibles para una aplicación y son obligatorios para alloydb_ai_nl.get_sql_summary.

Por ejemplo, la aplicación podría querer proporcionar el parámetro user_id para un usuario autenticado con un ID de usuario de 123. Para lograrlo, proporciona entradas param_names y param_values, como se muestra en el siguiente ejemplo:

SELECT
  alloydb_ai_nl.get_sql_summary(
    nl_config_id => 'my_app_config',
    nl_question => 'Give me the total number of accounts and the earliest opening date and other information for accounts who choose issuance after transaction are staying in east Bohemia region?',
    param_names => ARRAY ['user_id'],
    param_values => ARRAY ['123']
);

Proporcionar los argumentos param_names y param_values garantiza que, cuando la nl_question se pueda responder con una instrucción de SQL que se aplique a través de vistas seguras parametrizadas, se apliquen los filtros de seguridad designados cuando se produzca el conjunto de resultados y se genere el resumen.

Prueba y define mejor tu estrategia

Para obtener consultas mejoradas generadas automáticamente, modifica o agrega un mejor contexto, plantillas de consultas y índices de valores, luego itera hasta que obtengas los resultados que deseas.