Skip To Content

Inside the compact cache storage format

The compact cache storage format allows you to group tiles in large files rather than storing the tiles as individual files. Advantages of storing tiles in groups include the following:

  • Caches are easier to copy because the number of files is reduced.
  • The total size on disk of the cache is reduced.
  • Tiles are generally created more quickly because disk I/O is reduced during tile creation.
  • Scalability is improved when creating tiles with multiple-machine deployments, because of reduced network traffic.

How a compact cache works

The compact cache groups many tiles together in one large file called a bundle. A bundle contains up to 16,384 tiles. The result is a cache with dozens or hundreds of files, instead of thousands or millions. If you look at a compact cache on disk, you can see the bundle files with the .bundle extension. You'll also see some corresponding index files with the extension .bundlx.

While the cache is being created, you may see temporary .lock and .done files in the cache folders. The .lock files allow ArcGIS Server to keep track of which bundles are in the process of being created; the presence of a .lock file doesn't mean that the bundle is inaccessible to clients. Similarly, the .done file allows ArcGIS Server to keep track of which bundles have been created. All the .lock and .done files should go away when the caching job has finished.

It's possible to have a small cache with just one bundle at each level. More common is that you have a bundle boundary crossing some portion of the geography, so you get multiple bundles in a level (although the bundles might not contain the full 16,000 tiles if the geography is small). Large caches encompass many bundles.

The bundle boundaries are determined by the tiling scheme origin and are not adjustable. For reference, at the neighborhood/street level scale of 1:4096, a full bundle covers about the area of a midsize county in the eastern United States.

How updates occur on a compact cache

When you update tiles in a compact cache, the entire bundle is not re-created. Instead, a finer-grained area of 4096 x 4096 pixels (no antialiasing) or 2048 x 2048 pixels (antialiasing) is updated. In ArcGIS documentation, this unit of area is sometimes referred to as a supertile.

Getting tiles from the bundle

ArcGIS clients, including the web APIs, can read the bundle files produced by the compact cache format. Web clients issue calls to the ArcGIS Server site for the specific level, row, and column of the tile. ArcGIS Server receives the request and returns the appropriate tile from the bundle.

The internal architecture of the bundle is not publicly documented by Esri. If you've coded your own logic to pull tiles out of a virtual directory, you should continue to use the exploded format, which stores each tile as a single file and was the only option prior to ArcGIS 10.

Updating your compact cache to leverage performance improvements

The compact cache storage format was improved at ArcGIS 10.3 to increase performance when consuming cached map and image services. Improvements also reduced the number of files created in the cache directory. This was achieved by including the tile index information (.bundlx files) inside the .bundle files.

New compact caches created with ArcGIS Server or a later release will automatically leverage the performance improvements. After you upgrade to 10.3 or later versions, services with compact caches generated in earlier versions will continue to work. You can continue to maintain these caches using the server cache tools.

If you want caches created prior to 10.3 to leverage the performance improvements, you'll need to upgrade the cache using the Upgrade Map Server Cache Storage Format tool. Upgrading the cache does not create new tiles; instead, the files are reorganized to be compliant with the improved format. To learn how to use the tool, access the tool's help from the Server Toolbox in ArcMap.


The Upgrade Map Server Cache Storage Format tool is not available in ArcGIS Pro. Instead, use ArcMap or Python installed with ArcGIS Server.

The improved compact cache storage format is not backwards compatible with earlier versions of ArcGIS. For example, a compact cache created or upgraded using version 10.3 or later cannot be transferred and consumed in an earlier version of the software. The improved compact cache storage format is always expected to be associated with a service.

Also note that the Export Map Server Cache tool still uses the previous compact cache storage format and does not include the performance improvements noted above.