ai_enrich Fonction

S’applique à : Databricks SQL Databricks Runtime

La ai_enrich() fonction génère de nouvelles colonnes pour une ligne à partir d’un schéma que vous définissez. À partir du contenu d’entrée et d’un schéma cible, la fonction appelle un modèle d’IA pour remplir chaque champ. Il peut éventuellement ancrer les valeurs générées dans une ou plusieurs sources de connaissances , comme un index de recherche IA ou un outil de recherche sur un serveur externe de protocole de contexte de modèle (MCP), de sorte que les valeurs reflètent vos propres données ou informations de up-to-date plutôt que les seules données d’entraînement du modèle.

À utiliser ai_enrich pour ajouter des attributs dérivés à une table à grande échelle. Vous pouvez taguer et catégoriser les enregistrements, combler les métadonnées manquantes, ou attacher le contexte recherché à chaque ligne à partir d’un seul appel de fonction SQL. Par défaut, chaque champ généré est renvoyé avec une courte justification expliquant comment la valeur a été déduite.

Spécifications

• Databricks Runtime 18.2 ou version ultérieure.
• Si vous utilisez le calcul serverless, la version de l’environnement serverless doit être réglée à 3 ou plus, car cela permet des fonctionnalités comme VARIANT.
• Pour ancrer l’enrichissement dans un index IA Search, il vous faut un ou plusieurs index AI Search à utiliser comme sources de connaissances.
• Pour mettre à la terre l’enrichissement dans un serveur MCP externe, il faut un MCP enregistré dans Unity Gateway, EXECUTE dessus, ainsi USE CATALOG que USE SCHEMA sur son catalogue parent et son schéma. Voir la configuration MCP.
• La ai_enrich fonction est disponible via les notebooks Azure Databricks, l’éditeur SQL, les jobs ou les pipelines Lakeflow.

Sécurité des données

Vos données de document sont traitées dans le périmètre de sécurité Databricks. Databricks ne stocke pas les paramètres qui sont passés dans les appels de fonctions IA, mais conserve les détails de la gestion des métadonnées, comme la version d’exécution de Databricks utilisée.

Si vous configurez une mcp source de connaissances, la requête de recherche qui ai_enrich s’engagent à partir de chaque ligne est envoyée au fournisseur externe, donc considérez le contenu de la ligne qui y parvient comme des données sortant d’Azure Databricks. Voir la configuration MCP.

Syntax

ai_enrich(content, schema [, knowledge_sources] [, options])

Arguments

• content : Une expression STRING ou VARIANT. La dispute pour enrichir. VARIANT l’entrée, comme la sortie d’une autre fonction IA comme ai_parse_document, est sérialisée en une chaîne JSON en interne.

• schema: Un STRING littéral qui définit les colonnes à générer. Il utilise la même grammaire que ai_extract. Le schéma peut être :

  • Schéma simple : un tableau JSON de noms de champs, qui sont générés sous forme de chaînes.

    ["industry", "headquarters_country", "year_founded"]
    

  • Schéma avancé : un objet JSON avec informations de type, descriptions et structures imbriquées.

    • Prend en charge string, , integernumber, booleanet enum les types. Effectue la validation de type. Maximum de 500 valeurs d’énumération.
    • Prend en charge les objets imbriqués en utilisant "type": "object" avec "properties".
    • Prend en compte des tableaux de primitives ou d’objets utilisant "type": "array" avec "items".
    • Champ optionnel "description" pour chaque propriété afin de guider la valeur générée.

    {
      "hq_address": {
        "type": "object",
        "description": "Registered headquarters address",
        "properties": {
          "city": { "type": "string" },
          "country": { "type": "string" }
        }
      },
      "founding_team": { "type": "array", "description": "Full names of the founders", "items": { "type": "string" } },
      "founding_year": { "type": "integer", "description": "Year the company was founded" }
    }
    

• knowledge_sources: Une option VARIANT ou STRING une expression contenant un tableau JSON de configurations de sources de connaissances utilisées pour mettre à la terre les valeurs générées. Voir Configuration de la source de connaissances.

