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

# How to optimize Atoti performance

> How to identify the right Atoti performance strategy based on whether the bottleneck is in the data journey or query journey, covering aggregate providers, partitioning, virtual hierarchies, JVM tuning, aggregate cache, query plan, and query limits.

Performance optimization follows four steps:

* Understand the requirements
* Understand the context
* Understand the problem
* Fine-tune the solution

## 1. Understand the requirements

Clarify what matters most for the project. This ensures that optimization efforts remain focused.

* Faster data loading
* Faster query execution
* Reduced memory usage
* A balanced trade-off constrained by the available hardware

<Frame caption="Performance optimization requires balancing different constraints.">
  <img src="https://mintcdn.com/activeviam/lTzImDUNm0cHRUws/images/atoti-concepts/performance_constraints.png?fit=max&auto=format&n=lTzImDUNm0cHRUws&q=85&s=5a98622754708cf9d9c179c3735941a1" alt="Performance constraints" width="2548" height="1629" data-path="images/atoti-concepts/performance_constraints.png" />
</Frame>

## 2. Understand the context

Every Atoti deployment is different. Troubleshooting starts with gaining full visibility into:

* The underlying data and data sources
* The data model and datastore configuration
* The aggregate providers and how the cube is used

A solid grasp of this context helps identify potential bottlenecks and prevents unnecessary guesswork.

## 3. Understand the problem

Performance issues rarely happen without reason. When performance changes, either suddenly or gradually, investigate what has recently changed:

* new code or configuration updates,
* increased data volume,
* spikes in user activity, or
* unexpectedly large or complex queries.

Identifying the root cause helps address the actual issue instead of only addressing its symptoms.

<Frame caption="Common causes of performance issues.">
  <img src="https://mintcdn.com/activeviam/lTzImDUNm0cHRUws/images/atoti-concepts/performance_causes.png?fit=max&auto=format&n=lTzImDUNm0cHRUws&q=85&s=f69b75fe149b84c036dbd649f5a7874c" alt="Performance causes" width="3785" height="1367" data-path="images/atoti-concepts/performance_causes.png" />
</Frame>

## 4. Fine‑tune the solution

Once the problem is clear, refinements should be made methodically. Atoti tuning is most effective when performed in small, isolated steps:

* Change one parameter or configuration at a time,
* Test the impact immediately,
* Observe the results,
* Repeat as needed.

This disciplined approach avoids cascading issues and makes it easier to understand exactly how each tuning lever affects performance.

## Which strategies can help optimize performance?

The right strategy depends on the type of problem and the context of the project.
Hardware constraints, such as available memory and CPU cores, set the boundaries within which all optimization decisions must operate.

Most strategies involve a tradeoff between loading speed and query speed.
This tradeoff is most visible in two areas covered in the data and query journeys:

* **Aggregate providers**: pre-aggregating data during loading reduces the work required at query time.
  Queries run faster, but loading takes longer.
* **Partitioning**: the partitioning strategy affects both how quickly data is written to the datastore
  and how efficiently queries read it back.

Use the table below to identify potential performance optimization strategies.
First, determine whether the performance bottleneck lies in the data journey (loading and transformation)
or in the query journey (execution and resource usage).

| Strategy                        | What it optimizes                        | When to use                                                                              | For more details read the page |
| ------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------ |
| Column calculators              | Data transformation during ingestion     | When records need enrichment or filtering before loading (Java SDK only)                 | Load data                      |
| Tuple publishers                | Data loading flow                        | When controlling how transformed records are submitted to the datastore (Java SDK only)  | Load data                      |
| Partitioning and NUMA awareness | Loading speed and query performance      | When data volume is large or query patterns are predictable                              | Data journey / Query journey   |
| Virtual hierarchies             | Loading time and memory usage            | When hierarchies have high cardinality and are not used for slicing or ordering          | Virtual hierarchies            |
| JVM tuning                      | Memory allocation and garbage collection | When large datasets or frequent queries cause heap pressure or GC pauses (Java SDK only) | JVM tuning                     |
| Aggregate cache                 | Query execution time                     | When the same queries are repeated frequently                                            | Query journey                  |
| Aggregates providers            | Query execution time                     | When queries are slow and pre-aggregation during loading is acceptable                   | Query journey                  |
| Query plan analysis             | Query execution visibility               | When a specific query is slower than expected                                            | Query journey                  |
| Query limits                    | Resource usage                           | When queries consume excessive time or memory                                            | Query journey                  |