Relational Queries

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 and Custom Dashboards 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.
2. Select Visual Explorer.

Using Custom Dashboards:

1. In the left navigation menu, go to Dashboards, then Custom Dashboards.
2. Select New to create a dashboard.
3. 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 for more details).
2. Go to Select field in the Filter panel.
3. 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.
4. The list of available fields updates automatically with the selected prefix applied.
5. Select a field and assign it a value.
6. Use the Functions panel to add Group By operations (for example, root.Service, Subsystem).
7. 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.

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 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:

parent.Subsystem = "shopping-cart-service"

Group by:

Subsystem

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:

error = true

Group by:

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:

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.