Configuring Result Cache Settings

Result cache settings can be configured at three levels:

• At the server level
• At the project level
• At the individual report/document level

Changes to any of the caching settings are in effect only after Intelligence Server restarts.

Result Cache Settings at the Server Level

You can configure the following caching settings in the Intelligence Server Configuration Editor, in the Server Definition (Advanced) category. Each is described below.

You can also configure these settings using the Command Manager script, Alter_Server_Config_Outline.otl, located at C:\Program Files (x86)\MicroStrategy\Command Manager\Outlines\Cache_Outlines.

Backup Frequency (Minutes)

When a result cache is created, the cache is initially stored in memory on Intelligence Server. Caches are backed up to disk as specified by the backup frequency setting.

You can specify the cache backup frequency in the Backup frequency (minutes) box under the Server Definition: Advanced subcategory in the Intelligence Server Configuration Editor.

If you specify a backup frequency of 0 (zero), result caches are saved to disk as soon as they are created. If you specify a backup frequency of 10 (minutes), the result caches are backed up from memory to disk ten minutes after they are created.

In a clustered environment, MicroStrategy recommends that you set the backup frequency to 0 (zero) to ensure that History List messages are synchronized correctly.

Backing up caches from memory to disk more frequently than necessary can drain resources.

This setting also defines when Intelligent Cubes are saved to secondary storage, as described in Storing Intelligent Cubes in Secondary Storage.

Cache Lookup Cleanup Frequency (Sec)

The Cache lookup cleanup frequency (sec) setting determines how frequently the CacheLkUp.idx file is cleaned up. This file stores cache matching information and can become significant in size, especially when a large number of caches include a large number of prompts. The cleanup process reduces the amount of memory that the file consumes and the time that it takes to back up the lookup table to disk.

The default value for this setting is 0 (zero), which means that the cleanup takes place only at server shutdown. You may change this value to another based on your needs, but make sure that it does not negatively affect your system performance. MicroStrategy recommends cleaning the cache lookup at least daily but not more frequently than every half hour.

Result Cache Settings at the Project Level

You can configure caching settings in the Project Configuration Editor, in the Result Caches category. Each is described below.

To locate these settings, right-click the project and select Project Configuration. Then, in the Project Configuration Editor, expand Caching, and then select Result Caches.

You can also configure these settings using Command Manager scripts located at C:\Program Files (x86)\MicroStrategy\Command Manager\Outlines\Cache_Outlines.

Enable Report Server Caching

Result caches can be created or used for a project only if the Enable report server caching check box is selected in the Project Configuration Editor in the Caching: Result Caches: Creation category.

If this option is disabled, all the other options in the Result Caches: Creation and Result Caches: Maintenance categories are grayed out, except for Purge Now. By default, report server caching is enabled. For more information on when report caching is used, see Result Caches.

Enable Document Output Caching in Selected Formats

Document caches can be created or used for a project only if the Enable document output caching in selected formats check box is selected in the Project Configuration Editor in the Caching: Result Caches: Creation category. Document caches are created for documents that are executed in the selected output formats. You can select all or any of the following: PDF, Excel, HTML, and XML/Flash/HTML5.

Document caches are created or used only when a document is executed from MicroStrategy Web. They are not created or used in Developer.

Enable Prompted Report and Document Caching

Enabled by default, the Enable caching for prompted reports and documents setting controls whether prompted reports and documents are cached. In an environment where the majority of reports are prompted and each prompt is likely to receive a different answer each time it is used, the probability of matching an existing cache is low. In this case, caching these report datasets do not provide significant benefits; therefore you may want to disable this setting.

To disable this setting, clear its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Record Prompt Answers for Cache Monitoring

If you Enable caching for prompted reports and documents (see above), you can also Record prompt answers for cache monitoring. This causes all prompt answers to be listed in the Cache Monitor when browsing the result caches. You can then invalidate specific caches based on prompt answers, either from the Cache Monitor or with a custom Command Manager script.

This option is disabled by default. To enable it, select its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Enable Non-Prompted Report and Document Caching

If you Enable caching for non-prompted reports and documents, reports and documents without any prompts are cached.

This option is enabled by default. To disable it, clear its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Enable XML Caching for Reports

