genai_message_roles

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

The genai_message_roles function extracts an array of all message roles from a GenAI conversation. This provides a sequence view of conversation participants, showing the order and types of messages (user, assistant, system, tool, etc.).

You can use this function to analyze conversation patterns, validate conversation structure, detect role sequences, or understand conversation flow and complexity.

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 extract the role field from all messages in an array.

Splunk example

| eval roles=mvindex(role, 0, mvcount(role))

ANSI SQL users

In ANSI SQL, you would unnest the array and collect roles into an array.

SQL example

SELECT 
  conversation_id,
  ARRAY_AGG(role ORDER BY msg_index) as roles
FROM conversations
CROSS JOIN UNNEST(messages) WITH OFFSET AS msg_index
GROUP BY conversation_id

Usage

Syntax

genai_message_roles(messages)

Parameters

• messages (dynamic, required): An array of message objects from a GenAI conversation. Each message typically contains role and content fields.

Returns

Returns a dynamic array containing all the roles in the conversation in their original order (for example, ['system', 'user', 'assistant', 'user', 'assistant']).

Use case examples

Log analysis

Analyze common conversation patterns by examining role sequences across your application.

Query

['sample-http-logs']
| where uri contains '/api/chat'
| extend role_sequence = tostring(genai_message_roles(todynamic(response_body)['messages']))
| summarize conversation_count = count() by role_sequence
| top 10 by conversation_count

Run in Playground

Output

role_sequence	conversation_count
[“system”,“user”,“assistant”]	850
[“system”,“user”,“assistant”,“user”,“assistant”]	345
[“user”,“assistant”]	189

This query identifies the most common conversation patterns, helping you understand typical user interaction flows.

List of related functions

• genai_get_role: Gets the role at a specific index. Use this when you need a specific role rather than the full sequence.
• genai_conversation_turns: Counts conversation turns. Use this for a numerical metric of conversation length.
• genai_get_content_by_role: Gets content for a specific role. Use this after identifying roles of interest.
• array_length: Returns the number of messages. Apply this to the roles array to count messages.
• array_index_of: Finds the position of a role. Use this to detect if specific roles exist in the conversation.