• options: facultatif MAP<STRING, STRING>. Touches prises en charge :

  • 'version': La version fonctionnelle à utiliser.
  • 'instructions': A STRING de jusqu’à 20 000 caractères. Conseils en langage naturel qui décrivent la tâche d’enrichissement. Optionnel ; les noms des champs de schéma seuls peuvent piloter l’enrichissement. Par exemple : 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (par défaut) ou 'false'. Lorsque 'true', chaque champ généré est retourné comme un {rationale, value} objet, où rationale explique comment la valeur a été dérivée. Réglez sur 'false' retour {value} uniquement.

Configuration de la source de connaissances

L’argument knowledge_sources est un tableau JSON. Chaque élément est une {type, description, config} enveloppe. Le type champ identifie comment ai_enrich il récupère le contexte de mise à la terre, et le config champ contient la configuration spécifique à la source.

Configuration de l’index de recherche IA

Pour un index IA Search avec type défini à vector_search, config accepte les clés suivantes :

Vous pouvez configurer plus d’une vector_search source en un seul appel. Pour un exemple, voir Enrichissement au sol dans un index de recherche IA.

Configuration MCP

Une source met mcp chaque ligne à la base avec un outil de recherche sur un serveur MCP externe, tel que You.com ou Exa. Utilisez-le pour ancrer les lignes dans un fournisseur de recherche avec lequel vous avez déjà un compte. ai_enrich appelle l’outil via Unity Gateway comme identité qui exécute la requête. Chaque mcp source ajoute jusqu’à cinq URL de résultats à metadata.sources.

Avant d’utiliser une mcp source :

1. Enregistrez le serveur comme MCP. Voir Serveurs MCP externes. Pour un serveur listé sur Databricks Marketplace, comme You.com, installer la fiche crée le MCP pour vous. Consultez Obtenir l’accès aux serveurs MCP externes.
2. Utilisez une connexion avec un identifiant partagé, comme la clé API du fournisseur comme jeton porteur. ai_enrich Impossible de demander la connexion, donc si la connexion nécessite que chaque utilisateur se connecte, la mcp source échoue pour les utilisateurs qui ne se sont pas connectés.
3. Accorder EXECUTE sur le MCP, et USE CATALOGUSE SCHEMA sur son catalogue parent et son schéma, à l’identité qui exécute la requête : chaque utilisateur, ou l’identité exécutée d’un travail ou d’un pipeline. Voir « Partager un MCP ».

Pour une mcp source, config accepte les clés suivantes :

Pour chaque ligne contenant du contenu non vide, ai_enrich une courte requête de recherche à partir du contenu de la ligne est créée suivie des champs demandés. Chaque champ de niveau supérieur contribue à sa description, ou à son nom s’il n’a pas de description. La requête est coupée à max_query_chars, donc pour une longue ligne, le texte du champ peut être coupé. ai_enrich Appelle l’outil de chaque mcp source une fois avec cette requête. Chaque appel expire après 60 secondes. Un appel qui expire ou échoue avec une erreur 429, 500, 502, 503 ou 504 est réessayé jusqu’à trois fois. Comme les réessais peuvent répéter un appel, utilisez un outil de recherche en lecture seule. Les appels vers le fournisseur comptent dans les limites de prix et de tarif de votre compte opérateur.

Si un appel échoue et qu’aucune autre source de connaissance ne renvoie de résultats, error_message est défini et response est null pour cette ligne. Par exemple, un appel échoue si le fournisseur rejette la clé API ou si l’identité qui exécute la requête est EXECUTE absente sur le MCP. Si une autre source de connaissance renvoie les résultats, la ligne est mise à la terre uniquement dans ces résultats et aucune erreur n’est rapportée. Si l’outil ne donne aucun résultat et qu’aucune autre source de connaissance ne le fait non plus, la ligne est enrichie uniquement par son contenu, sans mise à la terre.

Si mcp les sources de connaissances ne sont pas activées pour l’espace de travail, chaque ligne contenant du contenu non vide retourne null pour response et le error_messagemcp knowledge source is not available: it is not enabled for this workspace., même lorsque l’appel configure également d’autres sources de connaissances.

