Effectuer des requêtes SQL intelligentes à l'aide de fonctions d'IA

Les fonctions AlloyDB AI intègrent des grands modèles de langage (LLM) tels que Gemini directement à vos données AlloyDB pour PostgreSQL, ce qui vous permet de combiner le langage naturel avec des requêtes SQL. Grâce aux fonctions intégrées de filtrage sémantique (ai.if), de classement sémantique (ai.rank) et de génération de texte (ai.generate), votre application peut traiter les données avec des modèles d'IA, à la fois pour les recherches sur une seule ligne et pour les opérations de base de données à grande échelle.

Il existe trois catégories de fonctions AI, qui diffèrent selon la façon dont elles gèrent les données d'entrée et l'allocation de mémoire : les fonctions scalaires, les fonctions basées sur des tableaux et les fonctions de curseur. Le choix de la fonction IA appropriée dépend de l'échelle de vos données et de vos exigences de performances. Utilisez le tableau suivant pour en savoir plus sur ces fonctions et leurs cas d'utilisation :

Catégorie

Description

Cas d'utilisation recommandé

Scalaire

Conçu pour un traitement de base, un à un. Prend une seule entrée et renvoie une seule sortie.

À utiliser lorsque vous souhaitez une fonction de base offrant des performances acceptables pour les requêtes qui effectuent un petit nombre (moins de 50) d'appels de fonction scalaire.

Basée sur un tableau

Traite les données sous la forme d'un tableau de lignes dans un seul appel de fonction. Prend un tableau en entrée et renvoie un tableau en sortie.

Utilisez-le pour les ensembles de données de petite à moyenne taille, où l'ensemble des lignes éligibles peut tenir dans les limites de mémoire. Cela permet d'obtenir un haut débit pour les opérations basées sur des ensembles.

Cursor

Prend un curseur en entrée et renvoie un curseur en sortie.

Utilisez-le pour traiter un grand nombre de lignes (par exemple, 10 000 lignes).

Avant de commencer

Intégrer à Agent Platform et installer l'extension

  1. Configurez l'accès des utilisateurs aux modèles Agent Platform.
  2. Vérifiez que la dernière version de google_ml_integration est installée.

    1. Pour vérifier la version installée, exécutez la commande suivante :

      SELECT extversion FROM pg_extension WHERE extname = 'google_ml_integration';
extversion 
------------
1.5.2
(1 row)

    2. Si l'extension n'est pas installée ou si la version installée est antérieure à la version 1.5.2, mettez à jour l'extension.

      CREATE EXTENSION IF NOT EXISTS google_ml_integration;
ALTER EXTENSION google_ml_integration UPDATE;

      Si vous rencontrez des problèmes lors de l'exécution des commandes précédentes ou si l'extension n'est pas mise à jour vers la version 1.5.2 après l'exécution des commandes précédentes, contactez l'assistanceGoogle Cloud .

  3. Pour utiliser la fonctionnalité du moteur de requêtes AlloyDB AI, définissez l'option google_ml_integration.enable_ai_query_engine sur on.

    SQL

    1. Activez le moteur de requête IA pour la session en cours.
      SET google_ml_integration.enable_ai_query_engine = on;
    2. Activez les fonctionnalités d'une base de données spécifique pour toutes les sessions.
      ALTER DATABASE DATABASE_NAME SET google_ml_integration.enable_ai_query_engine = 'on';
    3. Activez le moteur de requête IA pour un utilisateur spécifique sur l'ensemble des sessions et des bases de données.
      ALTER ROLE postgres SET google_ml_integration.enable_ai_query_engine = 'on';

    Console

    Pour modifier la valeur de l'indicateur de base de données google_ml_integration.enable_ai_query_engine, suivez les étapes de la section Configurer les indicateurs de base de données d'une instance.

    gcloud

    Pour utiliser la gcloud CLI, vous pouvez installer et initialiser la Google Cloud CLI, ou utiliser Cloud Shell.

    Vous pouvez modifier la valeur de l'option google_ml_integration.enable_ai_query_engine. Pour en savoir plus, consultez Configurer les indicateurs de base de données d'une instance. 

    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

Utiliser un modèle Gemini compatible dans votre région

Le modèle par défaut du moteur de requête IA est gemini-3.5-flash-lite. Si vous ne spécifiez pas de model_id dans vos fonctions AI, vos requêtes utilisent ce modèle. Pour vérifier la disponibilité des modèles, consultez Régions prises en charge. Pour en savoir plus sur les tarifs, consultez Tarifs d'Agent Platform.

Si votre cluster AlloyDB pour PostgreSQL se trouve dans une région où gemini-3.5-flash-lite n'est pas compatible, vous pouvez spécifier un autre modèle Gemini disponible à l'aide du paramètre model_id. Pour en savoir plus, consultez Emplacements des points de terminaison des modèles Google.

Vous pouvez également enregistrer un point de terminaison de modèle Gemini et fournir cet ID de modèle aux opérateurs d'IA. Pour en savoir plus, consultez Enregistrer et appeler des modèles d'IA distants à l'aide de la gestion des points de terminaison de modèle.

L'exemple suivant montre comment enregistrer un autre point de terminaison Gemini. Dans cet exemple, ce deuxième point de terminaison Gemini est le point de terminaison global pour gemini-3.5-flash-lite. Vous pouvez utiliser ce modèle enregistré avec des opérateurs d'IA en transmettant model_id => 'gemini-3.5-flash-lite-global' comme argument supplémentaire.

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

Utiliser les modèles Gemini 3.0

Certains modèles Gemini, tels que gemini-3.0-pro-preview, ne sont disponibles que via le point de terminaison global. Vous devez enregistrer ces modèles comme suit :

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'
);

