> ## Documentation Index
> Fetch the complete documentation index at: https://docs.braintrust.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding traces vs spans in SQL & BTQL queries

> [!NOTE]
>
> **Applies to:**
>
> * Plan - Any
> * Deployment - Braintrust-hosted
> *
> * Use case - BTQL queries on \`project\_logs\` with span-level filtering

## 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`.

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
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](https://docs.braintrust.dev/reference/sql/best-practices.md#project-only-the-fields-you-need) for more.

## Related documentation

For the full model of what a filter matches on each query shape, see [How filtering works](https://docs.braintrust.dev/reference/sql/filtering.md#what-a-filter-matches).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.