Vous pouvez configurer plus d’une mcp source en un seul appel. Pour un exemple, voir Enrichissement au sol dans un fournisseur externe de recherche MCP.

Returns

A VARIANT avec le schéma suivant :

{
  "response": { ... },     // Generated columns matching the provided schema. Each leaf is returned as an object (see below).
  "error_message": null,   // null on success, or an error message on failure
  "metadata": { ... }      // Metadata about the response, including grounding sources.
}

Le response champ contient les colonnes générées :

• Les noms et types de champs correspondent à la définition du schéma. Les objets imbriqués et les réseaux conservent leur forme d’origine.
• Par défaut (enableRationale est 'true'), chaque feuille est un {rationale, value} objet, où rationale est une brève explication de la manière dont la valeur a été dérivée et value est la valeur générée, typée selon le schéma. Lorsque enableRationale est 'false', chaque feuille est un {value} objet.
• Celui d’un value champ est null lorsqu’il ne peut pas être généré.

Le metadata champ contient des métadonnées sur la réponse. Lorsque la ligne est mise à la terre par une source de connaissances, metadata.sources il s’agit d’un tableau des identifiants du document source qui a mis la ligne à la base. La mise à la terre est au niveau des lignes, donc sources s’applique à toute la ligne plutôt qu’aux champs individuels.

Si content est NULL, le résultat est NULL.

Exemples

Enrichissement du sol dans un index de recherche IA

L’exemple suivant enrichit chaque ticket de support avec des champs fondés sur un index IA Search de la documentation produit, de sorte que les valeurs générées sont tirées de votre propre contenu :

SELECT
  ticket_id,
  ai_enrich(
    customer_description,
    '{
      "affected_product": {"type": "string"},
      "suggested_resolution": {"type": "string"},
      "documentation_url": {"type": "string"}
    }',
    PARSE_JSON('[{
      "type": "vector_search",
      "description": "Product documentation and troubleshooting guides",
      "config": {
        "index_name": "support.docs.product_documentation",
        "text_col": "content",
        "doc_uri_col": "doc_url"
      }
    }]')
  ) AS result
FROM support.tickets.open_tickets;

Enrichissement au sol dans un fournisseur de recherche MCP externe

L’exemple suivant enrichit chaque entreprise avec des champs fondés sur You.com résultats de recherche. Il appelle l’outil you-search sur un MCP nommé main.default.youcom:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "mcp",
    "description": "You.com web search",
    "config": {
      "mcp_service": "main.default.youcom",
      "tool": "you-search"
    }
  }]')
) AS result
FROM sales.accounts.companies;

L’exemple suivant utilise plutôt Exa. L’outil d’Exa web_search_exa est listé objective comme argument obligatoire, donc l’exemple le transmet dans arguments:

SELECT ai_enrich(
  company_name,
  '["industry", "headquarters_country", "year_founded"]',
  PARSE_JSON('[{
    "type": "mcp",
    "description": "Exa web search",
    "config": {
      "mcp_service": "main.default.exa",
      "tool": "web_search_exa",
      "arguments": {"objective": "Find public company profile facts"}
    }
  }]')
) AS result
FROM sales.accounts.companies;

Limitations

• ai_enrich ne prend pas en charge la source de web_search connaissances. Pour mettre à la terre les lignes dans un fournisseur de recherche, utilisez une mcp source. Voir la configuration MCP.
• Une mcp source de connaissances ne peut pas inciter les utilisateurs à se connecter au fournisseur. Si la connexion nécessite que chaque utilisateur se connecte, les appels échouent pour les utilisateurs qui ne se sont pas connectés.
• Une source de connaissances ne prend pas en charge les politiques de service qui retournent ASKmcp . ai_enrich Impossible de montrer la demande d’approbation, donc les appels nécessitant une approbation échouent.
• L’option instructions est limitée à 20 000 personnages.

Fonctions associées

• ai_extract fonction
• ai_search fonction
• ai_parse_document fonction
• ai_prep_search fonction
• ai_query fonction