funktion ai_enrich

gäller för: Databricks SQL Databricks Runtime

Funktionen genererar ai_enrich() nya kolumner för en rad från ett schema du definierar. Givet indata och ett målschema anropar funktionen en AI-modell för att fylla i varje fält. Den kan valfritt förankra de genererade värdena i en eller flera kunskapskällor som ett AI-sökindex eller ett sökverktyg på en extern Model Context Protocol (MCP)-server, så att värdena speglar din egen data eller up-to-datuminformation snarare än modellens träningsdata ensam.

Använd ai_enrich för att lägga till härledda attribut i en tabell i stor skala. Du kan tagga och kategorisera poster, fylla i saknad metadata eller bifoga undersökt kontext till varje rad från ett enda SQL-funktionsanrop. Som standard returneras varje genererat fält med en kort motivering som förklarar hur värdet härleds.

Requirements

• Databricks Runtime 18.2 eller senare.
• Om du använder serverless compute måste versionen av serverless miljöer vara inställd på 3 eller högre, eftersom detta möjliggör funktioner som VARIANT.
• För att förankra berikning i ett AI-sökindex behöver du ett eller flera AI-sökindex som kunskapskällor.
• För att grunda berikning i en extern MCP-server behöver du en MCP registrerad i Unity Gateway, EXECUTE på den, och USE CATALOGUSE SCHEMA på dess föräldrakatalog och schema. Se MCP-konfiguration.
• Funktionen ai_enrich finns tillgänglig med hjälp av Azure Databricks-notebooks, SQL-editor, jobb eller Lakeflow-pipelines.

Datasäkerhet

Dina dokumentdata bearbetas inom Databricks säkerhetsperimeter. Databricks lagrar inte parametrarna som skickas till AI-funktionsanropen, men behåller metadata-kördetaljer, såsom Databricks Runtime-versionen som används.

Om du konfigurerar en mcp kunskapskälla skickas sökfrågan som ai_enrich byggs från varje rad till den externa leverantören, så behandla radinnehåll som når den som data som lämnar Azure Databricks. Se MCP-konfiguration.

Syntax

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

Arguments

• content: Ett STRING eller VARIANT uttryck. Raden för att berika. VARIANT indata, såsom utdata från en annan AI-funktion som ai_parse_document, serialiseras internt till en JSON-sträng.

