# genai_message_roles



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.

## Usage [#usage]

### Syntax [#syntax]

```kusto
genai_message_roles(messages)
```

### Parameters [#parameters]

| Name     | Type    | Required | Description                                                                                                         |
| -------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------- |
| messages | dynamic | Yes      | An array of message objects from a GenAI conversation. Each message typically contains `role` and `content` fields. |

### Returns [#returns]

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

## Example [#example]

Extract all message roles from a GenAI conversation to understand the conversation structure.

**Query**

```kusto
['otel-demo-genai']
| extend roles = genai_message_roles(['attributes.gen_ai.input.messages'])
| extend role_sequence = tostring(roles)
| summarize conversation_count = count() by role_sequence
| top 5 by conversation_count
```

[Run in Playground](https://play.axiom.co/axiom-play-qf1k/query?initForm=%7B%22apl%22%3A%22%5B%27otel-demo-genai%27%5D%20%7C%20extend%20roles%20%3D%20genai_message_roles\(%5B%27attributes.gen_ai.input.messages%27%5D\)%20%7C%20extend%20role_sequence%20%3D%20tostring\(roles\)%20%7C%20summarize%20conversation_count%20%3D%20count\(\)%20by%20role_sequence%20%7C%20top%205%20by%20conversation_count%22%7D)

**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 [#list-of-related-functions]

* [genai\_get\_role](/apl/scalar-functions/genai-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](/apl/scalar-functions/genai-functions/genai-conversation-turns): Counts conversation turns. Use this for a numerical metric of conversation length.
* [genai\_get\_content\_by\_role](/apl/scalar-functions/genai-functions/genai-get-content-by-role): Gets content for a specific role. Use this after identifying roles of interest.
* [array\_length](/apl/scalar-functions/array-functions/array-length): Returns the number of messages. Apply this to the roles array to count messages.
* [array\_index\_of](/apl/scalar-functions/array-functions/array-index-of): Finds the position of a role. Use this to detect if specific roles exist in the conversation.

## Other query languages [#other-query-languages]

<LanguageComparisons>
  <Accordion title="Splunk SPL users">
    In Splunk SPL, you would extract the role field from all messages in an array.

    <CodeGroup>
      ```sql Splunk example
      | eval roles=mvindex(role, 0, mvcount(role))
      ```

      ```kusto APL equivalent
      ['ai-logs']
      | extend roles = genai_message_roles(messages)
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, you would unnest the array and collect roles into an array.

    <CodeGroup>
      ```sql 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
      ```

      ```kusto APL equivalent
      ['ai-logs']
      | extend roles = genai_message_roles(messages)
      ```
    </CodeGroup>
  </Accordion>
</LanguageComparisons>