Skip to main content
Version: current [24.2.x]

Pillar 2 - Performance Efficiency

Dremio is a powerful platform that can process large amounts of data. To get the best performance out of your Dremio environment, you should follow these design principles and implementation best practices.

Dimensions of Performance Optimization

When optimizing Dremio clusters for performance, several factors should be considered. Queries submitted to Dremio must be planned by the coordinator before being routed for execution. There is always one master coordinator and, optionally, additional scale-out coordinators that assist with planning JDBC/ODBC queries. The coordinator generates a query plan that can be used to route the query to one of the engines that are part of the cluster.

Some queries can be well-written, and some can consume inordinately high resources from the start. Those queries can be rewritten and optimized on their own without regard to the larger cluster.

Beyond individual queries, we look at the execution environment of executor nodes. Those nodes have individual constraints of memory and CPU. Executors in Dremio are also part of an engine that groups executors together to process queries in parallel across multiple machines. The size of the engine that a query runs on can affect its performance and ability to handle additional queries.


Perform Regular Maintenance

To ensure that your cluster is set up for optimal performance and to handle more data, queries, and workloads, it is necessary to conduct regular maintenance. Regular maintenance will establish a solid baseline from which you can design and optimize.

Scale-out Coordinators

Dremio’s coordinator nodes can be scaled-out with secondary coordinators that will assist in planning a high volume of queries submitted to the cluster.

Optimize for Efficiency

Before you think about scaling out your cluster, it is important to optimize your semantic layer and queries to be as efficient as possible.

Optimize Engines

Dremio provides several ways to enable workload isolation and ensure your queries do not overload the cluster. Multiple engines are used to keep some queries from affecting others, and queues are used to buffer queries from overloading any single engine.

Best Practices

Clean the KV Store

Dremio stores important metadata in a metastore, referred to as the KV store, which is local to the master coordinator node. As data is added and removed in conjunction with the changes that are made in the semantic layer, the KV store can become fragmented and consume significant disk space. To avoid this issue, Dremio recommends cleaning the KV store every six months once it reaches 100 GB in size.

The clean operation will ensure any orphaned metadata entries, orphaned profiles, old jobs, old profiles, and temporary dataset versions are deleted. You can also use the clean command to reindex and compact the data to reduce the fragmentation on disk.

Failure to clean the KV store can slow metadata retrieval, which will affect planning time for queries. For organizations with large semantic layers, this can potentially lead to an exhaustion of disk space and possible corruption of the KV store.

The clean operation requires the Dremio server to be offline, so this action needs to be planned with platform owners and users.

Right-size Scale-out Coordinators

Secondary coordinator nodes can be used to improve query planning concurrency and distribute query planning specifically for ODBC and JDBC client requests. Secondary coordinator nodes do not plan queries that arrive via Dremio’s SQL REST API.

It is common for Dremio to experience a natural ramp-up in workloads as new users and new use cases are added to the cluster. When the volume of queries submitted to Dremio exceeds the number of cores that Dremio has available to plan the queries, queries that cannot be planned immediately start to incur wait time -- time spent waiting in a queue to be planned. Wait time, of course, increases the overall time that it takes for the query to execute and return results.

To alleviate wait time caused by high volumes of queries from ODBC/JDBC clients, it is recommended that you configure secondary coordinators to improve concurrency in query planning and to distribute planning for ODBC/JDBC clients across multiple coordinators.

You should consider adding a secondary coordinator when your JDBC/ODBC queries start to incur small amounts of wait time -- one second of wait time is too long for many organizations. Failing to address this will result in increased query durations as more and more workload is added to Dremio. Wait time for each query is captured in the query history, which is stored in a file called queries.json on the Dremio master coordinator.

Dremio recommends that you monitor wait times for your queries, and if those times are consistently breaching the one-second threshold, you should consider adding another secondary coordinator.


Dremio recommends a maximum of five secondary coordinator nodes in any single cluster.

Design Semantic Layer for Workload Performance

Dremio’s enterprise-scale semantic layer provides a clear boundary between your physically-stored tables and your logical, IT-governed and self-service views. The semantic layer provides data engineers and semantic data modelers the ability to create views based on tables without having to make copies of the physical data.

Since interactive performance for business users is a key capability of the semantic layer, Dremio can leverage physically optimized representations of source data known as data reflections, when appropriate. When queries are made against views that have data reflections enabled, the query optimizer can accelerate a query by utilizing one or more reflections to partially or entirely satisfy that query, rather than processing the raw data in the underlying data source. Queries do not have to be rewritten to take advantage of data reflections -- Dremio's optimizer considers reflection suitability automatically while planning the query.

