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

# Query timeout requires timestamp filter

export const plans_0 = "Starter, Pro, Enterprise"

export const deployments_0 = "Braintrust-hosted, Self-hosted"

export const data_plane_version_0 = undefined

export const use_case_0 = "Use case - SQL queries on project_logs() with large datasets"

<Note>
  **Applies to:**

  * Plan - {plans_0}
  * Deployment - {deployments_0}
  * {data_plane_version_0}
  * {use_case_0}
</Note>

## Summary

**Issue:** SQL queries using `project_logs()` time out when scanning large datasets without timestamp constraints, even with other filters applied.

**Cause:** Without timestamp filters, queries can scan the entire project history regardless of other `WHERE` conditions.

**Resolution:** Add a range filter on `created`, `_xact_id`, `_pagination_key`, or scope the query to a specific `root_span_id` or `id` to limit the scan range.

<Note>
  The SQL sandbox proactively warns you about missing range filters before you run the query so you don't need to wait for a timeout to discover the issue.
</Note>

## Resolution Steps

### Add a range filter to your query

#### Step 1: Add a range filter constraint

Add a `created`, `_xact_id`, or `_pagination_key` filter to your `WHERE` clause, or scope the query to a specific `root_span_id` or `id`.

```sql theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
SELECT *
FROM project_logs('proj_12345678-1234-1234-1234-123456789012')
WHERE
  created > now() - interval '7 days' AND
  metadata.session_id = 'sess_12345678-1234-1234-1234-123456789012' AND
  span_attributes.name = 'Model Call'
LIMIT 100

```

#### Step 2: Adjust time range as needed

Modify the interval based on your investigation needs: `'1 day'`, `'30 days'`, etc.

### Best practices for project\_logs queries

#### Always include range filters

This is a required best practice for acceptable query performance, not an optional optimization. Accepted range filters include:

* `created` — filter by timestamp (most common)
* `_xact_id` — filter by transaction ID range
* `_pagination_key` — filter by pagination key range
* Scope to a specific `root_span_id` or `id`

#### Start with narrow time ranges

Begin with shorter intervals (e.g., `'1 day'`) and expand only if necessary.

#### Use specific date ranges for known timeframes

For specific investigations, use explicit date boundaries.

```text theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
WHERE created BETWEEN '2024-01-01' AND '2024-01-31'

```