• schema: Ett STRING bokstavligt tal som definierar vilka kolumner som ska genereras. Den använder samma grammatik som ai_extract. Schemat kan vara:

  • Enkelt schema: En JSON-array av fältnamn, som genereras som strängar.

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

  • Avancerat schema: Ett JSON-objekt med typinformation, beskrivningar och nästlade strukturer.

    • Stöder string, integer, number, booleanoch enum typer. Utför typverifiering. Maximalt 500 uppräkningsvärden.
    • Stöder nästlade objekt med hjälp "type": "object" av ."properties"
    • Stöder arrayer av primitiva eller objekt som använder "type": "array" med ."items"
    • Valfritt "description" fält för varje egenskap för att styra det genererade värdet.

    {
      "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: Ett valfritt VARIANT eller STRING uttryck som innehåller en JSON-array av kunskapskällskonfigurationer som används för att grunda de genererade värdena. Se konfiguration av kunskapskällor.

• options: Ett valfritt MAP<STRING, STRING>. Stödda nycklar:

  • 'version': Funktionsversionen att använda.
  • 'instructions': A STRING på upp till 20 000 tecken. Naturlig språklig vägledning som beskriver berikningsuppgiften. Valfritt; schemafältens namn kan ensamma driva berikningen. Till exempel: 'Infer attributes for each company from its public profile.'
  • 'enableRationale': 'true' (standard) eller 'false'. När 'true', returneras varje genererat fält som ett {rationale, value} objekt, där rationale förklarar hur värdet härleds. Ställ in på 'false' endast retur.{value}

Konfiguration av kunskapskälla

Argumentet knowledge_sources är en JSON-array. Varje element är ett {type, description, config} kuvert. Fältet type identifierar hur ai_enrich man hämtar jordningskontext, och config fältet innehåller den källspecifika konfigurationen.

AI-sökningsindexkonfiguration

För ett AI-sökningsindex med type satt till vector_search, config accepterar följande nycklar:

Du kan konfigurera mer än en vector_search källa i ett enda samtal. För ett exempel, se Ground enrichment in an AI Search index.

MCP-konfiguration

En mcp källa jordar varje rad med ett sökverktyg på en extern MCP-server, såsom You.com eller Exa. Använd det för att jorda rader i en sökleverantör du redan har ett konto hos. ai_enrich anropar verktyget via Unity Gateway som identiteten som kör frågan. Varje mcp källa summerar upp till fem resultat-URL:er till .metadata.sources

Innan du använder en mcp källa:

1. Registrera servern som MCP. Se Externa MCP-servrar. För en server listad i Databricks Marketplace, såsom You.com, skapar installationen av listningen MCP åt dig. Se Få åtkomst till externa MCP-servrar.
2. Använd en anslutning med en delad legitimation, såsom leverantörens API-nyckel, som en bärartoken. ai_enrich Kan inte be om inloggning, så om anslutningen kräver att varje användare loggar in, misslyckas källan mcp för användare som inte har loggat in.
3. Grant EXECUTE på MCP, och USE CATALOGUSE SCHEMA på dess föräldrakatalog och schema, till identiteten som kör frågan: varje användare, eller kör-som-identiteten för ett jobb eller pipeline. Se Dela en MCP.

För en mcp källa config accepterar följande nycklar:

För varje rad med icke-tomt innehåll ai_enrich byggs en kort sökfråga från radinnehållet följt av de begärda fälten. Varje toppnivåfält bidrar med sin beskrivning, eller sitt namn om det inte finns någon beskrivning. Frågan klipps till max_query_chars, så för en lång rad kan fälttexten skäras bort. ai_enrich anropar verktyget för varje mcp källa en gång med den frågan. Varje samtal går ut efter 60 sekunder. Ett samtal som går ut eller misslyckas med felet 429, 500, 502, 503 eller 504 försöks om upp till tre gånger. Eftersom omprövningar kan upprepa ett anrop, använd ett skrivskyddat sökverktyg. Samtal till leverantören räknas mot ditt leverantörskontos prissättning och prisgränser.

Om ett anrop misslyckas och ingen annan kunskapskälla returnerar resultat, error_message sätts och response gäller null för den raden. Till exempel misslyckas ett anrop om leverantören avvisar API-nyckeln eller om identiteten som kör frågan saknas EXECUTE på MCP. Om en annan kunskapskälla returnerar resultat är raden grundad endast i dessa resultat och inget fel rapporteras. Om verktyget inte ger några resultat och ingen annan kunskapskälla gör det heller, berikas raden enbart av sitt innehåll, utan jordning.

Om mcp kunskapskällor inte är aktiverade för arbetsområdet returnerar null varje rad med icke-tomt innehåll för response och , error_messagemcp knowledge source is not available: it is not enabled for this workspace.även när anropet också konfigurerar andra kunskapskällor.

Du kan konfigurera mer än en mcp källa i ett enda samtal. För ett exempel, se Markberikning i en extern MCP-sökleverantör.

Returns

A VARIANT med följande schema:

{
  "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.
}

Fältet response innehåller de genererade kolumnerna:

• Fältnamn och typer stämmer överens med schemats definition. Nästlade objekt och arrayer behåller sin ursprungliga form.
• Som standard (enableRationale är 'true'), är varje blad ett {rationale, value} objekt, där rationale är en kort förklaring av hur värdet härleds och value är det genererade värdet, skrivet enligt schemat. När enableRationale är 'false'är , är varje blad ett {value} objekt.
• Ett fälts value är null när det inte kan genereras.

Fältet metadata innehåller metadata om svaret. När raden är jordad av en kunskapskälla metadata.sources är en array av källdokumentidentifierare som jordade raden. Jordning är radnivå, så sources det gäller hela raden snarare än enskilda fält.

Om content är NULL är NULL resultatet.

Examples

Markberikning i ett AI-sökningsindex

Följande exempel berikar varje supportärende med fält som är grundade i ett AI-sökningsindex av produktdokumentation, så att de genererade värdena hämtas från ditt eget innehåll:

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;

Markberikning i en extern MCP-sökleverantör

Följande exempel berikar varje företag med fält baserade på You.com sökresultat. Den anropar you-search verktyget på en MCP som heter 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;

Följande exempel använder istället Exa. Exas web_search_exa verktyg listas objective som ett obligatoriskt argument, så exemplet skickar in det 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 stöder inte kunskapskällan web_search . För att jorda rader i en sökleverantör, använd en mcp källa. Se MCP-konfiguration.
• En mcp kunskapskälla kan inte uppmana användare att logga in hos leverantören. Om anslutningen kräver att varje användare loggar in, misslyckas samtal för användare som inte har loggat in.
• En mcp kunskapskälla stöder inte tjänstepolicyer som returnerar ASK. ai_enrich Kan inte visa godkännandebegäran, så samtal som kräver godkännande misslyckas.
• Alternativet instructions är begränsat till 20 000 tecken.

Relaterade funktioner

• ai_extract funktion
• ai_search funktion
• ai_parse_document funktion
• ai_prep_search funktion
• ai_query funktion