Realiza consultas SQL inteligentes con funciones basadas en IA

Las funciones de IA de AlloyDB AI integran modelos de lenguaje grandes (LLM) como Gemini directamente con tus datos de AlloyDB para PostgreSQL para realizar operaciones de datos inteligentes. Esta función incluye funciones integradas para lo siguiente:

Filtros (ai.if)
Clasificación semántica (ai.rank)
Generación de texto (ai.generate)

Estas funciones de IA usan el motor de consultas de AlloyDB AI para ayudar a tu aplicación a procesar datos con modelos de inteligencia artificial en varias escalas, desde respuestas de una sola fila hasta operaciones de bases de datos a gran escala. Puedes usar los operadores ai.if, ai.rank y ai.generate para combinar lenguaje natural con consultas en SQL. AlloyDB AI reserva y crea el esquema ai.

Existen tres categorías de funciones basadas en IA que se diferencian según la forma en que manejan los datos de entrada y la asignación de memoria: funciones escalares, basadas en arrays y de cursor. Elegir la función de IA adecuada depende de la escala de tus datos y de tus requisitos de rendimiento. Usa la siguiente tabla para obtener información sobre estas funciones y sus casos de uso:

Categoría	Descripción	Caso práctico recomendado
Escalar	Diseñado para el procesamiento básico de uno a uno. Toma una sola entrada y devuelve una sola salida.	Úsala cuando quieras una función básica que proporcione un rendimiento aceptable para las consultas que realizan una pequeña cantidad (menos de 50) de llamadas a funciones escalares.
Basado en arrays	Procesa los datos como un array de filas en una sola llamada a la función. Toma un array como entrada y lo devuelve como salida.	Se usa para conjuntos de datos pequeños o medianos en los que todo el array de filas aptas puede ajustarse dentro de los límites de memoria. Esto proporciona un alto rendimiento para las operaciones basadas en conjuntos.
Cursor	Toma un cursor como entrada y devuelve un cursor como salida.	Se usa para procesar una gran cantidad de filas, por ejemplo, 10,000.

Antes de comenzar

Verifica que la extensión google_ml_integration esté instalada y que estés usando la versión 1.5.2 o una posterior. Para obtener más beneficios de rendimiento con las funciones basadas en arrays, usa la versión 1.5.4 o posterior.
Verifica que la marca google_ml_integration.enable_ai_query_engine esté establecida en on.
Integración en Vertex AI
Usa un modelo de Gemini compatible con tu región. Gemini 2.0 Flash es el modelo predeterminado del motor de búsqueda de IA. Si no especificas un modelo de Gemini en la búsqueda, se elegirá el modelo predeterminado del motor de búsqueda de IA para las búsquedas.

Integra la extensión en Vertex AI y, luego, instálala

Configura el acceso de los usuarios a los modelos de Vertex AI.
Verifica que esté instalada la versión más reciente de google_ml_integration.
1. Para verificar la versión instalada, ejecuta el siguiente comando:
```
        SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
        extversion 
        ------------
        1.5.2
        (1 row)
      
```
2. Si la extensión no está instalada o si la versión instalada es anterior a la 1.5.2, actualízala.
```
        CREATE EXTENSION IF NOT EXISTS google_ml_integration;
        ALTER EXTENSION google_ml_integration UPDATE;
      
```
  Si tienes problemas cuando ejecutas los comandos anteriores o si la extensión no se actualiza a la versión 1.5.2 después de ejecutar los comandos anteriores, comunícate con el Google Cloud equipo de asistencia.
Para usar la funcionalidad del motor de consultas de AlloyDB AI, establece la marca google_ml_integration.enable_ai_query_engine en on.
SQL
1. Habilita el motor de consultas de IA para la sesión actual.
  SET google_ml_integration.enable_ai_query_engine = on;
2. Habilita funciones para una base de datos específica en todas las sesiones.
  ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
3. Habilita el motor de consultas de IA para un usuario específico en todas las sesiones y bases de datos.
  ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';
