genai_get_content_by_role

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

The genai_get_content_by_role function retrieves the content of a message with a specific role from a GenAI messages array. It returns the first message matching the specified role (such as ‘user’, ‘assistant’, ‘system’, or ‘tool’).

You can use this function to extract messages by role, filter conversations by participant type, analyze specific role patterns, or process messages from particular conversation participants.

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 use mvfilter to filter by role and then extract the content.

Splunk example

| eval filtered_msgs=mvfilter(match(role, "system"))
| eval content=mvindex(filtered_msgs, 0)

ANSI SQL users

In ANSI SQL, you would unnest the array, filter by role, and limit to the first result.

SQL example

SELECT 
  conversation_id,
  content
FROM conversations
CROSS JOIN UNNEST(messages)
WHERE role = 'system'
LIMIT 1

Usage

Syntax

genai_get_content_by_role(messages, role)

Parameters

• messages (dynamic, required): An array of message objects from a GenAI conversation. Each message typically contains role and content fields.
• role (string, required): The role to filter by. Common values include ‘user’, ‘assistant’, ‘system’, ‘tool’, or ‘function’.

Returns

Returns a string containing the content of the first message with the specified role, or an empty string if no matching message is found.

Use case examples

Log analysis

Extract tool role messages to analyze function calling and external API usage patterns.

Query

['sample-http-logs']
| where uri contains '/api/chat'
| extend tool_message = genai_get_content_by_role(todynamic(response_body)['messages'], 'tool')
| where isnotempty(tool_message)
| project _time, id, req_duration_ms, tool_message

Run in Playground

Output

_time	id	req_duration_ms	tool_message
2024-01-15T10:30:00Z	user_123	2150	{"temperature": 72, "condition": "sunny"}
2024-01-15T10:31:00Z	user_456	1980	{"stock_price": 150.25, "change": "+2.3%"}

This query extracts tool messages to understand what data external functions are returning.

List of related functions

• genai_get_content_by_index: Gets content by position. Use this when you need a message at a specific index rather than by role.
• genai_extract_user_prompt: Extracts the last user prompt. Use this shorthand when you specifically need the most recent user message.
• genai_extract_assistant_response: Extracts the last assistant response. Use this shorthand when you specifically need the most recent AI response.
• genai_extract_system_prompt: Extracts the system prompt. Use this shorthand when you specifically need the system message.
• genai_message_roles: Lists all roles in the conversation. Use this to understand what roles are present before extracting by role.