genai_concat_contents

This page explains how to use the genai_concat_contents function in APL.

The genai_concat_contents function concatenates all message contents from a GenAI conversation array into a single string. This is useful when you need to combine multiple conversation messages into a single text field for analysis, full-text search, or creating a complete conversation transcript.

You can use this function to create searchable conversation transcripts, prepare data for analysis, or consolidate conversation history for reporting.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

In Splunk SPL, you would typically use multiple eval commands with mvjoin to concatenate array values, but there’s no direct equivalent for extracting and joining message contents from nested structures.

Splunk example

| eval all_content=mvjoin(messages, " ")

ANSI SQL users

In ANSI SQL, you would need to unnest the array and use STRING_AGG or similar functions to concatenate values, which is more verbose.

SQL example

SELECT 
  conversation_id,
  STRING_AGG(content, ' ') as all_content
FROM conversations
CROSS JOIN UNNEST(messages) as msg
GROUP BY conversation_id

Usage

Syntax

genai_concat_contents(messages, separator)

Parameters

• messages (dynamic, required): An array of message objects from a GenAI conversation. Each message typically contains a role and content field.
• separator (string, optional): The string used to separate message contents. Default is a space character (' ').

Returns

Returns a string containing all message contents concatenated together with the specified separator.

Use case examples

Log analysis

When analyzing GenAI API logs, you can concatenate all conversation messages to create a searchable transcript for debugging or analysis.

Query

['sample-http-logs']
| where uri contains '/api/chat'
| extend full_transcript = genai_concat_contents(todynamic(response_body)['messages'], '\n---\n')
| project _time, id, full_transcript

Run in Playground

Output

_time	id	full_transcript
2024-01-15T10:30:00Z	user_123	You are a helpful assistant.---How do I reset my password?---To reset your password, click on ‘Forgot Password’…
2024-01-15T10:31:00Z	user_456	You are a helpful assistant.---What are your business hours?---Our business hours are Monday to Friday, 9 AM to 5 PM.

This query extracts chat API responses and concatenates all messages from each conversation into a single searchable transcript.

List of related functions

• genai_extract_user_prompt: Extracts only the user’s prompt instead of all messages. Use this when you need just the user’s input.
• genai_extract_assistant_response: Extracts only the assistant’s response. Use this when you need just the AI’s output.
• genai_get_content_by_role: Gets content filtered by a specific role. Use this when you need messages from a particular role like ‘system’ or ‘tool’.
• genai_message_roles: Extracts all message roles from a conversation. Use this to understand the conversation structure.
• strcat_array: Concatenates a simple string array. Use this for non-GenAI arrays that don’t have the message structure.