With Dremio, you can create layers of views that allow you to present data to business consumers in a format they need. At the same time, you can satisfy organizational security requirements without business consumers having to worry about the physical locations from which the data comes, or how the data is physically organized. A layered approach enables you to create sets of re-usable views that can be utilized many times across multiple projects.

Leveraging Dremio’s layering best practices promotes a more performant and low-maintenance solution that can provide agility to development teams and business users, and provide better control over data.

Improve Query Performance

Analyzing query history to determine which queries are performing sub-optimally involves a number of factors. The first and simplest factor to consider is the overall execution time of a query. You should identify the top 10 longest running queries to understand why they are taking so long. Is it taking too long to read data from the source? Are you lacking CPU cycles? Is the query spilling to disk? Was the query queued at the start? Did the query take a long time to plan?

The query history also allows you to focus on planning times. Even though a query might not appear in the top 10 longest running queries, it might still include a high amount of planning time. These queries should be investigated to determine the cause for high planning time, which can be caused by:

  • the complexity of the query
  • an inline metadata refresh due to stale metadata (see Optimize Metadata Refresh Frequency)
  • a high number of reflections being considered, which could mean there are too many reflections defined in the environment (see Remove unused reflections to learn how to identify if there are redundant reflections in your cluster)

At times, query performance may be inconsistent. A query may complete execution in less than 10 seconds in one case, but the same query may require one minute of execution time in another case. Performance inconsistency is a typical sign of resource contention in the cluster, which can happen in high-volume environments or those where too many jobs (user queries, metadata, or reflection) are running at the same time.

It is important to calculate the standard deviation for each set of identical jobs and not bundle everything into a single number. Also, you only want the standard deviation on the execution time, which excludes poolwait time, planning time, and queue time.

For metadata refresh jobs (REFRESH DATASET), if the standard deviation is higher than 50,000, those jobs should be assigned to a dedicated engine. For reflection refresh jobs (REFRESH REFLECTION), if standard deviation is higher than 150,000, those jobs should be assigned to a dedicated engine. If an engine for reflections already exists, it is recommended that you have two engines for reflection refresh jobs -- one for high-cost reflections and one for low-cost reflections.

Metadata and reflection refresh jobs run in the background to ensure they do not affect user queries. User queries invoked by dashboards or other platforms can have SLA requirements (e.g., completion in under 10 seconds). You can take the same approach for user queries, but the scope should be narrowed to queries in the same queue.

If the standard deviation is very high for some queries, review their profiles to make sure they are tuned properly. If the SLA is very strict, then a dedicated engine is required for them.

Review Dremio Profiles to Pinpoint Bottlenecks

Dremio profiles contain considerable detail about how a query was planned, how the phases of execution were constructed, how the query was actually executed, and the decisions that were made about whether or not to use reflections to accelerate the query.

For each phase of the query in the profile, check the phase's start and end times, which will give you your first indication of the phase in which bottlenecks were located. After you identify the phase, you can drill into the operators of that phase to see which operator or which thread within the operator may have been problematic. With this information, you can usually start to understand why a query was performing sub-optimally, and you can start to plan how to improve performance. For example (not exhaustive):

  • High sleep times in queries indicate there is CPU contention, and you should consider increasing the number of executors.
  • High setup times can indicate a "small file" problem, meaning Dremio spends too much time opening and closing files to read the headers.
  • High planning time can be caused by too many reflections or the need for an inline metadata refresh.
  • High queue time can indicate that workload management settings are causing too much throttling in the queues.

Rebalance Workload Management Rules

Since workloads query volumes change over time, Workload Management queue-routing rule settings for query cost thresholds should be re-evaluated and adjusted to rebalance the proportion of queries that flow to each of the cost-based queues.

Statistical quantile analysis can be used on the query history data to determine what the query cost threshold should be between the low-cost and high-cost user query queues in a two-queue setup, or what the threshold should be between the low-cost and medium-cost user query queues and the medium-cost and high-cost user query queues in a three-queue setup.

Ideally, in a two-queue setup, you want to see approximately an 80%/20% split of queries hitting the low/high cost user query queues. In a three-queue setup, you want to see approximately a 75%/15%/10% split of queries hitting the low/medium/high cost user query queues.

Right-size Engines and Executors

You can analyze the query history to determine if you need to change the number of executors in your engines.

When the volume of queries being executed simultaneously by the current set of executor nodes in an engine starts to reach a saturation point, there are a number of key symptoms that Dremio exhibits. Saturation point is typically manifested as increased sleep time during query execution. Sleep time is incurred when a running query needs to wait for available CPU cycles due to all available CPUs being in operation.

