Uncached attributes and entries

Although achieving optimal PingDirectory 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 because of hardware or financial constraints, or in which acceptable performance can be achieved by only caching a portion of the data.

The PingDirectory 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 PingDirectory 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 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 uncached-id2entry database 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.

The 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 uncached-id2entry database 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 value of uncached-id2entry.

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

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 uncached-id2entry 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 result messages, 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 PingDirectory server provides three new advanced properties on the local DB backend to control the caching mode for the uncached-id2entry database:

uncached-id2entry-cache-mode: Specifies the cache mode that is used when accessing the records in the uncached-id2entry database. If the system has enough memory available to fully cache the internal nodes for this database, then cache-keys-only is recommended. Otherwise it is better to select no-caching to minimize the amount of memory required for interacting with the uncached-id2entry database. For more information, see the PingDirectory Server Configuration Reference.
uncached-attribute-criteria: Specifies the criteria used to identify attributes that are written into the uncached-id2entry database, rather than the id2entry database. This property is only used for entries in which the associated uncached-entry-criteria does 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 id2entry database.
uncached-entry-criteria: Specifies the criteria used to identify entries that are written into the uncached-id2entry database, rather than the id2entry database. 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 id2entry database.