If you Enable XML caching for reports, reports executed from MicroStrategy Web create XML caches in addition to any Matching or History caches they may create. For information about XML caches, see Types of Result Caches.

This option is enabled by default. To disable it, clear its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Create Caches per User

If the Create caches per user setting is enabled, different users cannot share the same result cache. Enable this setting only in situations where security issues (such as database-level Security Views) require users to have their own cache files. For more information, see Cache Matching Algorithm.

Instead of enabling this setting, it may be more efficient to disable caching and instead use the History List. For information about the History List, see Saving Report Results: History List.

This option is disabled by default. To enable it, select its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Create Caches Per Database Login

Select the Create caches per database login option if database authentication is used. This means that users who execute their reports using different database login IDs cannot use the same cache. For more information, see Cache Matching Algorithm.

This option is disabled by default. To enable it, select its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Create Caches Per Database Connection

Select the Create caches per database connection option if connection mapping is used. For more information, see Cache Matching Algorithm.

This option is disabled by default. To enable it, select its check box in the Project Configuration Editor under the Caching: Result Caches: Creation category.

Cache File Directory

The Cache file directory, in the Project Configuration Editor under the Caching: Result Caches: Storage category, specifies where all the cache-related files are stored. By default these files are stored in the Intelligence Server installation directory, in the \Caches\<Server definition name> subfolder.

In a non-clustered environment, report caches are typically stored on the same machine that is running Intelligence Server.

In a clustered environment, there are two options:

• Local caching: Each node hosts its own cache file directory that needs to be shared as "ClusterCache" so that other nodes can access it. ClusterCache is the share name Intelligence Server looks for on other nodes to retrieve caches.
• Centralized caching: All nodes have the cache file directory set to the same network location, \\<machine name>\<shared directory name>. For example, \\My_File_Server\My_Cache_Directory.

Make sure this cache directory is writable from the network account under which Intelligence Server is running. Each Intelligence Server creates its own subdirectory.

For more information about which configuration may be best in clustered environments, see Configure Caches in a Cluster.

Cache Encryption Level on Disk

The Cache encryption level on disk drop-down list controls the strength of the encryption on result caches. Encrypting caches increases security, but may slow down the system.

By default the caches that are saved to disk are not encrypted. You can change the encryption level in the Project Configuration Editor under the Caching: Result Caches: Storage category.

Maximum RAM Usage

The Maximum RAM usage settings, in the Project Configuration Editor under the Caching: Result Caches: Storage category, control the amount of memory that result caches consume on Intelligence Server. When this setting is about to be exceeded, the least recently used caches are automatically unloaded to disk.

If the machine experiences problems because of high memory use, you may want to reduce the Maximum RAM usage for the result caches. You need to find a good balance between allowing sufficient memory for report caches and freeing up memory for other uses on the machine. The default value is 250 megabytes for reports and datasets, and 256 megabytes for formatted documents. The maximum value for each of these is 65536 megabytes, or 64 gigabytes.

MicroStrategy recommends that you initially set this value to 10% of the system RAM if it is a dedicated Intelligence Server machine, that is, if no other processes are running on it. This setting depends on the following factors:

• The size of the largest report cache.

  This setting should be at least as large as the largest report in the project that you want to cache. If the amount of RAM available is not large enough for the largest report cache, that cache will not be used and the report will always execute against the warehouse. For example, if the largest report you want to be cached in memory is 20 MB, the maximum RAM usage needs to be at least 20 MB.

• The average size and number of cache files.
• The amount of memory on the Intelligence Server machine.
• The amount of memory used while the system is at maximum capacity.

You should monitor the system's performance when you change the Maximum RAM usage setting. In general, it should not be more than 30% of the machine's total memory.

For more information about when report caches are moved in and out of memory, see Location of Result Caches.

Maximum Number of Caches

The Maximum number of caches settings, in the Project Configuration Editor under the Caching: Result Caches: Storage category, limit the number of result caches, including Matching caches, History caches, Matching-History caches, and XML caches, allowed in the project at one time. The default values are 10,000 datasets, and 100,000 formatted documents.

This setting depends on the following factors:

• The number of users and the number of History List messages they keep.
• The number of report caches and their average size.
• The amount of hard disk space available in the cache directory.

RAM Swap Multiplier

