Local DB Indexes are used to store information that makes it possible to locate entries very quickly when processing search operations.
Indexing is performed on a per-attribute level and different types of indexing may be performed for different kinds of attributes, based on how they are expected to be accessed during search operations.
The following components have a direct composition relation to Local DB Indexes:
The properties supported by this managed object are as follows:
| Description | Specifies the name of the attribute for which the index is to be maintained. |
| Default Value | None |
| Allowed Values | The name or OID of an attribute type defined in the server schema. |
| Multi-Valued | No |
| Required | Yes |
| Admin Action Required | None. Modification requires no further action |
| Description | Specifies the maximum number of entries that are allowed to match a given index key before that particular index key is no longer maintained. For indexes with keys expected to match a very large number of entries (e.g., more than 100,000 entries), you should use a composite index instead of an attribute index. Composite indexes exhibit much better performance and scalability than attribute indexes for keys that match a large number of entries. For example, a composite index with a filter pattern of "(givenName=?)" can be used to replace both equality and ordering indexes for the givenName attribute, and can also be used to process substring searches that contain at least a subInitial (i.e., "starts with") component. Similarly, a composite index with a filter pattern of "(cn=*?*)" can be used to replace a substring attribute index for the cn attribute, which may be needed for substring searches that don't include a subInitial component. Also note that you may not need a high index entry limit, even in cases where an index has keys that exceed the limit. The index entry limit is an important setting to help the server provide a good balance between read and write performance, and also to constrain the size of the database. You should generally only set a high index entry limit for indexes with keys that match a large number of entries and that are legitimately needed to provide very fast search results for search requests targeting those keys that can't be processed using other indexes. Infrequent searches that may need to examine a very large number of entries but don't require a very fast response (e.g., for background processes used to generate reports on the data contained in the server) are often better performed as unindexed searches, and overall server performance may improve by choosing a smaller index entry limit for the associated attribute. Having index keys that exceed the index entry limit can be a good thing that is expected in some cases and is not something to avoid at all costs. |
| Default Value | 4000 |
| Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | If any index keys have already reached this limit, indexes must be rebuilt before they will be allowed to use the new limit.
Note that large index entry limit values (e.g., greater than 100,000) should not be used for most attribute indexes because this can lead to performance issues when reading from or writing to the index, as well as potentially causing server responsiveness issues or severely degraded performance when cleaning up the ID set for an exploded index key that has exceeded the index entry limit. If you have a legitimate need to set a high index entry limit for one or more attributes, you should use a composite index for those attributes. Composite indexes do not have the same performance limitations as attribute indexes for keys that match a very large number of entries. For example, a composite index with a filter pattern of "(givenName=?)" can be used to replace both equality and ordering indexes for the givenName attribute, and can also be used to process substring searches that contain at least a subInitial (i.e., "starts with") component. Similarly, a composite index with a filter pattern of "(cn=*?*)" can be used to replace a substring attribute index for the cn attribute, which may be needed for substring searches that don't include a subInitial component. |
| Description | Specifies, for substring indexes, the maximum number of entries that are allowed to match a given index key before that particular index key is no longer maintained. Setting a large limit can dramatically increase the database size on disk and have a big impact on server performance if the indexed attribute is modified frequently. When a very large limit is required, creating a dedicated composite index with an index-filter-pattern of (attr=*?*) will give the best balance between search and update performance. |
| Default Value | The value of the index-entry-limit configuration option will be used. |
| Allowed Values | An integer value. Lower limit is 0. Upper limit is 2147483647 . |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | If this limit is increased, and any substring index keys have already reached the previous limit, then the substring index must be rebuilt to use the new limit. |
| Description | Specifies the type(s) of indexing that should be performed for the associated attribute. For equality, presence, and substring index types, the associated attribute type must have a corresponding matching rule. |
| Default Value | None |
| Allowed Values | equality - This index type is used to improve the efficiency of searches using equality search filters. ordering - This index type is used to improve the efficiency of searches using "greater than or equal to" or "less then or equal to" search filters. presence - This index type is used to improve the efficiency of searches using the presence search filters. substring - This index type is used to improve the efficiency of searches using substring search filters. approximate - This index type is used to improve the efficiency of searches using approximate matching search filters. |
| Multi-Valued | Yes |
| Required | Yes |
| Admin Action Required | If any new index types are added for an attribute, and values for that attribute already exist in the database, the index must be rebuilt before it will be accurate. |
maintain-match-count-for-keys-exceeding-entry-limit (Advanced Property)
| Description | Indicates whether to continue to maintain a count of the number of matching entries for an index key even after that count exceeds the index entry limit. Maintaining a match count for keys that exceed the index entry limit can help provide faster and/or more accurate results for unindexed searches that include the matching entry count request control, but may degrade performance by increasing contention on index keys and increasing the amount of data to be written for write operations involving that index key. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | If the index is updated to maintain a match count after this capability has been disabled for any period of time, then the index must be rebuilt before the count can actually be maintained. |
substring-length (Advanced Property)
| Description | The length of substrings in a substring index. |
| Default Value | 6 |
| Allowed Values | An integer value. Lower limit is 3. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The index must be rebuilt before it will reflect the new value. |
prime-index (Advanced Property)
| Description | If this option is enabled and this index's backend is configured to prime indexes, then this index will be loaded at startup. When using the preload prime option, the cache-mode property of this index can also affect how this index is preloaded. If the cache-mode is set to "cache-keys-only", then only the keys of this index will be preloaded. If the cache-mode is set to "no-caching", the nothing will be preloaded for this index. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
prime-internal-nodes-only (Advanced Property)
| Description | If this option is enabled and this index's backend is configured to prime indexes using the preload method, then only the internal database nodes (i.e., the database keys but not values) should be primed when the backend is initialized. This is equivalent to what is retained with a "cache-keys-only" cache-mode. If the cache-mode parameter is set to "no-caching", then none of the internal nodes for this index will be primed. Note that "internal nodes" refers to the internal structure of the underlying database (i.e., the B-tree and database keys) and not to LDAP entries within the DIT that are not leaf entries. |
| Default Value | false |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Changes will automatically take effect the next time that a prime is initiated. |
equality-index-filter (Advanced Property)
| Description | A search filter that may be used in conjunction with an equality component for the associated attribute type. If an equality index filter is defined, then an additional equality index will be maintained for the associated attribute, but only for entries which match the provided filter. Further, the index will be used only for searches containing an equality component with the associated attribute type ANDed with this filter. |
| Default Value | None |
| Allowed Values | A valid LDAP search filter |
| Multi-Valued | Yes |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
maintain-equality-index-without-filter (Advanced Property)
| Description | Indicates whether to maintain a separate equality index for the associated attribute without any filter, in addition to maintaining an index for each equality index filter that is defined. If this is false, then the attribute will not be indexed for equality by itself but only in conjunction with the defined equality index filters. |
| Default Value | true |
| Allowed Values | true false |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | None. Modification requires no further action |
cache-mode (Advanced Property)
| Description | Specifies the cache mode that should be used when accessing the records in the database for this index. This controls how much database cache memory can be consumed by this index. |
| Default Value | The cache mode specified by the default-cache-mode property in the associated backend will be used. |
| Allowed Values | cache-keys-and-values - The server will keep both the keys and values of this index in the database cache. This offers the best performance, but it also requires the most memory. cache-keys-only - If a cache-mode is set to "cache-keys-only", then only the internal database nodes will be cached, which includes the database keys and matching entry ID lists that contain four or fewer entries. This reduces the memory caching requirements for indexes whose keys match several entries. For these indexes, the typically the steady-state database cache requires about 20% of the memory of a fully cached index. Since the file system is accessed for more uses of this index, the "cache-keys-only" setting should only be used for infrequently used indexes or when the backend is stored on a solid state disk (SSD). For indexes that match mostly unique entries, there is no difference between this setting and "cache-keys-and-values" since the matching ID list can be embedded within the internal database nodes. no-caching - This setting requires the least memory. Only the minimum internal database structure is kept in the database cache. The savings vary based on the type of index, the size of keys, and the number of matched entries for each key, but typically the steady-state database cache requires around 2% of the memory of an environment using the default "cache-keys-and-values" option to fully cache the index. While this requires less memory, it relies more heavily on the disk, and puts more pressure on Java garbage collection. It is only recommended for indexes that are used infrequently. |
| Multi-Valued | No |
| Required | No |
| Admin Action Required | The Local DB Index must be disabled and re-enabled for changes to this setting to take effect. In order for this modification to take effect, the component must be restarted, either by disabling and re-enabling it, or by restarting the server |
To list the configured Local DB Indexes:
dsconfig list-local-db-indexes
[--property {propertyName}] ...
To view the configuration for an existing Local DB Index:
dsconfig get-local-db-index-prop
--index-name {name}
--backend-name {name}
[--tab-delimited]
[--script-friendly]
[--property {propertyName}] ...
To update the configuration for an existing Local DB Index:
dsconfig set-local-db-index-prop
--index-name {name}
--backend-name {name}
(--set|--add|--remove) {propertyName}:{propertyValue}
[(--set|--add|--remove) {propertyName}:{propertyValue}] ...
To create a new Local DB Index:
dsconfig create-local-db-index
--index-name {name}
--backend-name {name}
--set index-type:{propertyValue}
[--set {propertyName}:{propertyValue}] ...
To delete an existing Local DB Index:
dsconfig delete-local-db-index
--index-name {name}
--backend-name {name}