Understanding traces vs spans in SQL & BTQL queries

Applies to:

Plan -
Deployment -

Summary

Issue: BTQL query using traces returns spans that don’t match the filter conditions specified in the filter clause. Cause: The traces keyword returns all spans within any trace that contains at least one span matching the filter, not just the matching spans. Resolution: Use spans instead of traces in the from clause to filter individual span records.

Resolution Steps

If you want to filter individual spans

Step 1: Replace `traces` with `spans`

Change the from clause to use spans instead of traces.

from: project_logs('<PROJECT_ID>') spans
| filter: created >= day('XXX') AND created < day('XXX')
and span_attributes.name = "XXX"
select: *
limit: 10

Step 2: Verify results

Results will now only include spans that match all filter conditions.

If you want complete trace context

Keep `traces` in the query - the `traces` keyword is working as designed and returns all spans in traces where at least one span matches your filter.

Technical Details

Behavior difference: `traces` vs `spans`

`traces`

Returns complete traces (all spans within a trace)
Filter conditions select which traces to include
If any span in a trace matches the filter, all spans in that trace are returned

`spans`

Returns individual span records
Filter conditions select which spans to include
Only spans matching all filter conditions are returned

Lint warning: large fields on the `traces` shape

Because traces returns every span in a matching trace, projecting large fields (input, output, expected, or metadata) can pull large payloads from many spans at once. When a query uses the traces shape, projects large fields, and doesn’t filter by a specific root_span_id or id, the query engine raises this warning:

Query projects large fields (input, output, …) on traces shape, which can return large fields from many spans. Use spans or summary shape for bounded previews, or filter by specific root_span_id or id values.

A limit doesn’t resolve this warning on the traces shape, since the limit caps traces, not the spans within them. To preview large fields with a bounded result set, switch to the spans or summary shape, or scope the query to a specific root_span_id or id. See SQL best practices for more.

​Summary

​Resolution Steps

​If you want to filter individual spans

​Step 1: Replace traces with spans

​Step 2: Verify results

​If you want complete trace context

​Keep traces in the query - the traces keyword is working as designed and returns all spans in traces where at least one span matches your filter.

​Technical Details

​Behavior difference: traces vs spans

​traces

​spans

​Lint warning: large fields on the traces shape

Summary

Resolution Steps

If you want to filter individual spans

Step 1: Replace `traces` with `spans`

Step 2: Verify results

If you want complete trace context

Keep `traces` in the query - the `traces` keyword is working as designed and returns all spans in traces where at least one span matches your filter.

Technical Details

Behavior difference: `traces` vs `spans`

`traces`

`spans`

Lint warning: large fields on the `traces` shape