# Performance

> How report performance works in Holistics, common ways to optimize, and where to start when something's slow.

Holistics report performance is bound by the slowest of these stages:

1. **Pre-query processing**: parsing, permission checks, query plan
2. **Job queuing**: waiting for an available worker
3. **Query execution**: running on your data warehouse
4. **Result transfer**: moving the result set from your data warehouse to Holistics
5. **Post-query processing**: caching and result assembly
6. **Browser render**: drawing the visualization

For the full breakdown, see [Report Running Mechanism](/docs/performance/report-running-mechanism).

## Common levers

A few high-leverage ways to make things faster, before going deep into diagnosis.

### Optimize the underlying datasets and models
Optimizing datasets and models will help optimize the report's SQL execution (usually the biggest bottleneck). See [Dataset Performance Tips](/docs/datasets/best-practices#performance-tips).

### Reduce the number of data points on a report
Fewer data points means:
- Faster transfer from your data warehouse to Holistics
- Faster transfer from Holistics to the browser
- Faster visualization rendering

Ways to reduce data points:
- Apply [filters](/docs/data-exploration#filtering-data)
- Apply [limits](/docs/data-exploration#limiting-data) (configure default limit in Admin Settings → Visualization → Default Records Limit)
- Limit series on a chart: in Visualization Settings, **Styles → Group small values into "Other"**. See [Line chart example](/docs/charts/line-chart#use-low-cardinality-dimension-in-legend).

### Reduce the number of widgets in a dashboard
Each widget on a dashboard spawns its own report job. If the widgets exceed your job queue capacity, some will block until others finish.

Aim for **10–15 widgets per dashboard**. Use [Drill-Through](/docs/interactions/drill-through) for additional detail without piling on widgets.

### Use caching wisely
Set [cache duration](/docs/performance/data-caching#cache-duration) per the freshness/cost trade-off your dashboards need. Use [Model Persistence](/docs/query-models#model-persistence) for slow queries that don't change often.

### Pre-aggregate with Aggregate Awareness
For frequently-queried slices over large fact tables, [Aggregate Awareness](/docs/aggregate-awareness) lets Holistics route queries to pre-aggregated tables transparently.

### Enable Holistics Canal
[Canal Engine](/docs/performance/canal-engine) speeds up result transfer between your data warehouse and Holistics. Most useful when results are large or your warehouse is far from a Holistics region.

### Optimize your data warehouse
Holistics runs your queries on your warehouse. so the warehouse's processing power and configuration set the ceiling. See [Diagnose data warehouse issues](/docs/performance/troubleshooting#diagnose-data-warehouse-issues) for warehouse-side investigation.

## Diagnosing problems

- **Symptom-based diagnosis**: [Performance Troubleshooting](/docs/performance/troubleshooting) walks through what each report-loading status means and how to fix it.
- **Slow jobs you can't pin down**: [Report Slow-Running Jobs](/docs/jobs/report-slow-jobs): how to file an actionable support request.

If none of this matches what you're seeing, contact [support@holistics.io](mailto:support@holistics.io) with the URL, the slow status, and a screenshot/recording.

## References

- [Report Running Mechanism](/docs/performance/report-running-mechanism)
- [Data Caching](/docs/performance/data-caching)
- [Canal Engine](/docs/performance/canal-engine)
- [Job Queues and Workers](/docs/jobs/queues-and-workers)
- [Job Controls](/docs/jobs/controls)
- [Aggregate Awareness](/docs/aggregate-awareness)
- [Status Page](https://status.holistics.io/)