Appendix A - OpenLDAP: Indexing Entries

olcDbIndex (index)

The index directive of slapd.conf is only effective on initial load of the directory (using ldapadd). If indexes are subsequently changed the directory needs to be re-indexed using slapindex (caution: depending of the version must stop slapd first).

In OLC (cn=config) the attribute used is olcDbIndex which can only appear in an olcDatabase={0}config entry. Additionally re-indexing is done in real time so any change to an attribute immediately triggers an indexing change (slapindex is not required). However, it is not clear using OLC (cn=config) when re-indexing is completed - there is no visible sign to indicate completion.

Format:

# OLC (cn=config) form
olcDbIndex: attrlist | default indices

# slapd.conf form
index attrlist | default indices

# indices = [pres [,approx] [,eq] [,sub] [,special]]

The olcDbIndex/index attribute/directive defines what indexes will be maintained by OpenLDAP. Any number of index parameters may be included. If an attribute does not appear in an index directive it can still be used in a search filter - but if it occurs frequently it will hurt performance - once in a lifetime is not too bad!

attrlist may be either a single attribute or a comma separated list.

The optional parameter default stores the supplied indices and uses them on any subsequent index parameter that does does not have an indices entry. The default value must be defined before any olcDbIndex/index which does not have a indices value. A subsequent default will be used for index parameters following the new default.

pres should be used if use searches of the form 'objectclass=person' or 'attribute=mail' will be used.

approx MUST be used if use searches of the form 'sn~=person' (a 'sounds-like' search) will be used.

eq should be used if searches of the form 'sn=smith' will be used i.e no wildcards are included (uses the EQUALITY rule only).

sub should be used if use searches of the form 'sn=sm*' i.e wildcards are included (uses the SUBSTR rule). This rule may be enhanced by a using subinitial (optimised for 'sn=*s'), subany (optimised for 'sn=*n*') or subfinal (optimised for 'sn=th*'). One or more sub parameters may be included.

special may be either nolang or nosubtypes which are related to subtypes.

Careful attention to what indexes are maintained based on the application requirements will significantly affect directory read performance - conversely there is no point in indexing an attribute if no searches ever access it. If all the searches use EQUALITY rules only then there is no point in indexing for sub. Indexes (indeces) consume memory (more indexes = more memory) and write or modify operations will take longer due to index updates.

Examples:

# simple use of the default value
# OLC (cn=config) form
olcDbIndex: default pres,eq
olcDbIndex: cn,sn,uid

# slapd.conf form
index default pres,eq
index cn,sn,uid

# defines presence and equality indexes for 
# attributes cn, sn and uid
# exactly the same as the three index directives below
index cn pres,eq
index sn pres,eq
index uid pres,eq

index cn eq,sub,subinitial
# creates indexes for attribute cn (commonname)
# EQUALITY, SUBSTR searches and further optimises
# for sc=a* type searches

index sn eq,approx,sub
# creates indexes for sn (surname) on
# EQUALITY and SUBSTR searches
# NOTE: The approx index is a waste of time because
#       there is no ORDERING rule for sn approx is present
#       only to illustrate the parameter exists

index mail pres,eq,sub
# creates indexes for attribute mail on
# presence, EQUALITY and SUBSTR

index objectclass eq
# optimises searches of form objectclass=person

See also Performance chapter for a further review of performance.

Problems, comments, suggestions, corrections (including broken links) or something to add? Please take the time from a busy life to 'mail us' (at top of screen), the webmaster (below) or info-support at zytrax. You will have a warm inner glow for the rest of the day.