# Distributed Plancache > **📝 Note**: This is a Preview feature. The Distributed PlanCache (DPC) is a third layer of the plancache that supplements the [in-memory plancache and the on-disk persistent plancache (PPC)](https://docs.singlestore.com/cloud/query-data/advanced-query-topics/code-generation/#UUID-0a745a7a-c630-4066-7532-d3ded280d626.md). The DPC allows cluster nodes to share compiled plans. Nodes can skip query optimization, [code generation](https://docs.singlestore.com/cloud/query-data/advanced-query-topics/code-generation.md), and the LLVM compilation process if the plan has been compiled in a different node in the cluster. Thus, the load on the CPU is reduced and the first-time performance of queries that have been compiled on other nodes is improved. The DPC improves performance in the following scenarios: * **Fast scaling**: The DPC triggers plan synchronization during a node's reprovisioning phase. During reprovisioning, recently used query plans are downloaded to nodes’ PPCs. * **Clusters with multiple aggregator nodes**: Aggregators periodically sync the most recently used plans from other aggregators. ## Overview When the DPC is enabled, plans are synchronized automatically between nodes. That is, child aggregators and leaf nodes automatically download plans from the DPC into their local PPC. Once a plan is downloaded, the node can use that plan and avoid query optimization, code generation, and plan compilation in many cases. Similar to how the PPC functions, a plan downloaded to the DPC is usable except when: * A variable affecting the plan has changed in the node. * A table in a query has changed significantly (for example, the number of rows in the table has changed by a factor of two times or more) since the plan was generated. In addition to downloading plans from the DPC, nodes also upload plans to the DPC to make those plans available to other nodes. Similarly, plans can be deleted from the DPC to indicate to other nodes that those plans can be deleted. DPC operations do not interfere with regular cluster operations. While the DPC may consume CPU, memory, and network resources, all operations happen in the background and do not interfere with regular query execution. The DPC operates on a best-effort basis and does not guarantee that plan compilation will not occur on a new node. ## Remarks * DPC requires that the cluster have [Unlimited Storage](https://docs.singlestore.com/cloud/manage-data/#combining-unlimited-and-local-storage-databases.md) enabled. DPC utilizes unlimited storage to store plancache files. * DPC only stores plans generated during `MBC`, `LLVM`, and `INTERPRET_FIRST` interpreter modes. * Plan synchronization is not supported on the Master Aggregator. ## Enable and Manage the Distributed Plancache ## Enable the Distributed Plancache The `enable_distributed_plancache` engine variable controls the DPC. Use the following command to verify the DPC is enabled. ```sql SELECT @@enable_distributed_plancache; ``` ```output +--------------------------------+ | @@enable_distributed_plancache | +--------------------------------+ | 1 | +--------------------------------+ ``` ## Manage the Distributed Plancache When the DPC is enabled, nodes automatically download, upload, and delete plans from the DPC. Nodes download plans from the DPC to their local PPC when the cluster scales, is rebalanced, or a new node is added to the cluster. Nodes delete plans from the DPC when those plans are explicitly deleted from their local PPC with [DROP … FROM PLANCACHE](https://docs.singlestore.com/cloud/reference/sql-reference/data-definition-language-ddl/drop-from-plancache.md). The download, upload, delete, and synchronization operations occur in the background and are managed by the DPC task queue. ## Aggregator Synchronization Child aggregators can be configured to automatically synchronize their local PPCs with the DPC. This process is called aggregator synchronization and is useful for clusters with multiple aggregators. When `enable_periodic_distributed_plancache_agg_sync` is set to `ON`, at the interval specified by `distributed_plancache_agg_sync_s`, each aggregator performs an aggregator synchronization operation and downloads the most recently used `distributed_plancache_max_download_plans` query plans from the DPC. ## Synchronous DPC Lookup With synchronous DPC lookup, query execution looks to the DPC before starting query optimization, and [Code Generation](https://docs.singlestore.com/cloud/query-data/advanced-query-topics/code-generation.md). When a plan exists in the DPC, this synchronous lookup process is typically faster than local compilation, optimization, and code generation for large, complex queries. Syncronous DPC lookup is enabled when `enable_synchronous_dpc_lookup` is set to `ON` on aggregator nodes. ## Engine Variables The following engine variables are used to manage the DPC: | Name | Description | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- | | `distributed_plancache_worker_threads` | Specifies the number of threads used to process tasks in the task queue for the DPC. | | `distributed_plancache_max_download_plans` | Specifies the maximum number of plans downloaded in a synchronization task for the DPC. | | `distributed_plancache_agg_sync_s` | Specifies the interval between aggregators' periodic synchronizations for the DPC. | | `enable_periodic_distributed_plancache_agg_sync` | Specifies if aggregators periodically synchronize their local PPC with the DPC. | | `enable_synchronous_dpc_lookup` | A session variable that specifies that nodes look for a plan in the DPC when a plan is not found in the node's local PPC. | Refer to [List of Engine Variables](https://docs.singlestore.com/cloud/reference/configuration-reference/engine-variables/list-of-engine-variables.md) for default values. ## Observe Distributed Plancache Statistics Connect to a node and use the [SHOW DISTRIBUTED\_PLANCACHE STATUS](https://docs.singlestore.com/cloud/reference/sql-reference/show-commands/show-distributed-plancache-status.md) command to observe statistics about the DPC on a specific node, as follows. ```sql SHOW DISTRIBUTED_PLANCACHE STATUS; ``` ```output +-------------------------------------------------------+-------+ | Stat | Value | +-------------------------------------------------------+-------+ | Successful Downloads Since Startup | 128 | | Skipped Downloads Since Startup | 110 | | Failed Downloads Since Startup | 0 | | Plans Uploaded Since Startup | 2 | | Plans Deleted Since Startup | 0 | | DB Synchronization Since Startup | 1 | | Successful Downloads From Periodic Sync Since Startup | 12 | | Skipped Downloads From Periodic Sync Since Startup | 107 | | Failed Downloads From Periodic Sync Since Startup | 0 | | Periodic Query Plan Syncs Since Startup | 1 | | Distributed Plancache Plans Used Since Startup | 90 | | Currently Queued Populate Download Tasks | 0 | | Currently Queued Download Tasks | 0 | | Currently Queued Upload Tasks | 0 | | Currently Queued Delete Tasks | 0 | | Avg Plan Download Latency (ms) | 13 | | Avg Plan Upload Latency (ms) | 38 | | Avg Plan Delete Latency (ms) | 0 | | Avg Duration For DB Plan Synchronization (ms) | 1710 | +-------------------------------------------------------+-------+ ``` **Note**: Failed Downloads indicate that the node tried to download a plan file from the DPC, but failed to do so typically because the plan did not exist in the DPC. Skipped Downloads indicate that the node tried to download the plan from the DPC, but the plan already existed in the local PPC. Use the following commands to view the number of tasks in the DPC task queue. ```sql SHOW STATUS LIKE 'Queued_DPC_Uploads'; SHOW STATUS LIKE 'Queued_DPC_Downloads'; SHOW STATUS LIKE 'Queued_DPC_PopulateDownloads'; SHOW STATUS LIKE 'Queued_DPC_Deletes'; ``` If the values of these metrics increase significantly and the number of compilations rises due to slow plan synchronization, SingleStore recommends considering an increase in the DPC worker thread pool size (`distributed_plancache_worker_threads`). ## Use DPC with a New Workspace Use the following steps to use the DPC for a specific database in a new workspace. Complete steps 1, 2, and 3 before creating the new workspace. 1. Enable the distributed plancache. This command enables the distributed plancache for the entire [workspace group](https://docs.singlestore.com/cloud/getting-started-with-singlestore-helios/workspace-architecture.md). ```sql SET GLOBAL enable_distributed_plancache = ON; ``` 2. The plans that need to be downloaded to the new workspace must exist in the DPC, that is, those plans must be compiled locally in any of the nodes after `enable_distributed_plancache` was turned on. 1. This can be achieved by either removing and recompiling that plan, or letting the cluster run for a while so the nodes naturally recompile the plan over time. 3. Set `distributed_plancache_max_download_plans` to the number of plans that is expected for the database (default 1000). ```sql SET distributed_plancache_max_download_plans = ; ``` 4. Create a new workspace, attach the database to the new workspace. 5. The plans automatically sync after step 4 has been completed. 6. If more plans need to be synchronized explicitly or if the value set in step 3 was too small, run [\_SYNC\_PLANS](https://docs.singlestore.com/cloud/reference/sql-reference/code-generation-functions/sync-plans.md) `` on the aggregator node to download the most recently used query plans for that database again (plans that already exist in the DPC are skipped). *** Modified at: May 29, 2026 Source: [/cloud/user-and-workspace-administration/workspace-health-and-performance/distributed-plancache/](https://docs.singlestore.com/cloud/user-and-workspace-administration/workspace-health-and-performance/distributed-plancache/) (An index of the documentation is available at /llms.txt)