Understanding cache storage formats

With earlier versions than ArcGIS 10.0, tile caches were only available in the exploded format, meaning each tile is stored as an individual JPEG or PNG file measuring 256 px by 256 px. The exploded cache folder containing all tiles is, therefore, very large.

To drastically reduce the file size of tile caches, the compactcache format was introduced at 10.0. A compact cache uses .bundle files, which contain up to 16,384 tiles per file. Compact caches are smaller and easier to copy.

When you create or export a cache, you can specify that its storage format be compact or exploded.

How a compact cache works

The compact cache groups many tiles in one large file called a bundle. 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.

In the initial version of the compact cache, which is called compact, the format also comprised separate index files with the extension .bundlx. Having a separate .bundlx file negatively affects performance when the cache is hosted in a network share or cloud store, so a second version of the compact cache (compactv2) was introduced at 10.3. In this version, which is now used by default when a cache is created, the .bundlx file is included in the .bundle file. This halves the number of calls the client must make to the cache, improving performance while consuming and serving caches from a network share or cloud store.

The compactv2 version of the compact cache can only be used by ArcGIS Server 10.3 and later. The format is an open specification.

If you want caches created earlier than 10.3 to leverage the performance improvements of compactv2, 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.

The improved compact cache storage format is not backward 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 Export Map Server Cache tool uses the compact format as its output, and can be used to make a newer cache compatible with an earlier version of ArcGIS Server. See Copying caches if you want to copy a compactv2 cache to an ArcGIS Server site running an earlier version.

Work with compact caches

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.

Update a compact cache

When you update tiles in a compact cache, the entire bundle is not re-created. Instead, a finer-grained area of 4096x4096 pixels (no antialiasing) or 2048x2048 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.

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 in releases earlier than ArcGIS Server 10.0.