Although achieving optimal Directory Server performance requires that the entire data set be fully cached, there can be deployments in which fully caching the data set is not possible due to hardware or financial constraints, or in which acceptable performance can be achieved by only caching a portion of the data.
The Directory Server already provides support for controlling caching on a per-database basis, such as to cache only certain indexes and system databases, but these features might not provide sufficient control over how memory is used, particularly with regard to which entries are included in the cache, and they do not provide any degree of control over caching only a portion of attributes.
To better address the needs of environments that require partial caching, the Directory Server provides two new options: the ability to exclude certain entries
from the cache, and the ability to exclude certain attributes from the cache. The Directory Server uses an
uncached-id2entry database container,
which is similar to the
id2entry database that maps an entry's unique
identifier and its encoded representation. The
contains either complete or partial representations of entries that are intended to receive
less memory for caching. For example, if an entry has a large attribute and the system has
hardware constraints on memory, then you can configure the system to not cache this
particular attribute or entry. This functionality is only available for the local DB
backend, which uses the Berkeley DB Java Edition database.
uncached-id2entry database can be included in the set of databases to
prime, but if priming is to be performed, it only includes internal nodes and not leaf
nodes. For example, the internal nodes of the
are included in the preload if the
prime-all-indexes option is set to
"true," or if the
system-index-to-prime-internal-nodes-only option has a
Backup and Restore
There are no special considerations for backup and restore with regard to uncached entries and attributes. Backup successfully saves your database contents, including uncached entries and attributes. Because of the way the server deals with changes to uncached entry and uncached attribute configuration, there is no problem with restoring a backup that was taken with a different uncached entry configuration than is currently in place for the server. Any entries encoded in a manner that is inconsistent with the current uncached entry or uncached attribute configuration are properly re-encoded whenever they are updated, or whenever the re-encode entries task is invoked.
Replication does not propagate information about which portions of entries might have been cached or uncached, nor does it require that different replicas have the same uncached attribute or uncached entry configuration.
LDIF Import and Export
When LDIF content is imported into the server, the uncached attribute and uncached entry
configuration is used to determine on a per-entry basis whether some or all of the
content for that entry should be written into the
database. The determination is based on the current configuration and is completely
independent of and unaware of the configuration that might have been in place when the
LDIF data was initially exported. Neither the LDIF import nor export tools provide any
options that specifically target only cached or only uncached content, but these tools
do provide the ability to include or exclude entries using search filters or to include
or exclude specific attributes.
Server Access Log
Server access log messages can include
uncachedDataAcessed=true in the
result message for any operation in which it was necessary to access uncached data in
the course of processing the associated request. For add, delete, modify, or modify DN
uncachedDataAcessed=true indicates that at least a
portion of the new or updated entry was written into the
uncached-id2entry database or that at least a portion of the updated
entry was formerly contained in the
uncached-id2entry database. For
compare result messages, it indicates that at least a portion of the target entry was
contained in the
uncached-id2entry database and that data from the
uncached portion of the entry was required to evaluate the assertion. For search result
messages, it indicates that one or more of the entries evaluated as potential matches
contained uncached data and that data from the uncached portion of at least one entry
was needed in determining what data should be returned to the client.
Uncached Entry and Attribute Properties
The Directory Server provides three new advanced properties on the local DB
backend to control the caching mode for the
- Specifies the cache mode that is used when accessing the records in the
uncached-id2entrydatabase. If the system has enough memory available to fully cache the internal nodes for this database, then
cache-keys-onlyis recommended. Otherwise it is better to select
no-cachingto minimize the amount of memory required for interacting with the
uncached-id2entrydatabase. For more information, see the PingDirectory Server Configuration Reference.
- Specifies the criteria used to identify attributes that are written into the
uncached-id2entrydatabase, rather than the
id2entrydatabase. This property is only used for entries in which the associated
uncached-entry-criteriadoes not indicate that the entire entry should be uncached. The property applies to all entry writes, including add, soft delete, modify, and modify DN operations, as well as LDIF import and re-encode processing. Any changes to the property take effect immediately for writes occurring after the change is made. If no value is specified, then all attributes are written into the
- Specifies the criteria used to identify entries that are written into the
uncached-id2entrydatabase, rather than the
id2entrydatabase. The property applies to all entry writes, including add, soft delete, modify, and modify DN operations, as well as LDIF import and re-encode processing. Any changes to the property take effect immediately for writes occurring after the change is made. If no value is specified, then all entries are written into the