## Overview

Relational queries in Coralogix's Query Builder empower you to analyze and understand the intricate relationships within your distributed traces.

Modern applications often consist of complex, interconnected services. Understanding how these services interact is crucial for performance optimization and issue resolution. With relational queries, you can query spans based on their relationships within a trace, providing deeper insights into your application's behavior.

## How to build a Relational query

Use Coralogix's Query Builder in both [**Visual Explorer**](https://coralogix.com/docs/user-guides/monitoring-and-insights/visual-explorer/index.md) and [**Custom Dashboards**](https://coralogix.com/docs/user-guides/custom-dashboards/getting-started/index.md) to query spans based on their relationships within a trace. Create more targeted and insightful queries by applying relational prefixes (`root.`, `parent.`, `any.`) to existing fields.

### Open a view that supports Relational queries

Using **Visual Explorer**:

1. In the left navigation menu, go to **Explore**.
1. Select **Visual Explorer**.

Using **Custom Dashboards**:

1. In the left navigation menu, go to **Dashboards**, then **Custom Dashboards**.
1. Select **New** to create a dashboard.
1. Select a widget type (Table, Bar Chart, Pie Chart, etc.) to visualize your data.

### Build a Relational query

1. Select **Spans** and select the **Monitoring** option (see [limitations](#limitations) for more details).
1. Go to **Select field** in the **Filter** panel.
1. Select or type a relational prefix (`root.`, `parent.`, or `any.`) from the dropdown. For example, select the `root.` prefix to filter based on the root span—the first span in each trace.
1. The list of available fields updates automatically with the selected prefix applied.
1. Select a field and assign it a value.
1. Use the **Functions** panel to add **Group By** operations (for example, `root.Service`, `Subsystem`).
1. Use the chart selector to select a visualization such as Table, Bar, or Pie.

The image below shows the Relational Query builder in the Coralogix UI.

### Understanding relational prefixes

The following relational prefixes are available:

- **`root.`**: Identifies spans with root spans that match specific attributes.
- **`parent.`**: Pinpoints spans with direct parent spans that match specific attributes.
- **`any.`**: Targets all spans in a trace if any span within that trace matches the specified attributes.

Note

These prefixes are exclusive to spans in the Query Builder and are supported in the Monitoring [TCO pipeline](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/#tco-priority-levels-explained).

Take the following example:

A user visits an online store and clicks on a product to view its details. This simple action triggers a request that flows through multiple service. Each step in this process is captured as a span, and the relationships between these spans help you analyze system behavior and performance.

| Relationship type | Description                                                                                    | Example scenario                                                                                                                                                | Query example                                           |
| ----------------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **Root span**     | The `root` span represents the first step in the trace—the initial user request.               | A user selects a product, triggering the frontend-service to load the product page. This is the root span that starts the entire trace.                         | `root.user.id = "73cb6c82-3279-467e-b262-198b33d8964b"` |
| **Parent span**   | A `parent` span is the direct trigger for another span—the immediate upstream action.          | In a payment flow, the payment service calls downstream systems (fraud detection, notification service). The payment service span is the parent of those spans. | `parent.Service = "paymentservice"`                     |
| **Any span**      | Matches spans where any span in the trace meets a given condition, no matter where it appears. | You want to find all product page loads where `any` span in the trace (for example, an async logger or external API) encountered an error.                      | `any.error = true`                                      |

## Relational query performance optimization

To enhance the efficiency of your queries using relational field prefixes in Coralogix, consider the following best practices:

**Use multiple filters**

- **Combine filters**: Combine relational prefix usage with nonrelational field filters.
- **Ensure selectivity**: Use filters that significantly reduce the dataset size.
- **Fallback filtering**: If needed, apply a filter on a common field like `application.name` to limit the query scope.

**Understand prefix performance**

Different relational field prefixes have varying performance characteristics:

- **`root.` prefix**: Most performant; inherently filters to root spans.
- **`any.` prefixes**: Moderately performant; Match the first span meeting criteria, reducing the dataset.
- **`parent.` prefix**: Potentially less performant; Requires identifying each span’s parent.

**Limit time ranges**

Shorter time ranges reduce data volume, leading to faster query execution.

## Converting queries to DataPrime

- Selecting **"Convert to DataPrime"** generates the raw query format.
- Switching back to the **Builder** view clears any existing query (one-way conversion).

## Limitations

- **Monitoring pipeline**: This feature can be used in the [monitoring pipeline](https://coralogix.com/docs/user-guides/account-management/tco-optimizer/#tco-priority-levels-explained) only. Queries using relational filters in the Monitoring pipeline automatically fetches data from both the Monitoring and Compliance pipelines, ensuring broader coverage for complex analysis.

- **Query constraints**: Up to two different relationships can be included in a query, across both filters and group by functions. For example, it is not possible to filter by `root.` and `any.` and also run an aggregation on `parent.`.

  Note

  There is no limit on the amount of filters per relationship type.

- **Query limits**: Broad queries may reach system limits, resulting in incomplete results or timeouts. Narrowing the time range or adding more filters can help mitigate this.

- **Field value options:** Only field values that exist within the selected time range appears as selectable filter options.

## Use cases

### Use case 1: Identify downstream services called by a given service

**Scenario**

You want to analyze which downstream services a specific microservice calls. This is useful when investigating latency, dependency bottlenecks, or unexpected service-to-service interactions.

**Goal**

See all spans whose parent belongs to a specific service (for example, `shopping-cart-service`) and visualize the distribution of downstream calls.

**How to build the query**

Filter:

```text
parent.Subsystem = "shopping-cart-service"
```

Group by:

```text
Subsystem
```

Note

In Coralogix, `Subsystem` refers to the service or applications that send logs, metrics, and traces. For more information, refer to the [Application and Subsystem Names](https://coralogix.com/docs/user-guides/account-management/account-settings/application-and-subsystem-names/index.md) document.

**What you learn**

- Which services receive calls from `shopping-cart-service`.
- How frequently each downstream dependency is invoked.
- Whether unexpected or rarely-used services appear in the call chain.

**Example use case**

A spike in latency appears in the checkout flow. Using this query, you identify that `shopping-cart-service` is suddenly calling `inventory-service` far more often than usual—indicating a potential bug in request batching logic. The image below shows this use case in the Coralogix UI.

**Tip**

Combine `parent.` filters with `any.` to detect indirect dependencies. For example, you can identify cases where a service triggers downstream work that, in turn, calls other internal services—helping you understand the dependencies.

### Use case 2: Identify which root services generate the most errors

**Scenario**

The system is experiencing a rise in errors, but you don’t know which service initiated the request flows that contain them.

**Goal**

Group all erroring spans by the root service of their trace to understand where problematic user flows begin.

**How to build the query**

Filter:

```text
error = true
```

Group by:

```text
root.Subsystem
```

**What you learn**

- Which incoming user journeys or top-level services generate the highest concentration of errors.
- Whether the problem originates in a specific API gateway, UI entry point, or microservice boundary.
- A clear source map of problematic traces.

**Example use case**

Most errors originate from traces whose root is `payment-service`, even though the errors appear later in downstream services. This helps you focus your investigation on the initial request flow rather than isolated spans. The image below shows this use case in the Coralogix UI.

**Tip**

Use `root.` filters with tight time ranges (5–15 minutes) to detect sudden regressions tied to specific entry points—especially useful during deployments or incident response.

### Use case 3: Detect complex trace behavior using combined any + root relationships

**Scenario**

You want to investigate traces where:

- The root of the trace belongs to `notification-service`.
- Somewhere anywhere in the trace, a span from `template-service` occurs.
- You are specifically interested in spans from `data-prime-api`.

This helps you isolate cross-service behavior where issues only arise under specific upstream conditions.

**Goal**

Pinpoint complex, multi-service interactions that might indicate cascading failures or cross-team dependency issues.

**How to build the query**

Filters:

```text
Subsystem        = data-prime-api
any.Subsystem    = template-service
root.Subsystem   = notification-service
```

**What you learn**

- How a trace behaves when it starts at `notification-service` and involves additional services further down the execution path.
- Whether the downstream service `data-prime-api` is impacted only when a specific upstream service (like `template-service`) appears in the trace.
- How to surface unexpected or complex service interactions that occur only when certain combinations of root and internal services appear together.
- How relational filters (`root.`, `any.`, direct filters) can be combined to isolate specific trace conditions that traditional span-level filters cannot detect.

**Example use case**

Only traces that start with `notification-service` and include `template-service` show elevated latency or atypical behavior in `data-prime-api` spans. This relational query isolates a cross-service dependency issue that is impossible to detect using nonrelational filters alone. The image below shows this use case in the Coralogix UI.

**Tip**

Combine `root.` + `any.` filters to see hidden cross-service patterns. This is especially useful for:

- identifying cascading failures
- testing rollout impact of new upstream features
- validating assumptions about dependency chains

## Support

**Need help?**

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to reach out to us via our in-app chat or by sending us an email at [support@coralogix.com](mailto:support@coralogix.com).