# YARA-L 2.0 dashboard query library

Supported in:

> [!CAUTION]
> **Caution:** The Ingestion API described in this document is [deprecated](https://docs.cloud.google.com/chronicle/docs/deprecations) and will be discontinued on July 20, 2027. To ingest data into Google SecOps, use the [Chronicle API](https://docs.cloud.google.com/chronicle/docs/reference/rest) instead. For details on how to migrate, see [Migrate from legacy SIEM API to Chronicle API](https://docs.cloud.google.com/chronicle/docs/administration/migrate-from-legacy-api-to-chronicle-api).

This document provides a library of YARA-L 2.0 query examples for common dashboard use cases. These examples are organized by data source to help you visualize security telemetry, track analyst workflows, and measure the effectiveness of your automated response playbooks. For more information about dashboards, see [Dashboards overview](https://docs.cloud.google.com/chronicle/docs/reports/dashboards-overview).

By using these queries, you can transform raw event and case data into high-level metrics, such as:

- Monitoring log volume and drop rates.
- Tracking the Mean Time to Repair (MTTR) and analyst workload.
- Identifying top IoCs and frequent rule detections.

For more information about building and customizing your visual interface, see the [Dashboards overview](https://docs.cloud.google.com/chronicle/docs/reports/dashboards-overview).

## Supported data sources

To build effective dashboard widgets, you must first identify the correct data source for the metrics you want to visualize. Each data source within Google Security Operations is accessed using a specific YARA-L prefix and has unique time-retention limits.

Dashboards include the following data sources, each with its own query time limit and YARA-L prefix:

| Data source | Query time interval | YARA-L prefix | Schema | Dashboard examples |
|---|---|---|---|---|
| Case history | 365 days | `case_history` | [Fields (SOAR)](https://docs.cloud.google.com/chronicle/docs/reference/soar-data-dashboard#case-history) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#dashboard-query-examples-case-history) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-case-history) |
| Cases and alerts | 365 days | `case` | [Fields (SOAR)](https://docs.cloud.google.com/chronicle/docs/reference/soar-data-dashboard#cases-and-alerts) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#cases-and-alerts) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-cases) |
| Data tables | No standalone time limit (governed by the joined data source) | `%` | User-defined | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-data-tables) |
| Detections | 365 days | `detection` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#detections-fields) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#detections) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#dashboard-query-examples-detections) |
| Entity Graph | 365 days | `graph` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#entity-graph-fields) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#entity-graph) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-entity-graph) |
| Events | 90 days | `no prefix` | [Fields (UDM)](https://docs.cloud.google.com/chronicle/docs/reference/udm-field-list) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#udm-event) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-events) |
| Ingestion metrics | 365 days | `ingestion` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-metrics-schema) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#ingestion-metrics) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-ingestion-metrics) |
| IoCs | 365 days | `ioc` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/yaral-functions-native-dashboards#ioc_fields) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#iocs) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-iocs) |
| Playbooks | 365 days | `playbook` | [Fields (SOAR)](https://docs.cloud.google.com/chronicle/docs/reference/soar-data-dashboard#playbook) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#playbooks) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-playbooks) |
| Rule sets | 365 days | `ruleset` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/yaral-functions-native-dashboards#rule_sets_fields) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#dashboard-query-examples-rulesets) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-rulesets) |
| Rules | No time limit | `rules` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/yaral-functions-native-dashboards#rule_fields) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#rules) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-rules) |
| Triage and Investigation Agent | 365 days | `gemini_investigation`, `gemini_investigation_feedback` | [Fields](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#triage-investigation-agent-fields) \| [Template](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#triage-investigation-agent) | [Examples](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#query-examples-triage-investigation-agent) |

> [!NOTE]
> **Note:** By default, chart queries return a limit of 1,000 rows. You can customize this limit up to 10,000 using the `limit` section in YARA-L queries. This customization applies only to custom dashboard queries, not to curated queries.

> [!NOTE]
> **Note:** Dashboards support querying SOAR case data generated on or after May 10, 2025.

> [!IMPORTANT]
> **Important:** When you define YARA-L queries for dashboards, you must include a `match` or an `outcome` section, or both, to return valid results.

## Analyze user login events

This section provides YARA-L query examples for monitoring user authentication activity. Use these patterns to identify successful logins, failed attempts, and potential credential abuse across your data sources.

#### Example: Group by login status

The following YARA-L query counts user logins, grouping them by login status of `"ALLOW"` or `"BLOCK"`:

    //USER_LOGIN by status
    metadata.event_type = "USER_LOGIN"
    $security_result = security_result.action
    $security_result = "BLOCK" OR $security_result = "ALLOW"

    match:
      $security_result

    outcome:
      $event_count = count_distinct(metadata.id)

#### Example: Monitor login trends

The following YARA-L query counts successful user logins over time:

    //successful sign-ins over time
    metadata.event_type = "USER_LOGIN"
    $security_result = security_result.action
    $security_result = "ALLOW"
    $date = timestamp.get_date(metadata.event_timestamp.seconds, "America/Los_Angeles")

    match:
      $security_result, $date

    outcome:
      $event_count = count_distinct(metadata.id)

    order:
      $date desc

#### Example: Track logins by location

The following YARA-L query counts user logins, grouped by countries:

    //user sign-ins by country
    metadata.event_type = "USER_LOGIN"
    $country = principal.location.country_or_region
    $country != ""

    match:
      $country

    outcome:
      $event_count = count_distinct(metadata.id)

    order:
      $event_count desc

## Cases and alerts

Use cases and alerts to monitor operational SOC metrics, including alert categorization, case statuses, and incident resolution trends.

The following templates demonstrate how to query cases and alerts to visualize the health of your incident response lifecycle and monitor SOAR performance.

- **Data source** : `Cases and Alerts`
- **Query prefix** : `case` (fields must be prefixed; for example, `case.priority`)
- **Time interval**: 365 days

### Schema reference

The following schema defines the fields available for monitoring cases and alerts within the platform. This data source provides the operational telemetry required to track incident volume, prioritize response efforts, and evaluate the workload distribution across your security team. Use this schema to build high-level SOC metrics, such as case distribution by status, priority, and assignee.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `case.name` | String | Unique identifier (GUID) for a SOAR case. |
| `case.priority` | Enum | Priority of the case (for example, `PRIORITY_HIGH`). |
| `case.status` | Enum | Current status (for example, `OPEN`, `CLOSED`). |
| `case.stage` | String | Current workflow stage. |
| `case.assignee` | String | User ID or name of the entity assigned to the case. |
| `case.score` | Double | Risk score associated with the case. |
| `case.custom_fields` | Map | User-defined custom fields. Must append data type (for example, `case.custom_fields["field_name"].string_seq.string_vals`). |

### Query examples

The following queries let SOC managers and lead analysts visualize incident response velocity and workload distribution. These examples focus on isolating active incidents, categorizing them by priority to ensure high-risk threats are addressed, and analyzing the overall lifecycle of cases through status distribution. Use these templates to ensure your team is meeting service-level agreements (SLAs) and to identify bottlenecks in the remediation process.

For more information about field descriptions in the following examples, see [Cases and alerts](https://docs.cloud.google.com/chronicle/docs/reference/soar-data-dashboard#cases-and-alerts).

#### Example: Total open incidents

The following example calculates the total number of active, open incidents, providing a baseline metric for active SOC workload:

    case.incident = true
    case.status = "OPENED"

    outcome:
      $Count = count(case.name)

#### Example: Incident priorities distribution

The following example groups all active incidents by their assigned priority level, allowing for a weighted view of current environmental risk:

    case.incident = true

    $Priority = case.priority

    match:
      $Priority

    outcome:
      $Count = count(case.name)

    order:
      $Count desc

#### Example: Case status distribution

The following example provides a comprehensive view of all cases (both incidents and alerts) across every lifecycle phase (for example, `Opened`, `Closed`, `Suspended`):

    $Status = case.status

    match:
      $Status

    outcome:
      $Count = count(case.name)

    order:
      $Count desc

#### Example: Count cases by status

The following YARA-L queries help analyze cases and alert data:

    match:
      case.status

    outcome:
      $count=count(case.name)

#### Example: Count cases tagged as `SUSPICIOUS`

    case.tags.name="SUSPICIOUS"

    outcome:
      $count=count(case.name)

#### Example: Calculate mean time to detect (in minutes)

    $case_create_time = case.create_time.seconds
    $alert_time = case.alerts.metadata.detection_time.seconds

    outcome:
      $avg_time = math.round(window.avg($case_create_time - $alert_time)/60, 2)

#### Example: Filter cases based on custom fields

The following example lists cases where a specific custom field matches a value:

    case.custom_fields["reporter"].string_seq.string_vals = "bob"

    match:
      case.response_platform_info.response_platform_id, case.display_name, case.environment, case.priority

#### Example: Count cases filtered by custom fields

The following example counts cases where a custom field value matches specific criteria:

    $impact = case.custom_fields["business impact"].string_seq.string_vals
    $impact = "high" or $impact = "critical"

    outcome:
      $Case_Count = count(case.name)

#### Example: Multi-condition filtering on custom fields

The following example lists cases that meet multiple conditions, including a custom time-based field and a string field:

    $deadline = timestamp.get_date(case.custom_fields["sla deadline"].time_val.seconds)
    $deadline > "2026-04-25"
    case.custom_fields["business impact"].string_seq.string_vals = "critical"

    match:
      case.response_platform_info.response_platform_id, case.display_name, case.stage, $deadline

#### Example: Group results by custom field values

The following example groups case details by the value of a custom field:

    case.display_name = /^Soma.*/

    match:
      case.custom_fields["reporter"].string_seq.string_vals, case.environment, case.priority

#### Example: Case-insensitive filtering on custom fields

The following example uses the `nocase` modifier to perform a case-insensitive search on a custom field:

    case.custom_fields["reporter"].string_seq.string_vals = "Bob" nocase

    match:
      case.response_platform_info.response_platform_id, case.display_name, case.environment, case.priority

## Case history

Use a case history to track activity trends across the case lifecycle.

The following templates show how to query case history to visualize the lifecycle of security incidents and calculate critical SOC performance metrics like MTTR and MTTA:

- **Data source** : `Case History`
- **Query prefix** : `case_history` (fields must be prefixed; for example, `case_history.case_activity`)
- **Time interval**: 365 days

### Schema reference

The following schema defines the fields available for auditing the chronological actions taken within a SOAR case. Unlike the [cases and alerts schema](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#cases-and-alerts), which shows current state, case history tracks every transition, assignment, and status change over time. Use this schema to perform complex time-series analysis and identify operational bottlenecks within your incident handling process.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `case_history.name` | String | Unique identifier (GUID) for the specific history event. |
| `case_history.case_response_platform_info.case_id` | String | Unique identifier for the parent SOAR case. |
| `case_history.case_activity` | Enum | Type of activity performed (for example, `STAGE_CHANGE`, `ASSIGNEE_CHANGE`, `CREATE_CASE`). |
| `case_history.event_time.seconds` | Timestamp | Epoch timestamp indicating when the activity occurred. |
| `case_history.assignee` | String | Identity of the new assignee after the event. |
| `case_history.stage` | String | New workflow stage after the event. |

### Query examples

The following queries let SOC managers measure the efficiency of the security team using standard industry metrics. These examples focus on handling time (time spent in specific stages), Mean Time to Resolve (MTTA), and Mean Time to Acknowledge (MTTA). By analyzing the transitions between "Create," "Assign," and "Close" activities, these templates provide quantitative data on how quickly the organization responds to and neutralizes threats.

For more information about field descriptions in the following examples, see [Case history](https://docs.cloud.google.com/chronicle/docs/reference/soar-data-dashboard#case-history).

#### Example: Analyze case activity distribution

The following YARA-L query retrieves the case history by activity count:

    match:
      case_history.case_activity

    outcome:
      $count=count_distinct(case_history.name)

#### Example: Handling time by case stage - last 7 days

The following example calculates the duration (in minutes) that cases spend in various workflow stages to identify where delays occur:

    case_history.assignee.soc_roles != ""

    $Case_ID = case_history.case_response_platform_info.case_id
    $Case_Stage = case_history.stage

    match:
      $Case_Stage

    outcome:
      $Handling_Time_Minutes = (max(case_history.event_time.seconds) - min(case_history.event_time.seconds)) / 60

#### Example: MTTR in minutes - last 7 days

The following example shows a multi-stage query that isolates cases that have both `CREATE_CASE` and `CLOSE_CASE` activities to calculate the average time-to-closure across the environment:

    stage stage1 {
    $case_id = case_history.case_response_platform_info.case_id

    match:
      $case_id

    outcome:
       $case_close_time = max(if(case_history.case_activity = "CLOSE_CASE", case_history.event_time.seconds, 0))
      $status = array_distinct(case_history.case_activity)
      $TTC = $case_close_time - min(case_history.event_time.seconds)

    condition:
      arrays.contains($status, "CREATE_CASE") and arrays.contains($status, "CLOSE_CASE")
    }

    outcome:
      $case_count = count($stage1.case_id)
      $MTTC = (math.round(avg($stage1.TTC)/60))
      $log_count desc

#### Example: MTTA in minutes - last 7 days

The following example measures the average duration between the creation of a case and its first assignment to an analyst, reflecting the speed of initial SOC intake:

    stage stage1 {
    $case_id = case_history.case_response_platform_info.case_id

    match:
      $case_id

    outcome:
      $case_assign_time = min(if(case_history.case_activity = "ASSIGNEE_CHANGE", case_history.event_time.seconds, 9999999999999999))
      $status = array_distinct(case_history.case_activity)
      $TTA = $case_assign_time - min(case_history.event_time.seconds)

    condition:
      arrays.contains($status, "CREATE_CASE") and arrays.contains($status, "ASSIGNEE_CHANGE")
    }

    outcome:
      $case_count = count($stage1.case_id)
      $MTTA = (math.round((avg($stage1.TTA)/60)))

#### Example: Analyze case lifecycle and Time to Close (TTC)

Goal: Measure the efficiency of security operations by calculating the average TTC for cases that have been successfully created and closed.

    stage stage1 {
      $case_id = $h.case_history.case_response_platform_info.case_id
      $case_id = $c.case.response_platform_info.response_platform_id
      match:
        $case_id
      outcome:
        $case_close_time = max(if($h.case_history.case_activity = "CLOSE_CASE", $h.case_history.event_time.seconds, 0))
        $status = array_distinct($h.case_history.case_activity)
        $TTC = $case_close_time - min($h.case_history.event_time.seconds)
        $environment = array_distinct($c.case.environment)
        $tags = array_distinct($c.case.tags.name)
      condition:
        arrays.contains($status, "CREATE_CASE") and arrays.contains($status, "CLOSE_CASE")
    }

    outcome:
      $case_count  = count($stage1.case_id)
      $MTTC = avg($stage1.TTC)
      $environment = array_distinct($stage1.environment)
      $tags = array_distinct($stage1.tags)

## Data tables

Data tables are user-defined tables that can be used to enrich event data or filter events based on custom lists (for example, known malicious IPs or critical assets).

### Query examples

The following queries demonstrate how to use Data tables in YARA-L searches to correlate live event data with custom reference lists. These examples cover explicit join syntax for multi-field matching as well as the streamlined `in` clause for efficient filtering across all data sources.

#### Example: Match network traffic against threat intel datatable

Goal: Perform multi-field matching between network events and a threat intelligence datatable to identify high-fidelity matches.

    events:
            %dt_join_test3_table.hostname = $host
            $e.principal.hostname = $host
            %dt_join_test3_table.ips = $ips
            $e.principal.ip = $ips
            $e.principal.investigation.severity_score = $severity
            %dt_join_test3_table.severity = $severity
            $e.principal.port = $port
            %dt_join_test3_table.port = $port
            $e.target.hostname = $sec_hostname
            %dt_join_test3_table.sec_hostnames = $sec_hostname
            $e.principal.url_metadata.last_http_response_code = $bad_code
            %dt_join_test3_table.bad_codes = $bad_code

    match:
            $host over 5m

    condition:
            $e

#### Example: Use the IN clause with data tables

Goal: Filter events based on whether a field value exists in a data table column without using explicit joins. This syntax is supported across all data sources.

    // Filter IoCs where the type is listed in a reference Data Table
    ioc.ioc_type in %ioc_types_table.type
    ioc.ioc_value != ""

    $ioc_value = ioc.ioc_value

    match:
      $ioc_value

    outcome:
      $count = count_distinct(ioc.ioc_value)

## Detections

The following templates demonstrate how to query detection metrics for threat visibility and security performance visualizations:

- **Data Source** : `Detections`
- **Query Prefix** : `detection` (fields must be prefixed; for example, `detection.rule_name`)
- **Time Interval**: 365 days

### Schema reference

The following schema defines the structured format for monitoring security alerts. It's optimized for tracking detection frequency, risk distribution, and rule performance across the environment.

#### Core schema hierarchy

Use this map to understand which layer contains the data you need.

| Layer | Description | Key query paths |
|---|---|---|
| **Collection (Root)** | The top-level container for an alert or investigation. | `detection.id` `detection.type` `detection.created_time` |
| **Detection Details** | Logic-specific metadata (Rules, Severity, Scores). | `detection.detection.rule_name` `detection.detection.severity` |
| **Evidence (Elements)** | The raw UDM events or entities that triggered the alert. | `detection.collection_elements.references.event.metadata.vendor_name` |

#### Fields reference (collection object)

These fields are at the root of the detection object and represent the overall alert container.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `detection.id` | String | Unique identifier for the collection (for example, the Detection ID). |
| `detection.type` | Enum | Origin: `RULE_DETECTION`, `TELEMETRY_ALERT`, `SOAR_ALERT` |
| `detection.id_namespace` | String | Namespace context for the ID. |
| `detection.created_time` | Timestamp | When this collection was generated. |
| `detection.last_updated_time` | Timestamp | When the collection was last modified. |
| `detection.time_window` | Interval | Start and end time of the logs that triggered this match. |
| `detection.collection_elements` | List | Raw UDM events or entities that caused the alert. This is the bridge that connects the alert (collection) back to the raw data (UDM). |
| `detection.detection` | List | **Crucial:** Contains the nested metadata fields (for example, rule name, severity). |
| `detection.detection_time` | Timestamp | Specific moment the event occurred or the rule triggered. |
| `detection.investigation` | Message | Current investigation state (status, categorization). |
| `detection.tags` | List\<String\> | Labels applied to the finding for filtering. |
| `detection.response_platform_info` | Message | Linking information for external SOAR platforms (for example, Siemplify). |
| `detection.case_name` | String | Resource name of the associated case in Google SecOps. |
| `detection.feedback_summary` | Message | The most recent analyst feedback/verdict. |
| `detection.feedback_history` | List | History of all feedback given for this alert. |
| `detection.soar_alert` | Boolean | Indicates if this alert has been pushed to a SOAR. |
| `detection.soar_alert_metadata` | Message | Metadata from the source SIEM/SOAR system. |
| `detection.data_access_scope` | String | RBAC scope that determines who can see this data. |
| `detection.detection_timing_details` | Enum | Indicates if this was a `RETROHUNT` or `REPROCESSING` run. |
| `detection.latency_metrics` | Message | Measurement of ingestion delay for the events in this alert. |
| `detection.rule_run_frequency` | Enum | How often the rule runs: `REALTIME`, `HOURLY`, `DAILY`. |

#### Nested detection metadata (`detection.detection`)

These fields describe the logic of the security threat. Note: Prefix all of the following fields with `detection.detection.` for dashboard and search queries.

| Category | Key Fields (Query Ready: prepend with `detection.detection.`) |
|---|---|
| **Rule Identification** | `rule_id`, `rule_name`, `rule_version`, `rule_type`, `rule_author`, `rule_labels`, `rule_set`, `rule_set_display_name`, `ruleset_category_display_name` |
| **Threat Intelligence** | `threat_name`, `threat_id`, `threat_feed_name`, `threat_id_namespace`, `threat_status`, `threat_verdict`, `threat_collections`, `campaigns`, `reports` |
| **Scoring and Severity** | `severity`, `severity_details`, `confidence`, `confidence_score`, `confidence_details`, `priority`, `priority_details`, `risk_score`, `verdict`, `verdict_info`, `alert_state` |
| **Detection Details** | `about` (entities involved), `category`, `category_details`, `summary`, `description`, `detection_fields`, `outcomes`, `variables`, `analytics_metadata`, `attack_details`, `detection_depth` |
| **Action and Discovery** | `action`, `action_details`, `url_back_to_product`, `first_discovered_time`, `last_discovered_time`, `last_updated_time`, `associations` |

#### Access raw evidence (`collection_elements`)

The `collection_elements` field is a bridge that connects a high-level detection to the raw evidence that triggered it. This field contains a list of references to UDM events and entities.

To access raw log data within a dashboard or query, navigate through the `references.event` node.

| Data Point | Schema Path (query ready) |
|---|---|
| **Vendor Name** | `detection.collection_elements.references.event.metadata.vendor_name` |
| **Product Name** | `detection.collection_elements.references.event.metadata.product_name` |
| **Principal Asset** | `detection.collection_elements.references.event.principal.asset_id` |
| **Target User** | `detection.collection_elements.references.event.target.user.userid` |
| **Source IP** | `detection.collection_elements.references.event.network.ip` |

> [!NOTE]
> **Note:** `collection_elements` is a repeated list (because a single detection can be comprised of multiple events). Depending on your dashboard widget type or search query, you may need to use list-handling functions (like `at()` or `flatten`) to access these values.

### Query examples

The following queries are designed to transform raw Detections data into high-level security dashboards. By targeting the detections data source, these examples encourage security analysts and SOC managers to monitor the threat landscape in real-time.

These queries focus on critical security pillars: threat trends (tracking alert volume over time), top offenders (identifying frequent rule triggers across cloud providers), and IOC analysis (categorizing detections by IoC types). Use these templates to identify emerging attack patterns and ensure high-risk alerts are prioritized for investigation.

#### Example: Alerts over time

The following example tracks cloud-related security threats (specifically those involving secrets or KMS) to visualize how these specific risks trend daily:

    detection.detection.ruleset_category_display_name = "Cloud Threats"
    detection.detection.alert_state = "ALERTING"
    detection.detection.rule_name = /Secrets|Key|KMS/ nocase

    $Date = timestamp.get_date(detection.collection_elements.references.event.metadata.event_timestamp.seconds)
    $Rule_Name = detection.detection.rule_name

    match:
      $Date, $Rule_Name

    outcome:
      $Count = count(detection.id)

    order:
      $Date desc

#### Example: Top 10 detections

The following example provides a breakdown of the most frequent detections across major cloud providers (Google Cloud, Amazon Web Services (`AWS`), Microsoft Azure (`AZURE`)), limited to the top 10 most active rules:

    $log_type = detection.collection_elements.references.event.metadata.log_type
    $log_type = /GCP|AWS|AZURE/
    $rule_name = detection.detection.rule_name
    $rule_name != ""

    match:
      $rule_name

    outcome:
      $event_count = count(detection.id)

    order:
      $event_count desc

    limit:
      10

#### Example: Detections over time by IoC type

The following example categorizes detections by their Indicator of Compromise (IoC) type, letting teams see which types of threats (for example, IP, Domain, Hash) are most prevalent:

    detection.detection.rule_name = /ioc/ nocase

    $Date = timestamp.get_date(detection.collection_elements.references.entity.metadata.event_metadata.event_timestamp.seconds)
    $IOC_Type = detection.collection_elements.references.entity.metadata.entity_type

    match:
      $Date , $IOC_Type

    outcome:
      $Count = count(detection.id)

    order:
      $Count desc

#### Example: Detections by severity over time

The following YARA-L query counts detections, grouped by severity and date:

    //Detection count by severity over time
    $date = timestamp.get_date(detection.created_time.seconds)
    $severity = detection.detection.severity

    match:
      $date, $severity

    outcome:
      $detection_count = count_distinct(detection.id)

    order:
      $date asc

#### Example: Top 10 rule names by detection count

The following YARA-L query retrieves the top 10 rule names, ranked by their detection count (or frequency):

    //top ten rule names by detection count
    $rule_name = detection.detection.rule_name

    match:
      $rule_name

    outcome:
      $count = count_distinct(detection.id)

    order:
      $count desc

    limit:
      10

#### Example: Top 10 IP addresses

The following YARA-L query retrieves the top 10 IP addresses from `principal`, `target` and `source` fields, ranked by their detection count:

    $ip = group(detection.collection_elements.references.event.principal.ip,detection.collection_elements.references.event.target.ip,detection.collection_elements.references.event.src.ip)

    $ip != ""

    match:
      $ip

    outcome:
      $count = count(detection.id)

    order:
      $count desc

    limit:
      10

## Entity Graph

The following templates demonstrate how to query the UDM entity model to visualize asset risk and threat intelligence context:

- **Data source** : `Entity Graph`
- **Query prefix** : `graph` (fields must be prefixed; for example, `graph.metadata.entity_type`)
- **Time interval**: 365 days

### Schema reference

The following schema defines the structured format for entities within the graph. While the Event schema captures point-in-time activity, the Entity schema provides the "state-in-time" context for users, assets, and indicators of compromise (IoCs). This lets developers correlate telemetry with business context.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `graph.metadata.entity_type` | Enum | The type of entity (for example, \`USER\`, \`ASSET\`). |
| `graph.metadata.product_name` | String | Product name that produced the entity information. |
| `graph.entity.user.department` | String | Department associated with a user entity. |
| `graph.entity.asset.hostname` | String | Hostname of an asset entity. |
| `graph.entity.asset.location.name` | String | Physical location or region of the asset. |
| `graph.risk_score.risk_score` | Float | Risk score associated with the entity. |

For a list of additional Entity Graph-related fields, see [UDM field list](https://docs.cloud.google.com/chronicle/docs/reference/udm-field-list).

### Query examples

The following queries use the Entity Graph to identify high-risk assets and track threat intelligence indicators.

#### Example: Top PCI assets by risk

The following example identifies assets within the PCI scope and ranks them by their current risk score:

    graph.metadata.entity_type = "ASSET"
    graph.entity.hostname in %PCI_Assets
    graph.risk_score.risk_window_size.seconds = 86400

    $Hostname = graph.entity.hostname
    $Risk_Score = graph.risk_score.risk_score

    match:
      $Hostname, $Risk_Score

    order:
      $Risk_Score desc

> [!NOTE]
> **Note:** To match the normalized risk score (1-1000) displayed in the **Risk Analytics** dashboard, query `graph.risk_score.normalized_risk_score`. The `graph.risk_score.risk_score` field returns the raw or base score.

#### Example: IoCs with high risk score

The following example aggregates various indicator types (IP, URL, Hash) and calculates the average risk score from threat intelligence feeds:

    $IOC_Type = graph.metadata.entity_type
    $Risk_Score = graph.metadata.threat.risk_score
    $Date = timestamp.get_date(graph.metadata.collected_timestamp.seconds)
    $Hash = group(graph.entity.file.sha256, graph.entity.file.md5)

    $IOC_Value = strings.coalesce(
      if(graph.entity.ip != "", graph.entity.ip, ""),
      if(graph.entity.url != "", graph.entity.url, ""),
      if($Hash != "", $Hash, "")
    )

    $IOC_Value != ""

    match:
      $Date, $IOC_Type, $IOC_Value

    outcome:
      $Total_Risk_Score = math.round(avg($Risk_Score), 2)
      $Count = count(graph.metadata.event_metadata.id)

    order:
      $Total_Risk_Score desc

#### Example: Enrich network events with asset context

Goal: Identify network connections to a specific IP address and enrich the event with the asset ID of the initiating host from the entity graph.

    $e1.principal.hostname = $hostname
    $e1.target.ip = "1.1.1.1"
    $g.graph.entity.hostname = $hostname
    $asset_id = $g.graph.entity.asset_id

    match:
      $hostname over 1h

    outcome:
      $asset_ids = array($asset_id)
      $count = count($e1.metadata.id)

#### Example: Recent ransomware intel sources events

The following example filters for ransomware-related threat intelligence and extracts the associated indicators for dashboard visualization:

    graph.metadata.threat.description = /ransom/ nocase

    $Hash = group(graph.entity.file.sha256, graph.entity.file.md5)

    $IOC_Value = strings.coalesce(
      if(graph.entity.ip != "", graph.entity.ip, ""),
      if(graph.entity.url != "", graph.entity.url, ""),
      if($Hash != "", $Hash, "")
    )

    $IOC_Value != ""

    $IOC_Type = graph.metadata.entity_type
    $Threat = graph.metadata.threat.description
    $Date = timestamp.get_date(graph.metadata.collected_timestamp.seconds)

    match:
      $Date, $Threat, $IOC_Value, $IOC_Type

    outcome:
      $Count = count(graph.metadata.event_metadata.id)

    order:
      $Count desc

## Events

The following templates demonstrate how to query UDM Event fields for dashboard visualizations.

- **Data source** : `Events`
- **Query prefix** : None (fields referenced directly; for example, `metadata.event_type`)
- **Time interval**: 90 days

### Schema reference

The following schema defines the structured format for security and system events used in data processing and analysis. It is designed to be *query ready* , making sure that security analysts and data engineers can efficiently filter, aggregate, and correlate logs across different sources. By standardizing fields, such as timestamps, identities (`principal`), and outcomes (`security_result`), this schema enables consistent visibility into activities like network traffic, process executions, and user authentication.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `metadata.event_type` | Enum | Type of event (for example, `PROCESS_LAUNCH`, `USER_LOGIN`). |
| `metadata.event_timestamp.seconds` | Integer | Epoch timestamp of the event in seconds. |
| `metadata.product_name` | String | Name of the product that generated the log. |
| `metadata.vendor_name` | String | Name of the product vendor. |
| `principal.ip` | String | IP address of the acting entity. |
| `principal.user.userid` | String | User ID of the acting entity. |
| `target.ip` | String | IP address of the target entity. |
| `network.sent_bytes` | Integer | Number of bytes sent. |
| `security_result.action` | Enum | Action taken, such as `BLOCK` or `ALLOW`. |

For a list of UDM fields, see [UDM field list](https://docs.cloud.google.com/chronicle/docs/reference/udm-field-list).

### Query examples

This section shows specific queries designed to power visual dashboards, transforming raw logs into actionable insights regarding application control and user activity.

By leveraging the Events schema, these queries let analysts track execution trends, identify blocked high-risk applications, and monitor authentication patterns across the enterprise in real-time.

#### Example: Application executions over time

The following example tracks the volume of allowed (`allow`) and blocked (`block`) executions across the environment:

    // Selection Criteria
    metadata.product_event_type = /(execution|application) (allow|block)/ nocase or
    security_result.threat_name = /application control/ nocase

    // Logic
    $Date = timestamp.get_timestamp(metadata.event_timestamp.seconds, "%F")

    match:
      $Date

    outcome:
      $Count = count(metadata.id)

#### Example: Top 10 blocked application executions by reason

The following example identifies the specific files that are blocked and the policy reason for the action:

    // Selection Criteria
    (metadata.product_event_type = /(execution|application) block/ nocase or
    security_result.threat_name = /application control/ nocase) and
    security_result.action = "BLOCK"

    // Logic
    $Application = strings.coalesce(about.file.full_path, target.process.file.full_path, additional.fields["fname"])
    $Reason = strings.coalesce(target.resource.attribute.labels["categoryTupleDescription"], security_result.action_details, metadata.product_event_type)

    match:
      $Application, $Reason

    outcome:
      $Count = count(metadata.id)

    order:
      $Count desc

    limit:
      10

#### Example: Top 10 successful user login trends

The following example monitors user login frequency across Workspace activity to detect abnormal patterns:

    // Selection Criteria
    metadata.log_type = "WORKSPACE_ACTIVITY"
    metadata.product_event_type = "LOGIN_SUCCESS"
    principal.user.email_addresses != ""

    // Logic
    $User_Account = principal.user.email_addresses
    $Date = timestamp.get_date(metadata.event_timestamp.seconds)

    match:
      $User_Account, $Date

    outcome:
      $Count = count(metadata.id)

    order:
      $Count desc

    limit:
      10

#### Example: Correlate events across different hosts

Goal: Detect a single host communicating with multiple specific destination IPs within a short timeframe, which may indicate scanning or lateral movement.

    $e1.target.ip = "1.1.1.1"
    $e2.target.ip = "2.2.2.2"
    $e1.principal.ip = $placeholder
    $e2.principal.ip = $placeholder

    match:
      $placeholder over 1h

    outcome:
      $target_ip = arrays.concat(array($e1.target.ip), array($e2.target.ip))

## Ingestion metrics

Use ingestion metrics to monitor the health and volume of data that enters the system.

The following templates demonstrate how to query ingestion metrics for health and performance visualizations:

- **Data Source** : `Ingestion Metrics`
- **Query Prefix** : `ingestion` (fields must be prefixed; for example, `ingestion.log_type`)
- **Time Interval**: 365 days

### Schema reference

The following schema defines the structured format for monitoring log flows. It's optimized for tracking ingestion health, volume, and normalization states across all collection mechanisms. For more information about field descriptions in the following examples, see [Ingestion metrics schema](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-metrics-schema).

| Field name (query ready) | Data type | Description |
|---|---|---|
| `ingestion.log_type` | String | The log source type (for example, `WINDOWS_DNS`). |
| `ingestion.component` | String | TIngestion component (for example, `Forwarder`, `Ingestion API`). |
| `ingestion.collector_id` | String | Unique identifier of the collection mechanism. |
| `ingestion.log_volume` | Float | Volume of logs in bytes. |
| `ingestion.log_count` | Float | Number of logs ingested. |
| `ingestion.drop_count` | Float | Number of logs dropped. |

For additional fields, see [Ingestion metrics schema](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-metrics-schema). Learn more about the [Chronicle API ingestion methods](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-methods) (and legacy [Ingestion API](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-api)), and see the [ingestion metrics schema reference](https://docs.cloud.google.com/chronicle/docs/reference/sample-yaral-for-native-dashboard#ingestion-metrics-schema-reference). For information on migrating from the legacy Ingestion API, see [Migrate from legacy SIEM API to Chronicle API](https://docs.cloud.google.com/chronicle/docs/administration/migrate-from-legacy-api-to-chronicle-api).

### Query examples

The following queries are designed to transform raw ingestion metrics into high-level operational dashboards. By targeting the ingestion data source, these examples encourage platform administrators and data engineers to monitor the health of the entire data pipeline in real-time.

These queries focus on critical operational pillars: *volume tracking* (measure license consumption and throughput), *normalization health* (identify where logs fail to parse or validate), and *component reliability* (confirm the Ingestion API and Forwarders are communicating correctly). Use these templates to identify ingestion bottlenecks and make sure high-value logs are successfully converted into searchable UDM events.

#### Example: Ingestion throughput over time

The following example tracks the total size of logs (in bytes) processed by the [Ingestion API](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-api) over time:

    $Date = timestamp.get_date(ingestion.end_time)

    match:
      $Date

    outcome:
      $Total_Size_Bytes = sum(if(ingestion.component = "Ingestion API", ingestion.log_volume, 0))

#### Example: Ingested events by log type

The following example breaks down the ingestion health, comparing raw volume to normalized success and specific parsing or indexing failures:

    $Log_Type = ingestion.log_type

    match:
      $Log_Type

    outcome:
      $Total_Size_Bytes = sum(if(ingestion.component = "Ingestion API", ingestion.log_volume, 0))
      $Total_Logs = sum(if(ingestion.component = "Ingestion API", ingestion.log_count, 0))
      $Total_Normalized_Events = sum(if(ingestion.component = "Normalizer" AND ingestion.state = "validated", ingestion.event_count, 0))
      $Total_Parsing_Error_Events = sum(if(ingestion.component = "Normalizer" AND ingestion.state = "failed_parsing", ingestion.log_count, 0))
      $Total_Validation_Error_Events = sum(if(ingestion.component = "Normalizer" AND ingestion.state = "failed_validation", ingestion.event_count, 0))
      $Total_Indexing_Error_Events = sum(if(ingestion.component = "Normalizer" AND ingestion.state = "failed_indexing", ingestion.log_count, 0))

    order:
      $Total_Size_Bytes desc

#### Example: Ingestion throughput

The following example calculates the daily ingestion volume in GB, excluding heartbeat data and empty log types:

    ingestion.component = "Ingestion API"
    ingestion.log_type != ""
    ingestion.log_type != "FORWARDER_HEARTBEAT"

    $Date = timestamp.get_date(ingestion.end_time)

    match:
      $Date

    outcome:
      $Throughput_GB = math.round(sum(ingestion.log_volume) / (1000 * 1000 * 1000), 2)

    order:
      $Date desc

#### Example: Aggregate ingestion metrics by log type

The following YARA-L query counts `log`, `event`, and `drop_count`, grouped by `log_type`:

    //log count, event count, and drop count by log type
    ingestion.log_type != ""
    $log_type = ingestion.log_type

    match:
      $log_type

    outcome:
      $log_count = sum(ingestion.log_count)
      $event_count = sum(ingestion.event_count)
      $drop_count = sum(ingestion.drop_count)

    order:
      $log_count desc

For more ingestion metrics examples, see [Ingestion metrics schema](https://docs.cloud.google.com/chronicle/docs/reference/ingestion-metrics-schema#ingestion-metrics-examples).

## IoCs

The following templates demonstrate how to query IoCs to visualize threat intelligence matches and monitor high-risk infrastructure patterns:

- **Data Source** : `IoCs`
- **Query Prefix** : `ioc` (fields must be prefixed; for example, `ioc.ioc_value`)
- **Time Interval**: 365 days

### Schema reference

The following schema defines the fields available for analyzing threat intelligence matches. This data source correlates your environment's telemetry with known malicious indicators, providing visibility into the severity, origin (feed), and type of threats detected. It's essential for quantifying the impact of external threat feeds on your internal ecosystem.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `ioc.ioc_value` | String | Domain, IP, or hash indicator value. |
| `ioc.ioc_type` | String | Type of IOC (for example, `IOC_TYPE_DOMAIN`, `IOC_TYPE_IP`). |
| `ioc.feed_log_type` | String | IOC feed log type (for example, `ET_PRO_IOC`). |
| `ioc.is_global` | Boolean | Determines whether this is a global IOC indicator. |
| `ioc.day_bucket_seconds` | Integer | Specific day bucket when an IOC hit occurred, based on the event's timestamp. |
| `ioc.category` | String | Category or type for this indicator (for example, malware, phishing). |
| `ioc.confidence_score` | Integer | Raw confidence level provided by the original IOC source. |
| `ioc.feed_name` | String | Original feed from which the IOC indicator originated. |
| `ioc.severity` | String | Raw severity level assigned to the indicator. |
| `ioc.ioc_ingest_time` | Timestamp | Timestamp indicating when the IOC was first ingested into the system. |
| `ioc.asset` | String | The asset indicator associated with the match. |
| `ioc.location` | String | The physical location associated with the indicator. |

### Query examples

The following queries allow analysts to prioritize threat hunting efforts by identifying outliers and trends within IOC match data. These examples focus on rare values---which often indicate targeted or sophisticated attacks---indicator distribution by type, and longitudinal trends across different threat categories. Use these templates to identify which threat feeds are providing the most value and which infrastructure categories are seeing increased malicious activity over time.

For more information about field descriptions in the following examples, see [IoC fields](https://docs.cloud.google.com/chronicle/docs/reference/yaral-functions-native-dashboards#ioc_fields).

#### Example: Top 10 rarely seen values

The following example identifies the indicators that appear least frequently in the environment, helping to highlight unique or "low-and-slow" threat actor activity:

    ioc.ioc_value != ""

    $ioc_value = ioc.ioc_value

    match:
      $ioc_value

    outcome:
      $count = count_distinct(ioc.ioc_value)

    order:
      $count

    limit:
      10

#### Example: Top 10 IoCs

The following YARA-L query retrieves the top 10 IOCs, ranked by count:

    ioc.ioc_type = "IOC_TYPE_DOMAIN"
    ioc.ioc_value != ""

    //Top 10 IOCs by count
    $ioc_value = ioc.ioc_value

    match:
      $ioc_value

    outcome:
      $count = count_distinct(ioc.ioc_value)

    order:
      $count desc

    limit:
      10

#### Example: IoC matches over time by category

The following example tracks the volume of indicator matches across different threat categories (for example, Command and Control compared to Adware) to identify shifting threat landscapes:

    ioc.category != ""

    $category = ioc.category
    $ioc_date = timestamp.get_date(ioc.day_bucket_seconds)

    match:
      $ioc_date, $category

    outcome:
      $count = count_distinct(ioc.ioc_value)

#### Example: Top 10 IoC prevalence

The following YARA-L query retrieves the top 10 IoCs, ranked by `count`:

    //Top 10 IOCs by count
    $ioc_value = ioc.ioc_value

    match:
      $ioc_value

    outcome:
      $ioc_count = count(ioc.ioc_value)

    order:
      $ioc_count desc

    limit:
      10

## Playbooks

Use Playbooks to monitor your automated response capabilities with queries designed to identify faulted actions and track real-time playbook performance.

The following templates demonstrate how to query playbooks to visualize the efficiency, success rates, and environmental distribution of your automated response workflows:

- **Data Source** : `Playbooks`
- **Query Prefix** : `playbook` (fields must be prefixed; for example, `playbook.display_name`)
- **Time Interval**: 365 days

### Schema reference

The following schema defines the fields available for monitoring playbook execution and SOAR automation. This data source provides the insights necessary to evaluate the ROI of automation, identify failing workflows, and ensure that response logic is correctly distributed across different organizational environments. Use this schema to track performance metrics like completion percentages and error rates across your automation library.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `playbook.name` | String | Unique identifier (GUID) of the specific playbook run. |
| `playbook.display_name` | String | Human-readable display name of the playbook instance. |
| `playbook.status` | Enum | Execution status of the run (for example, `COMPLETED`, `FAILED`). |
| `playbook.start_time.seconds` | Timestamp | Epoch timestamp that indicates when the playbook execution started. |

### Query examples

The following queries help automation engineers and SOC managers quantify the impact of automation on the incident response lifecycle. These examples focus on efficiency (measuring the rate at which playbooks successfully resolve alerts), reliability (identifying workflows with high error rates), and distribution (analyzing where automation is triggered). Use these templates to optimize your SOAR workflows and reduce the manual burden on security analysts.

The following YARA-L queries provide insights into Playbook executions. For more information about field descriptions in the following examples, see [Playbooks](https://docs.cloud.google.com/chronicle/docs/reference/soar-data-dashboard#playbook).

#### Example: Retrieve percentage of faulted actions

    1=1

    outcome:
       $faulted_action=sum(if(playbook.action.status="FAULTED", 1, 0))
       $total_actions=count(playbook.action.name)
       $percentage=($faulted_action/$total_actions)*100

#### Example: Count running playbooks

    playbook.status="IN_PROGRESS" OR playbook.status="PENDING_FOR_USER"

    outcome:
       $count=count_distinct(playbook.name)

#### Example: Percentage of alerts closed per playbook

The following example calculates the percentage of successful playbook runs that resulted in an alert being automatically closed:

    match:
      playbook.display_name

    outcome:
      $Total_Playbook_Runs = count(playbook.name)
      $Alerts_Closed = sum(if(playbook.status = "COMPLETED" and playbook.action.action = /close/ nocase, 1, 0))
      $Percentage = math.round(($Alerts_Closed / $Total_Playbook_Runs) * 100, 2)

    order:
      $Percentage desc

#### Example: Percentage of error runs

The following example monitors the reliability of your automation by calculating the failure rate across all playbook executions:

    outcome:
      $Total_Playbook_Runs = count(playbook.name)
      $PlaybookError = sum(if(playbook.status = "FAILED", 1, 0))
      $Percentage = math.round(($PlaybookError / $Total_Playbook_Runs) * 100, 2)

#### Example: Automation distribution by environment

The following example breaks down playbook executions by environment and trigger type (automatic compared to manual) to make sure automation coverage is balanced:

    $Automatic = playbook.metadata.automatic
    $Environment = playbook.metadata.environments

    match:
      $Environment, $Automatic

    outcome:
      $Total_playbook_Runs = count(playbook.name)

    order:
      $Total_playbook_Runs desc

## Rules

Rule health and management metrics provide insights into rule performance, authorship trends, and operational status.

The following templates demonstrate how to query rules to visualize the performance, detection volume, and operational status of your custom and system detection logic:

- **Data Source** : `Rules`
- **Query Prefix** : `rules` (fields must be prefixed; for example, `rules.display_name`)

### Time interval: Dashboard time range

In Dashboards, every chart requires a time window. For the rules schema, this window is mapped directly to the rule creation date (`rules.create_time`). As a result, only rules created within the selected time span appear in the dashboard. If a rule was created two years ago but your chart is set to `"Last 365 Days"`, that rule is hidden, even if it's `ENABLED`. Because of this behavior, Dashboards lets you select a time range of 10+ years for rule-based charts. To make sure all active rules are visible, regardless of when they were authored, set your chart's time range to the maximum available limit.

### Permissions

To modify rule schedules, your account must be assigned one of the following roles:

- **Detection Engine Admin** (`roles/chronicle.detectionEngineAdmin`)
- **SecOps Admin** (`roles/chronicle.admin`)

### Schema reference

The following schema defines the fields available for monitoring detection rules. This data source provides the metadata necessary to manage rule lifecycles and evaluate the impact of specific detections on your security posture. Use this schema to identify high-volume rules, manage severity distributions, and audit active rule counts.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `rules.name` | String | Unique rule identifier (`ruleID`). |
| `rules.display_name` | String | Human-readable name of the rule. |
| `rules.rule_text` | String | The rule's logic or conditions in text form. |
| `rules.alerting` | Boolean | Indicates whether rule detections trigger alerts (`true`/`false`). |
| `rules.live_status` | String | Current operational state of the rule, such as `ENABLED` or `DISABLED`. |
| `rules.author` | String | The creator of the rule. |
| `rules.severity` | String | Severity level assigned to the rule (for example, `CRITICAL`, `HIGH`, `LOW`). |
| `rules.metadata` | String/Map | Additional details, such as description, [mitre_attack_tactic](https://attack.mitre.org/tactics/enterprise/), [mitre_attack_technique](https://attack.mitre.org/techniques/enterprise/), and `mitre_attack_url`. |
| `rules.total_detection_count` | Integer | Total detections generated by the rule across its lifetime. |
| `rules.create_time` | Timestamp | Rule creation timestamp in [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) format. |
| `rules.update_time` | Timestamp | Latest rule update timestamp in [google.protobuf.Timestamp](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Timestamp) format. |
| `rules.latest_detection_time` | Timestamp | Timestamp of the most recent rule detection. |
| `rules.earliest_detection_time` | Timestamp | Timestamp of the first rule detection. |
| `rules.archived` | Boolean | Indicates whether the rule is archived (`true`/`false`). |

### Query examples

The following queries help security engineers optimize their detection strategy by surfacing rule activity and identifying "noisy" or highly effective logic. These examples bridge the gap between rule metadata and active detections, letting you rank your top-performing detections and identify which rules contribute most to your alert volume.

#### Example: Top 10 active rules

The following example ranks rules by the number of unique detections they have generated:

    $Rulename = detection.detection.rule_name

    match:
      $Rulename

    outcome:
      $Count = count_distinct(detection.id)

    order:
      $Count desc

    limit:
      10

> [!NOTE]
> **Note:** This query uses detection-specific fields commonly found in curated dashboards to provide an accurate count of active rule occurrences.

#### Example: Rules created per month

The following YARA-L query retrieves the rules created per month:

    $month_wise = timestamp.get_timestamp(rules.create_time.seconds,"%y-%m")

    match:
        $month_wise

    outcome:
        $rule_count = count(rules.name)

#### Example: Identify rule detection count

The following YARA-L query retrieves the rules with detection:

    $rule_name = rules.display_name
    $detection_count = rules.total_detection_count
    $detection_count >0

    match:
       $rule_name, $detection_count

#### Example: Monitor rule status

The following YARA-L query retrieves the rules in `ENABLED` status:

    $status = rules.live_status
    $status = "ENABLED"

    outcome:
     $rule_count = count(rules.name)

#### Example: Analyze rule velocity by author

The following YARA-L query retrieves the rules created `by day` (by `author`):

    $rule_author = rules.author

    match:
     $rule_author by day

    outcome:
     $count_of_rules = count(rules.name)

    order:
       $count_of_rules desc

#### Example: Retrieve rules with `text` and `time` query

The following YARA-L query retrieves the all rules `text` and `time` query:

    $name= rules.name
    $display_name = rules.display_name
    $author = rules.author
    $severity = rules.severity
    $live_status = rules.live_status
    $alerting_status = rules.alerting
    $detection_time = rules.latest_detection_time.seconds
    $latest_version_time = rules.update_time.seconds
    $detection_count = rules.total_detection_count
    $rule_text = rules.rule_text

    match:
      $name, $display_name, $live_status, $alerting_status, $severity, $author, $detection_time, $latest_version_time, $detection_count, $rule_text

    order:
      $detection_count desc

#### Example: Identify non-triggering rules

The following YARA-L query retrieves the non-triggering rules (rules with no (`0`) detections):

    $rule_name = rules.name
    $display_name = rules.display_name
    $detection_time = rules.latest_detection_time.seconds
    $detection_time = 0

    match:
      $rule_name, $display_name

For more information about field descriptions in the following examples, see [Rule fields](https://docs.cloud.google.com/chronicle/docs/reference/yaral-functions-native-dashboards#rule_fields).

## Rule sets

The following templates demonstrate how to query *rule sets* (*curated detections*) to visualize the health, status, and coverage of your detection content.

- **Data Source** : `Rule Sets`
- **Query Prefix** : `ruleset` (fields must be prefixed; for example, `ruleset.ruleset_family`)
- **Time Interval**: 365 days

### Schema reference

The following schema defines the fields used to monitor curated detections. This data source provides visibility into which rule families are active and whether they're configured for broad observation or precise alerting. Use this schema to map detection coverage across different threat families like "Cloud Threats" or "Linux Threats".

| Field name (query ready) | Data type | Description |
|---|---|---|
| `ruleset.ruleset_family` | String | Family name of the rule set. |
| `ruleset.ruleset` | String | Display name of the rule set. |
| `ruleset.broad_live` | String | Status of live broad rules (for example, `ENABLED`, `DISABLED`). |
| `ruleset.broad_alerting` | String | Alerting status of broad rules within the rule set. |
| `ruleset.precise_live` | String | Status of precise rules (for example, `ENABLED`, `DISABLED`). |
| `ruleset.precise_alerting` | String | Alerting status of precise rules within the set. |
| `ruleset.detection_timestamp` | Timestamp | Specific timestamp when a detection event was triggered. |

### Query examples

The following queries let detection engineers audit their security posture by analyzing the deployment of curated detections. These examples focus on deployment health (calculating the percentage of enabled rule sets) and detection coverage, which tracks the most recent activity across different rule types. Use these examples to make sure your detection coverage remains aligned with your organizational threat model, specifically for high-priority families like Cloud Threats.

#### Example: CDIR rulesets enabled

The following example calculates the percentage of rule sets within the `"Cloud Threats"` family that have both `precise` and `broad` live modes enabled:

    ruleset.ruleset_family != ""
    ruleset.ruleset_family = "Cloud Threats"
    ruleset.precise_live = "ENABLED"
    ruleset.broad_live = "ENABLED"

    $rule_name = ruleset.ruleset

    outcome:
      $total_ruleset_count = count_distinct(ruleset.ruleset)
      $ruleset_count = count_distinct(if(ruleset.ruleset_family = "Cloud Threats" and ruleset.precise_live = "ENABLED" and ruleset.broad_live = "ENABLED", ruleset.ruleset, "0"))
      $percentage = $ruleset_count / $total_ruleset_count * 100

#### Example: Detection coverage

The following example lists rule sets in the `"Cloud Threats"` family and ranks them by their detection frequency and the time of their most recent detection:

    $ruleset = ruleset.ruleset
    $precise_live = ruleset.precise_live
    $precise_alerting = ruleset.precise_alerting
    $broad_live = ruleset.broad_live
    $broad_alerting = ruleset.broad_alerting

    ruleset.ruleset_family = "Cloud Threats"
    timestamp.get_timestamp(ruleset.detection_timestamp.seconds) != ""

    match:
      $ruleset, $precise_live, $precise_alerting, $broad_live, $broad_alerting

    outcome:
      $latest_detection = timestamp.get_timestamp(max(ruleset.detection_timestamp.seconds))
      $count = count_distinct(ruleset.detection_timestamp.seconds)

    order:
      $count desc

> [!NOTE]
> **Note:** Curated examples for this data source were limited to two unique queries in the source.

## Triage and Investigation Agent

The following template demonstrates how to query Triage and Investigation Agent
(TIN) data to visualize its investigations, including their outcomes, volume,
and user feedback:

- **Data source** : `TIN`
- **Query prefix** : `gemini_investigation` and `gemini_investigation_feedback` (fields must be prefixed; for example, `gemini_investigation.confidence`)
- **Time interval**: 365 days

### Schema reference

The following schema defines the fields available for monitoring TIN investigations.
Use this data source to track investigation statuses, verdicts, and feedback
to improve investigation quality.

| Field name (query ready) | Data type | Description |
|---|---|---|
| `gemini_investigation.alert_type` | String | Type of alert that triggered the investigation. |
| `gemini_investigation.confidence` | Float | Confidence score (`high` or `low`) of the investigation verdict. |
| `gemini_investigation.end_time` | Timestamp | Time when the investigation was finalized. |
| `gemini_investigation.id` | String | Unique identifier for the investigation. |
| `gemini_investigation.security_token_count` | Integer | Count of security tokens associated with the investigation. |
| `gemini_investigation.start_time` | Timestamp | Time when the investigation was initiated. |
| `gemini_investigation.status` | String | Current status of the investigation. |
| `gemini_investigation.step_id` | String | Identifier for a specific step within an investigation. |
| `gemini_investigation.trigger_type` | String | Initiation method, such as `MANUAL` or `AUTOMATED`. |
| `gemini_investigation.verdict` | String | Final verdict assigned by the agent. |
| `gemini_investigation_feedback.type` | String | Type of user feedback provided (for example, `thumbs_up`, `thumbs_down`). |
| `gemini_investigation_feedback.target` | String | Component targeted by the feedback (for example, `verdict`, `summary`). |

### Query examples

The following examples let you monitor your security posture by analyzing the
deployment and performance of TI Agent investigations.

#### Example: Daily investigation count

The following example creates a sample query for TIN operational activity:

    $investigation_date = timestamp.get_date(gemini_investigation.last_update_time.seconds)

    match:
      $investigation_date by day

    outcome:
      $count = count(gemini_investigation.id)

#### Example: Daily investigation count by alert type

The following example creates a sample query that displays the daily `count` of
investigations, grouped by the specific alert type:

    $investigation_date = timestamp.get_date(gemini_investigation.last_update_time.seconds)

    match:
      $investigation_date,
      gemini_investigation.alert_type

    outcome:
      $count = count_distinct(gemini_investigation.id)

    order:
      $investigation_date asc

#### Example: Verdict feedback ratio

The following example displays a sample query that returns the ratio of positive
to negative feedback specifically for the investigation verdict:

    gemini_investigation_feedback.target = "FEEDBACK_TARGET_VERDICT"

    match:
      gemini_investigation_feedback.type

    outcome:
      $count = count(gemini_investigation_feedback.type)

    order:
      gemini_investigation_feedback.type desc

## Display zero values in timeline charts

To plot empty time intervals as `0` instead of drawing continuous lines between non-zero data points across timeline charts, follow these guidelines:

- Keep timestamps as chronological time objects rather than custom string labels. Formatting timestamps as string labels causes the dashboard to treat data points as discrete categories.
- Use built-in YARA-L granularity constants (for example, `HOUR` or `DAY`) inside the `timestamp.get_timestamp()` function. This lets the dashboard plot continuous timelines and fill inactive intervals with zeros.

## What's next

Learn more about how to use functions to build dashboards using [YARA-L 2.0 functions for Google Security Operations dashboards](https://docs.cloud.google.com/chronicle/docs/reference/yaral-functions-native-dashboards).