Se usó la API de Cloud Translation para traducir esta página.

Genera consultas en SQL con preguntas en lenguaje natural

En esta página, se describe cómo configurar y generar instrucciones SQL con el lenguaje natural de AlloyDB AI. El lenguaje natural te permite crear aplicaciones de IA generativa orientadas al usuario con lenguaje natural para consultar bases de datos.

Para habilitar la extensión alloydb_ai_nl, que es la API de compatibilidad con lenguaje natural de AlloyDB para PostgreSQL, sigue estos pasos generales:

Instala la extensión de alloydb_ai_nl.
Define una configuración de lenguaje natural para tu aplicación.
Registra un esquema.
Agrega contexto.
Se agregaron plantillas de búsqueda.
Define los tipos de conceptos y crea un índice de valores.
Generar instrucciones en SQL con una interfaz de lenguaje natural

Antes de comenzar

Comprende cómo conectarte a la base de datos de AlloyDB y ejecutar comandos de PostgreSQL. Para obtener más información, consulta la Descripción general de la conexión.
Propaga 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. 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 en Vertex AI

Crea un clúster y una instancia de AlloyDB. Usarás la instancia de AlloyDB para crear la base de datos y el esquema de la aplicación.
Habilita la integración en Vertex AI. Para obtener más información, consulta Integración con Vertex AI.

Roles requeridos

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 en lenguaje natural, debes instalar la extensión requerida, crear una configuración y registrar un esquema.

Instala la extensión alloydb_nl_ai

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

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 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 default_version es posterior a 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 configuraciones para diferentes partes de la aplicación, siempre y cuando 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}'
  );

Agregar contexto

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

Estructura y relaciones del esquema
Resúmenes y descripciones de las 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 las 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 el 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 a que el lenguaje natural de AlloyDB AI proporcione 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 del 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 generado.

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 entra en vigencia 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'
  );

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 una justificación declarativa para la generación de lenguaje natural a SQL (NL2SQL). Las plantillas están diseñadas principalmente para que las especifique la aplicación, pero la extensión alloydb_ai_nl también puede generarlas automáticamente en función de las consultas de 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 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 componer una instrucción 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 a la tienda 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 que se pasó. Si la intención no coincide con la instrucción de SQL, no se agrega la plantilla.

El SQL y la intención se parametrizan con alloydb_ai_nl. La vista alloydb_ai_nl.template_store_view expone las instrucciones 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 de la intención, en la que los valores de los literales se reemplazan por descripciones genéricas de los valores.

En este ejemplo, el valor de 1950 en la intención 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 de TRUE para el argumento opcional check_intent, se realiza una verificación de intención basada en LLM durante add_template. Durante esta verificación, cuando la instrucción de SQL proporcionada no capta el propósito y el objetivo de la instrucció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 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 a la tienda de plantillas. Si ejecutas la instrucción anterior, se mostrará 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 la tienda 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, esta se habilita de forma predeterminada. Las plantillas inhabilitadas permanecen en la tienda de plantillas, pero alloydb_ai_nl no las 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 la tienda de plantillas de forma permanente.

Puedes usar alloydb_ai_nl.template_store_view para extraer el template_id de una plantilla, dado su contenido. Por ejemplo, para encontrar el identificador de las plantillas que tienen la intención 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
Es la instrucción de SQL parametrizada.
El intent parametrizado
Manifiesto de la plantilla

alloydb_ai_nl puede recuperar plantillas relevantes 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.
Redefine la plantilla nueva con la modificación requerida usando la función alloydb_ai_nl.add_template.

Crea fragmentos de consultas

Puedes especializar 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 representativas o comunes en lenguaje natural con predicados SQL correspondientes. La aplicación debe especificar los fragmentos.

Cada fragmento debe estar asociado a un nl_config_id y a 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 búsqueda en lenguaje natural.

La extensión alloydb_ai_nl usa fragment_store para incorporar de forma dinámica las condiciones en fragmentos relevantes durante 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 que se infieren 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 cada plantilla y contexto relevantes 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 de la intención proporcionada, y la extensión parametriza la intención y la condición del fragmento, si es posible. Los fragmentos disponibles se exponen a través de vistas como alloydb_ai_nl.fragment_store_view, 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 de la intención y representa una versión generalizada de la intención. Por ejemplo, los números 6000 y 10000 en la intención 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, dado su contenido. Por ejemplo, para encontrar el identificador de un fragmento que tiene la intención 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 la intención del fragmento sea coherente con lo siguiente:

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

Para garantizar la coherencia cuando actualices 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 de SQL que correspondan a las preguntas comunes que es probable que hagan tus usuarios finales. Asegúrate de que las consultas tengan planes de consultas completos y que tengan un buen rendimiento.

Después de ejecutar las consultas, el lenguaje natural de AlloyDB AI puede generar automáticamente plantillas basadas en 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 búsquedas que se usan con mayor frecuencia en el registro de búsquedas, google_db_advisor_workload_statements. Las búsquedas se filtran según los siguientes criterios:

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

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

Solicita a AlloyDB que genere plantillas basadas en tu historial de búsquedas:
```
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 devuelto:

-[ 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 devuelto es una plantilla general o una descripción amplia del tipo de pregunta o 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 de las aplicaciones de datos con vistas seguras parametrizadas.

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

Defines tipos de conceptos y valores de índice para comprender mejor 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 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, como USA, y el otro está en minúsculas, como 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 a cada columna. Un índice de valores permite la coincidencia eficiente de frases de valores para la pregunta que se hace y los valores de la base de datos.

Para definir 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 en lenguaje natural y que están asociadas a un tipo de concepto, ejecuta la siguiente instrucción:
```
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 United States se usa 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, AlloyDB AI los correlaciona 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 valores.

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 valores. La 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 es similar a la búsqueda y lo usa 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';

En la siguiente tabla, se enumeran los tipos de conceptos integrados definidos por el lenguaje natural de AlloyDB AI.

Nombre del concepto	Descripción
`generic_entity_name`	Se puede usar una sola columna de tipo 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`	Nombre de la persona, que incluye el nombre de pila, el segundo nombre y el apellido. Se pueden usar hasta tres columnas de tipo 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`. Por ejemplo: 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`	Una fecha o una marca de tiempo Por ejemplo: SELECT alloydb_ai_nl.associate_concept_type('public.person.date_col','date')

Genera automáticamente asociaciones de tipos de conceptos

Para asociar automáticamente columnas con tipos de conceptos, usa la función de asociación automática de tipos de conceptos 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 instrucciones en SQL a partir de entradas en lenguaje natural

Puedes usar el lenguaje natural de AlloyDB AI para generar sentencias en SQL a partir de entradas en lenguaje natural. Cuando ejecutas la instrucción de SQL generada, se proporcionan los datos de la base de datos que necesitas para responder la pregunta de 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 de 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.

Generar resúmenes de resultados a partir de entradas en lenguaje natural

Puedes usar el lenguaje natural de AlloyDB AI para generar resúmenes de resultados a partir de entradas en 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 generar 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?');

Si llamas a la instrucción anterior, se producirá 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 las 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 ello, 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 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 perfecciona

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