Remplacez PROJECT_ID par l'ID du projet dans lequel le modèle Agent Platform est disponible. Le compte de service AlloyDB doit disposer du rôle Utilisateur Agent Platform dans ce projet.

Après avoir enregistré le modèle, vous pouvez l'utiliser dans les fonctions AI comme suit :

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

Utiliser des filtres dans vos requêtes

AlloyDB AI propose des fonctions SQL optimisées par l'IA qui vous permettent d'utiliser le traitement du langage naturel et les LLM directement dans vos requêtes de base de données, y compris les opérateurs ai.if et ai.rank.

Effectuer un filtrage à l'aide de fonctions scalaires

Pour évaluer si une condition énoncée en langage naturel est remplie, utilisez l'opérateur ai.if/google_ml.if. La fonction renvoie une valeur booléenne "true" ou "false", et renvoie false si le résultat n'est pas clairement détecté.

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

L'exemple suivant montre l'utilisation de l'opérateur ai.if comme filtre pour trouver des restaurants ayant reçu plus de 500 avis positifs et situés dans des villes de plus de 100 000 habitants. L'exemple utilise restaurant_reviews et contient des données telles que des avis et la localisation de la ville. L'opérateur ai.if vous aide à comprendre l'opinion des avis et à combiner les emplacements de la base de données avec les connaissances générales de Gemini sur la population de ces emplacements.

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;

L'exemple suivant montre le même exemple en utilisant le modèle que vous avez enregistré dans Utiliser un modèle Gemini compatible dans votre région.

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-3.5-flash-lite')
GROUP BY r.name, r.location_city
HAVING COUNT(*) > 500;

Effectuer une jointure sur une requête qui utilise l'opérateur "if"

Pour effectuer une opération de jointure, utilisez l'opérateur ai.if/google_ml.if avec join. L'exemple de requête suivant recherche le nombre d'avis qui mentionnent chaque élément du menu du restaurant.

    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;

Effectuer un filtrage à l'aide de fonctions basées sur les tableaux

L'exemple suivant identifie les restaurants ayant plus de 10 avis positifs en utilisant un modèle d'IA (gemini-3.5-flash-lite) pour analyser le sentiment des avis et filtrer les résultats. ARRAY_AGG permet de transformer des lignes de données individuelles en tableaux structurés afin qu'elles puissent être traitées par le modèle d'IA de manière groupée plutôt qu'une ligne à la fois.

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-3.5-flash-lite',
      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.location_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.location_city, rest_review.name
HAVING COUNT(*) > 10;

Effectuer un filtrage à l'aide de curseurs

L'exemple suivant montre comment filtrer un grand ensemble d'avis sur des restaurants en les diffusant via un curseur.

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-3.5-flash-lite'
    );

    -- 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 $$;

Génération et synthèse de texte

AlloyDB AI propose des opérateurs de génération de texte tels que les opérateurs scalaires ai.generate, ainsi que les opérateurs basés sur des tableaux et des curseurs ai.generate.

Pour en savoir plus sur les fonctions et les paramètres des opérateurs, consultez la documentation de référence sur les fonctions des opérateurs. Pour obtenir des guides dédiés à des tâches textuelles spécifiques, consultez Résumer du contenu et Analyser les sentiments d'un texte.

Générer du texte à l'aide de fonctions scalaires

La fonction ai.generate produit du texte en combinant les données fournies avec le prompt de l'utilisateur.

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

Par exemple, vous pouvez utiliser la requête suivante pour générer un résumé concis de chaque avis utilisateur.

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

Générer du texte à l'aide de fonctions basées sur les tableaux

Cette fonction ai.generate vous permet de générer du texte pour plusieurs requêtes par lots.

-- Function signature
FUNCTION ai.generate(
  prompts TEXT[],
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS TEXT[]

La requête suivante utilise UNNEST et ai.generate pour résumer efficacement plusieurs avis.

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

Générer du texte à l'aide de curseurs

Pour générer des résumés ou des traductions pour des millions de lignes sans rencontrer de goulots d'étranglement de mémoire, utilisez la génération par lot avec des curseurs.

-- Function signature
FUNCTION ai.generate(
  prompt TEXT,
  input_cursor REFCURSOR,
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS REFCURSOR

L'exemple suivant montre comment générer des résumés pour de grands volumes de texte à l'aide de curseurs.

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 $$;

Évaluer les résultats de votre requête

Si vous devez trier les résultats d'une requête à l'aide d'instructions personnalisées en langage naturel, utilisez l'opérateur ai.rank.

Effectuer l'évaluation à l'aide de fonctions scalaires

La fonction suivante vous permet de fournir une requête décrivant les critères de classement et renvoie un score pour chaque élément.

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

Par exemple, la requête suivante récupère les 20 avis de restaurants les plus positifs, en utilisant les scores d'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;

Effectuer l'évaluation à l'aide de fonctions basées sur les tableaux

Cette fonction ai.rank vous permet d'évaluer et de classer les résultats de requête en fonction d'instructions personnalisées en langage naturel.

-- Function signature
FUNCTION ai.rank(
  prompts TEXT[],
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS real[]

La requête suivante utilise UNNEST et ai.rank pour évaluer efficacement plusieurs avis.

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;

Effectuer une notation à l'aide de curseurs

Cette fonction permet d'évaluer de grands ensembles de données sans atteindre les limites de mémoire.

-- Function signature
FUNCTION ai.rank(
  prompt TEXT,
  input_cursor REFCURSOR,
  batch_size INT DEFAULT NULL,
  model_id VARCHAR(100) DEFAULT NULL)
RETURNS REFCURSOR

L'exemple suivant montre comment évaluer de grands volumes de texte en fonction de critères de langage naturel spécifiques.

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 $$;

Étapes suivantes