Console

Para modificar el valor de la marca google_ml_integration.enable_ai_query_engine, sigue los pasos que se indican en Configura las marcas de base de datos de una instancia.
gcloud

Para usar gcloud CLI, puedes instalar y, luego, inicializar Google Cloud CLI, o bien usar Cloud Shell.

Puedes modificar el valor de la marca google_ml_integration.enable_ai_query_engine. Para obtener más información, consulta Configura las marcas de base de datos de una instancia.
```
             gcloud alloydb instances update INSTANCE_ID \
               --database-flags google_ml_integration.enable_ai_query_engine=on \
               --region=REGION_ID \
               --cluster=CLUSTER_ID \
               --project=PROJECT_ID
            
```

Usa un modelo de Gemini compatible con tu región

Si tu clúster de AlloyDB para PostgreSQL se encuentra en una región en la que no se admite gemini-2.0-flash, puedes usar uno de los otros modelos de Gemini disponibles en tu región con model_id parameter.

También puedes registrar un extremo del modelo de Gemini y proporcionar ese ID del modelo a los operadores de IA. Para obtener más información, consulta Cómo registrar y llamar a modelos de IA remotos con la administración de extremos de modelos.

En el siguiente ejemplo, se muestra cómo registrar otro extremo de Gemini. En este ejemplo, el segundo extremo de Gemini es el extremo global para gemini-2.0-flash. Puedes usar este modelo registrado con operadores de IA pasando model_id =>gemini-2.5-flash-global` como argumento adicional.

CALL
  google_ml.create_model(
    model_id => 'gemini-2.5-flash-global',
    model_type => 'llm',
    model_provider => 'google',
    model_qualified_name => 'gemini-2.5-flash',
    model_request_url =>  'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent',
    model_auth_type => 'alloydb_service_agent_iam'
);

Usa los modelos de Gemini 3.0

Algunos modelos de Gemini, como gemini-3.0-pro-preview, solo están disponibles a través del extremo global. Debes registrar estos modelos de la siguiente manera:

CALL
  google_ml.create_model(
    model_id => 'gemini-3-preview-model',
    model_request_url => 'https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-3-pro-preview:generateContent',
    model_qualified_name => 'gemini-3-pro-preview',
    model_provider => 'google',
    model_type => 'llm',
    model_auth_type => 'alloydb_service_agent_iam'
);

Reemplaza PROJECT_ID por el ID del proyecto en el que está disponible el modelo de Vertex AI. Ten en cuenta que la cuenta de servicio de AlloyDB debe tener el rol de usuario de Vertex AI en ese proyecto.

Después de registrar el modelo, puedes usarlo en las funciones de IA de la siguiente manera:

SELECT ai.generate(prompt => 'What is AlloyDB?', model_id => 'gemini-3-preview-model');

Usa filtros en tus consultas

AlloyDB AI ofrece funciones de SQL potenciadas por IA que te permiten usar el procesamiento de lenguaje natural y los LLM directamente en tus consultas de bases de datos, incluidos los operadores ai.if y ai.rank.

Realiza filtrados con funciones escalares

Para evaluar si se cumple una condición establecida en lenguaje natural, usa el operador ai.if/google_ml.if. La función devuelve un valor booleano verdadero o falso, y devuelve false si no se detecta claramente la salida.

- Function signature
FUNCTION ai.if(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS bool

En el siguiente ejemplo, se muestra el uso del operador ai.if como filtro para encontrar restaurantes con más de 500 opiniones positivas ubicados en ciudades con una población superior a 100,000 habitantes. En el ejemplo, se usa restaurant_reviews y se incluyen datos como opiniones y la ubicación de la ciudad. El operador ai.if te ayuda a comprender el sentimiento de la opinión y a combinar las ubicaciones de la base de datos con el conocimiento general de Gemini sobre la población en esas ubicaciones.

SELECT r.name, r.location_city
FROM restaurant_reviews r
WHERE
  AI.IF(r.location_city || ' has a population OF more than 100,000 AND the following is a positive review; Review: ' || r.review)
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

A continuación, se muestra el mismo ejemplo con el modelo que registraste en Usa un modelo de Gemini compatible con tu región.

SELECT r.name, r.location_city
FROM restaurant_reviews r
WHERE
  AI.IF(r.location_city || ' has a population of more than 100,000 AND the following is a positive review; Review: ' || r.review, model_id => 'gemini-2.5-flash')
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Realiza una unión en una consulta que usa el operador if

Para realizar una operación de unión, usa el operador ai.if/google_ml.if con la unión. La siguiente consulta de ejemplo busca la cantidad de opiniones que mencionan cada elemento del menú del restaurante.

    SELECT item_name, COUNT(*)
    FROM menu_items JOIN user_reviews
      ON ai.if(
        prompt => 'Does the following user review talk about the menu item mentioned ? review: ' || user_reviews.review_text || ' menu item: ' || item_name)
    GROUP BY item_name;

Realiza el filtrado con funciones basadas en arrays

En el siguiente ejemplo, se identifican los restaurantes con más de 10 opiniones positivas a través de un modelo de IA (gemini-2.0-flash) para analizar el sentimiento de las opiniones y filtrar los resultados. ARRAY_AGG se usa para transformar filas individuales de datos en arrays estructurados, de modo que el modelo de IA pueda procesarlos de forma masiva en lugar de fila por fila.

WITH initial_arrays AS (WITH initial_arrays AS (
  SELECT
    ARRAY_AGG(r.id ORDER BY r.id) AS review_ids,
    -- Assuming ai.if takes an array of prompts and returns a boolean array
    ai.if(
      prompts => ARRAY_AGG('Is the review positive: ' || r.review ORDER BY r.id)
      model_id => 'gemini-2.5-flash',
      batch_size => 20
    ) AS truth_values
  FROM restaurant_reviews r
),
reviews AS (
SELECT
  initial_arrays.review_ids[i] AS review_id,
  initial_arrays.truth_values[i] AS truth_value
FROM
  initial_arrays,
  generate_series(1, array_length(initial_arrays.review_ids, 1)) AS i
)
SELECT rest_review.city, rest_review.name
FROM restaurant_reviews rest_review JOIN reviews review ON rest_review.id=review.review_id
WHERE review.truth_value = 't'
GROUP BY rest_review.city, rest_review.name
HAVING COUNT(*) > 10;

Realiza el filtrado con cursores

En el siguiente ejemplo, se muestra cómo filtrar un conjunto grande de opiniones de restaurantes transmitiéndolas a través de un cursor.

CREATE TABLE filtered_results(input text, result bool);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    result_cursor REFCURSOR;
    rec RECORD;
BEGIN
    -- 1. Open a cursor for the input data
    OPEN prompt_cursor FOR
        SELECT r.location_city || ' has a population of > 100,000 and is a positive review; Review: ' || r.review
        FROM restaurant_reviews r;

    -- 2. Call the array-based function using the input cursor
    result_cursor := ai.if(
        'Is the given statement true? ',
        prompt_cursor,
        model_id => 'gemini-2.5-flash'
    );

    -- 3. Fetch results from the output cursor and store them
    LOOP
        FETCH result_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO filtered_results VALUES(rec.input, rec.output);
    END LOOP;

    CLOSE result_cursor;
END $$;

Creación y resumen de textos

AlloyDB AI ofrece operadores de generación de texto, como ai.generate escalar y ai.generate basados en arrays y cursores.

Realiza la generación de texto con funciones escalares

La función ai.generate produce texto combinando los datos proporcionados con la instrucción del usuario.

-- Function Signature
FUNCTION ai.generate(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS TEXT

Por ejemplo, puedes usar la siguiente consulta para generar un resumen conciso de cada opinión del usuario.

SELECT
  ai.generate(
    prompt => 'Summarize the review in 20 words or less. Review: ' || review) AS review_summary
FROM user_reviews;

Realiza la generación de texto con funciones basadas en arrays

En la siguiente consulta, se usan UNNEST y ai.generate para resumir varias opiniones de manera eficiente.

SELECT
  UNNEST(
    ai.generate(
      prompts => ARRAY_AGG('Summarize the review in 20 words or less. Review: ' || review),
      model_id => 'gemini-2.5-flash',
    )
  ) AS review_summary
FROM user_reviews;

Realiza la generación de texto con cursores

Para generar resúmenes o traducciones de millones de filas sin generar cuellos de botella de memoria, usa la generación por lotes con cursores.

CREATE TABLE summary_results(summary text);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    summary_cursor REFCURSOR;
    rec RECORD;
BEGIN
    OPEN prompt_cursor FOR SELECT review_text FROM user_reviews ORDER BY id;

    summary_cursor := ai.generate(
        'Summarize the review in 20 words or less. Review:',
        prompt_cursor,
    );

    LOOP
        FETCH summary_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO summary_results VALUES(rec.output);
    END LOOP;

    CLOSE summary_cursor;
END $$;

Cómo calificar los resultados de tu búsqueda

Si necesitas ordenar los resultados de la búsqueda con instrucciones personalizadas en lenguaje natural, usa el operador ai.rank.

Realiza la puntuación con funciones escalares

La siguiente función te permite proporcionar una instrucción que describe los criterios de clasificación y devuelve una puntuación para cada elemento.

-- Function signature
FUNCTION ai.rank(prompt TEXT, model_id VARCHAR(100) DEFAULT NULL) RETURNS real

Por ejemplo, la siguiente consulta obtiene las 20 opiniones más positivas sobre restaurantes, con las puntuaciones de un LLM.

SELECT review AS top20
FROM user_reviews
ORDER BY ai.rank(
  'Score the following review according to these rules:
  (1) Score OF 8 to 10 IF the review says the food IS excellent.
  (2) 4 to 7 IF the review says the food is ok.
  (3) 1 to 3 IF the review says the food is not good. Here is the review:' || review) DESC
LIMIT 20;

Realiza la puntuación con funciones basadas en arrays

Esta función ai.rank te permite calificar y clasificar los resultados de la búsqueda según instrucciones personalizadas en lenguaje natural.

FUNCTION ai.rank(prompts TEXT[], model_id VARCHAR(100) DEFAULT NULL) RETURNS real[]

La siguiente consulta usa UNNEST y ai.rank para calificar varias opiniones de manera eficiente.

SELECT
  UNNEST(
    ai.rank(
      ARRAY_AGG('Score the following review according to these rules:
  (1) Score OF 8 to 10 IF the review says the food IS excellent.
  (2) 4 to 7 IF the review says the food is ok.
  (3) 1 to 3 IF the review says the food is not good. Here is the review:' || review),
    )
  ) as review_scores
FROM user_reviews;

Realiza la puntuación con cursores

Esta función se usa para calificar conjuntos de datos grandes sin alcanzar los límites de memoria.

FUNCTION ai.rank(context TEXT, input_cursor REFCURSOR, model_id VARCHAR(100) DEFAULT NULL) RETURNS REFCURSOR

En el siguiente ejemplo, se muestra cómo calificar grandes volúmenes de texto según criterios específicos de lenguaje natural.

CREATE TABLE scored_results(input text, score real);

DO $$
DECLARE
    prompt_cursor REFCURSOR;
    score_cursor REFCURSOR;
    rec RECORD;
BEGIN
    OPEN prompt_cursor FOR SELECT review FROM user_reviews ORDER BY id;

    score_cursor := ai.rank(
        'Score the following review: (1) 8-10 if excellent, (2) 4-7 if ok, (3) 1-3 if not good. Review:',
        prompt_cursor,
    );

    LOOP
        FETCH score_cursor INTO rec;
        EXIT WHEN NOT FOUND;
        INSERT INTO scored_results VALUES(rec.input, rec.output);
    END LOOP;

    CLOSE score_cursor;
END $$;