> ## Documentation Index
> Fetch the complete documentation index at: https://axiom.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<AccordionGroup>
  <Accordion title="Splunk SPL users">
    In Splunk SPL, you would use `mvfilter` to filter by role and then extract the content.

    <CodeGroup>
      ```sql Splunk example theme={null}
      | eval filtered_msgs=mvfilter(match(role, "system"))
      | eval content=mvindex(filtered_msgs, 0)
      ```

      ```kusto APL equivalent theme={null}
      ['ai-logs']
      | extend content = genai_get_content_by_role(messages, 'system')
      ```
    </CodeGroup>
  </Accordion>

  <Accordion title="ANSI SQL users">
    In ANSI SQL, you would unnest the array, filter by role, and limit to the first result.

    <CodeGroup>
      ```sql SQL example theme={null}
      SELECT 
        conversation_id,
        content
      FROM conversations
      CROSS JOIN UNNEST(messages)
      WHERE role = 'system'
      LIMIT 1
      ```

      ```kusto APL equivalent theme={null}
      ['ai-logs']
      | extend content = genai_get_content_by_role(messages, 'system')
      ```
    </CodeGroup>
  </Accordion>
</AccordionGroup>

## Usage

### Syntax

```kusto theme={null}
genai_get_content_by_role(messages, role)
```

### 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. |
| role     | string  | Yes      | 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.

## Example

Extract the content of the system message from a GenAI conversation.

**Query**

```kusto theme={null}
['otel-demo-genai']
| extend system_content = genai_get_content_by_role(['attributes.gen_ai.input.messages'], 'system')
| where isnotempty(system_content)
| summarize conversation_count = count() by system_content
| top 3 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%20system_content%20%3D%20genai_get_content_by_role\(%5B%27attributes.gen_ai.input.messages%27%5D%2C%20%27system%27\)%20%7C%20where%20isnotempty\(system_content\)%20%7C%20summarize%20conversation_count%20%3D%20count\(\)%20by%20system_content%20%7C%20top%203%20by%20conversation_count%22%7D)

**Output**

| system\_content                       | conversation\_count |
| ------------------------------------- | ------------------- |
| You are a helpful shopping assistant. | 1250                |
| You are a technical support expert.   | 845                 |

This query shows the distribution of system prompts being used, helping ensure configuration consistency.

## List of related functions

* [genai\_get\_content\_by\_index](/apl/scalar-functions/genai-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](/apl/scalar-functions/genai-functions/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](/apl/scalar-functions/genai-functions/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](/apl/scalar-functions/genai-functions/genai-extract-system-prompt): Extracts the system prompt. Use this shorthand when you specifically need the system message.
* [genai\_message\_roles](/apl/scalar-functions/genai-functions/genai-message-roles): Lists all roles in the conversation. Use this to understand what roles are present before extracting by role.