Another symptom in Dremio Software is an increased number of Out Of Memory exceptions, even on queries that are not particularly heavy memory consumers. If a query uses a very small amount of memory but needs only a small amount more, if the request for that memory pushes Dremio over its limit, then that small query will be marked as Out Of Memory since it was the one that requested memory and it couldn't be allocated. Seeing these types of Out Of Memory exceptions is an indication that the engine cannot handle the concurrency allowed by the queue settings.

These symptoms can be identified by analyzing the query history, which reports on both sleep time and reasons why queries failed. Failure to address these symptoms can result in increasing query times and an increasing number of queries failing due to Out Of Memory issues. These, in turn, can lead to a bad end-user experience and poor satisfaction.

In a cluster that has multiple engines configured, you can alleviate the issues in both of these circumstances by adding executor nodes to an existing engine or creating a new engine, then altering the Workload Management settings to make use of the engine changes.


Dremio recommends that no engine should exceed 10 executor nodes, assuming 128GB of memory and 16/32 cores per executor.

A good reason for creating a new engine is when a new workload is introduced to Dremio, perhaps by a new department within an organization, and their queries are causing degraded performance in the existing engine setup. Creating a new engine to isolate the new workload, most likely by creating rules to route queries from users in that organization to the new engine, is a useful way of isolating workloads.

Leverage Reflections to Improve Performance

When developing use cases in Dremio’s semantic layer, it is often best to build out the use case iteratively, without any reflections at the start. As you complete iterations, you can run the queries and analyze the data in the query history to deduce which ones are taking the longest to execute and whether there are any common factors between a set of slow queries which are contributing to the performance issues.

For example, assume you have a set of five slow queries that are each derived from a view that contains a join between two relatively large tables. In this situation, you might find that putting a raw reflection on the view that is performing the join helps to speed up all five queries because an Apache Iceberg materialization of the join results will be created, and can be automatically used to accelerate views derived from the join. This allows you to get the query planning and performance benefits of Apache Iceberg, and you can even partition the reflection to accelerate queries for which the underlying data wasn’t initially optimized. This is an important pattern since it means you can leverage a small number of reflections to speed up potentially many workloads.

Raw reflections can be useful in cases where you have large volumes of JSON or CSV data. When this type of data is queried, the entire dataset needs to be processed, which can be inefficient. Adding a raw reflection over the JSON or CSV data allows for an Apache Iceberg representation of that data to be created, and it enables all of those planning and performance benefits that come along with it.

Similar to the JSON/CSV example described above, another use of raw reflections is to simply offload heavy queries from an operational data store. Often, database administrators do not want their operational data stores (e.g., OLTP databases) being overloaded with analytical queries while they are busy processing billions of transactions. In this situation, you can leverage raw reflections to create an Apache Iceberg representation of the operational table. When a query needs the data, it will read the reflection data as opposed to going back to the operational source.

Another important use case that often requires raw reflections is joining on premises data to cloud data. In this case, you will typically find that the retrieval of the on premises data becomes the bottleneck for queries due to the latency in retrieving the data from the source system. Leveraging a raw reflection on the view where the data is joined together can almost always yield significant performance gains.

If you have connected Dremio to client tools and those client tools are issuing different sets of GROUP BY queries against a view, and if the GROUP BY statements are taking too long to process compared to the desired SLAs, you might consider adding an aggregation reflection to the view to satisfy the combinations of dimensions and measures that are being submitted from the client tool.

For further best practices when considering how and where to apply reflections, see Best Practices for Creating Raw and Aggregation Reflections.

Failure to make use of Dremio reflection means you could be missing out on some very significant performance enhancements for some of your poorest performing queries. However, creating too many reflections can also have a negative impact on the system as a whole. The misconception is often that more reflections must be better, but when you consider the overhead in maintaining and refreshing them at intervals, the reflection refreshes can end up consuming valuable resources from your everyday workloads.

Where possible, organize your queries by pattern. Try to create the smallest amount of reflections that you need to service the highest number of your queries. Locating the points in your semantic tree that a lot of queries go through can help you accelerate a larger number of queries. The more reflections you have that may be able to accelerate the same query patterns, the longer the planner will need to evaluate which reflection will be best suited for accelerating the query being planned.

Optimize Metadata Refresh performance

Adding a dedicated metadata refresh engine to your Dremio cluster will ensure that all metadata refresh activities serviced by executors will be isolated from any other workloads. A dedicated engine avoids any problems with metadata refresh workloads taking CPU cycles and memory away from business-critical workloads and ensures they have the best chance of finishing in a timely manner.