Working with filtered indexes

The PingDirectory server filtered index is useful when client search requests consisting of a compound & filter with individual components matching a large number of entries, potentially greater than the index entry limit, have an intersection of a relatively small number of entries.

About this task

Filtered indexing is primarily useful for cases in which clients frequently issue searches with & filters that meet the following criteria:

The & filter itself matches a small number of entries, but each of the individual components can match a large number of entries.
The filter has a dynamic component that does change, and that dynamic component always uses the same attribute.
The filter has a static component that does not change.
The filter must be narrowed to a base distinguished name (DN) for data structures with many branches or if indexed attribute values appear in a large number of entries.

For an example, consider the following use case process. A database contains several thousand company profiles and each company profile is represented by many entries. The (objectClass=company) filter matches a small set of entries per company and can exceed the index entry limit because there are many companies. Also, the (companyDomain=example.com) filter matches many of the entries for the company with domain example.com and can also result in an unindexed search. The more narrow filter (&(objectClass=company)(companyDomain=example.com)) also results in an unindexed search but only matches a small number of entries. The filtered index makes it possible to index this compound filter by defining an equality index on the companyDomain attribute with a static filter of (objectClass=company) in the equality-index-filter property of the index.

When configuring a filtered index, define the following properties.

Filtered Index Properties and their descriptions
Filtered Index Properties	Description
`equality-index-filter`	Specifies a search filter that can 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 is maintained for the associated attribute, but only for entries that match the provided filter. The index is used only for searches containing an equality component with the associated attribute type used with this filter.
`maintain-equality-index-without-filter`	Specifies 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 does not indexed for equality by itself but only in conjunction with the defined equality index filters.

Steps

Define the equality-index-filter filter index property.

Define the maintain-equality-index-without-filter filter index property.

Maintain the filtered index independently from the equality filter for that attribute. Use the filtered index only for searches containing the equality component with the associated attribute type used with this filter. When configuring a filtered index, be aware of the equality-index-filter and maintain-equality-index-without-filter properties of the index.

Result:

The searches are configured and built with the rebuild-index tool or import-ldif tool.

This example shows the result of searches built with filters based on the use case process described above with the following index.

(&(objectClass=company)(companyDomain=example.com))
(&(objectClass=company)(|(companyDomain=example.com)(companyDomain=example.org)))
(&(companyDomain=example.com)(objectClass=company))
(&(companyDomain=example.com)(&(objectClass=company)))
(&(companyDomain=example.com)(objectClass=company)(something=else))
(&(companyDomain=example.com)(&(objectClass=company)(something=else)))
(|(&(objectClass=company)(companyDomain=example.com))(&(objectClass=company)(companyDomain=example.org)))

Creating a filtered index

Steps

To create a filtered index, use the dsconfig tool.

The following command creates an equality index on the companyDomain attribute and maintains an index for the equality filter defined "(objectclass=company)".

Example:

$ bin/dsconfig create-local-db-index --backend-name "userRoot" \
  --index-name companyDomain --set maintain-equality-index-without-filter:true \
  --set index-type:equality --set equality-index-filter:"(objectclass=company)"

After you have created the index, rebuild the indexes.
1. Stop the PingDirectory server using bin/stop-server.
2. Run the rebuild-index tool.
  
  Example:
  $ bin/rebuild-index --baseDN dc=example,dc=com --index companyDomain
Start the PingDirectory server using bin/start-server.