If the Intelligence Server memory that has been allocated for caches becomes full, it must swap caches from memory to disk. The RAM swap multiplier setting, in the Project Configuration Editor under the Caching: Result Caches: Storage category, controls how much memory is swapped to disk, relative to the size of the cache being swapped into memory. For example, if the RAM swap multiplier setting is 2 and the requested cache is 80 kilobytes, 160 kilobytes are swapped from memory to disk.

If the cache memory is full and several concurrent reports are trying to swap from disk, the swap attempts can fail and re-execute those reports. This counteracts any gain in efficiency due to caching. In this case, increasing the RAM swap multiplier setting provides additional free memory into which those caches can be swapped.

The default value for this setting is 2.

Maximum RAM for Cache Index %

This setting determines what percentage of the amount of memory specified in the Maximum RAM usage limits (see Maximum RAM Usage) can be used for result cache lookup tables. If your reports and documents contain many prompt answers, the cache lookup table may reach this limit. At this point, Intelligence Server no longer creates new caches. To continue creating new caches, you must either remove existing caches to free up memory for the cache lookup table, or increase this limit.

The default value for this parameter is 100%, and the values can range from 10% to 100%.

You can change this setting in the Project Configuration Editor under the Caching: Result Caches: Storage category.

Load Caches on Startup

If report caching is enabled and the Load caches on startup setting is enabled, when Intelligence Server starts up, it loads report caches from disk into memory until it reaches the Maximum RAM usage limit (see Maximum RAM Usage). If the Load caches on startup setting is disabled, it loads report caches only when requested by users.

Load caches on startup is enabled by default. To disable it, in the Project Configuration Editor under the Caching: Result Caches: Storage category, clear the Load caches on startup check box.

For large projects, loading caches on startup can take a long time so you have the option to set the loading of caches on demand only. However, if caches are not loaded in advance, there will be a small additional delay in response time when they are hit. Therefore, you need to decide which is best for your set of user and system requirements.

Never Expire Caches

The Never expire caches setting, in the Project Configuration Editor under the Caching: Result Caches: Maintenance category, causes caches to never automatically expire. MicroStrategy recommends selecting this check box, instead of using time-based result cache expiration. For more information, see Managing Result Caches.

Cache Duration (Hours)

All caches that have existed for longer than the Cache duration (Hours) are automatically expired. This duration is set to 24 hours by default. You can change the duration in the Project Configuration Editor under the Caching: Result Caches: Maintenance category.

As mentioned earlier, MicroStrategy recommends against using time-based result cache expiration. For more information, see Managing Result Caches.

Cache Expiration and Dynamic Dates

By default, caches for reports based on filters that use dynamic dates always expire at midnight of the last day in the dynamic date filter. This behavior occurs even if the Cache Duration (see above) is set to zero.

For example, a report has a filter based on the dynamic date "Today." If this report is executed on Monday, the cache for this report expires at midnight on Monday. This is because a user who executes the report on Tuesday expects to see data from Tuesday, not the cached data from Monday. For more information on dynamic date filters, see the Filters section in the Advanced Reporting Help.

To change this behavior, in the Project Configuration Editor under the Caching: Result Caches: Maintenance category, select the Do Not Apply Automatic Expiration Logic for reports containing dynamic dates check box. When this setting is enabled, report caches with dynamic dates expire in the same way as other report caches do, according to the Cache duration setting.

Cache Usage Defaults for Subscriptions

By default, if a cache is present for a subscribed report or document, the report or document uses the cache instead of re-executing the report or document. If no cache is present, one is created when the report or document is executed. For more information about subscriptions, see Scheduling Reports and Documents: Subscriptions.

When you create a subscription, you can force the report or document to re-execute against the warehouse even if a cache is present. You can also prevent the subscription from creating a new cache.

To change the default behavior for new subscriptions, use the following check boxes in the Project Configuration Editor, in the Caching: Subscription Execution category.

• To cause new History List and Mobile subscriptions to execute against the warehouse by default, select the Re-run History List and Mobile subscriptions against the warehouse check box.
• To cause new email, file, and print subscriptions to execute against the warehouse by default, select the Re-run file, email, and print subscriptions against the warehouse check box.
• To prevent new subscriptions of all types from creating or updating caches by default, select the Do not create or update matching caches check box.