Understanding traces vs spans in SQL queries

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.

Applicable To

Plans: Free, Pro, Enterprise

Deployments: Braintrust Hosted, Hybrid

Use case: BTQL queries on project_logs with span-level filtering

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

Internal Links

• Slack thread: Support ticket regarding BTQL filter application