Chapter 2. Maintaining the indexes of a specific database
Each database in Directory Server has its own index. You can create, update, and delete indexes using the dsconf
utility or the web console.
2.1. The different index types
Directory Server stores the indexes of each indexed attribute in a separate database file in the instance’s database directory. For example, the indexes of the sn
attribute are stored in the /var/lib/dirsrv/slapd-instance_name/db/database_name/sn.db
file. Each index file can contain multiple index types if Directory Server maintains different indexes for an attribute.
Directory Server supports the following index types:
-
The presence index (
pres
) is a list of the entries that contain a particular attribute. For example, use this type when clients frequently perform searches, such asattribute=mail
. -
The equality index (
eq
) improves searches for entries containing a specific attribute value. For example, an equality index on thecn
attribute enables faster searches forcn=first_name last_name
. -
The approximate index (
approx
) enables efficient approximate or sounds-like searches. For example, searches forcn~=first_name last_name
,cn~=first_name
, orcn~=first_nam
(note the misspelling) would return an entrycn=first_name X last_name
. Note that the metaphone phonetic algorithm in Directory Server supports only US-ASCII letters. Therefore, use approximate indexing only with English values. -
The substring index (
sub
) is a costly index to maintain, but it enables efficient searching against substrings within entries. Substring indexes are limited to a minimum of three characters for each entry. For example, searches fortelephoneNumber=*555*
return all entries in the directory with a value that contains555
in thetelephoneNumber
attribute. - International index speeds up searches for information in international directories. The process for creating an international index is similar to the process for creating regular indexes, except that it applies a matching rule by associating an object identifier (OID) with the attributes to be indexed.
2.2. Balancing the benefits of indexing
Before you create new indexes, balance the benefits of maintaining indexes against the costs:
- Approximate indexes are not efficient for attributes commonly containing numbers, such as phone numbers.
- Substring indexes do not work for binary attributes.
- Avoid equality indexes on attributes that contain big values, such as an image.
- Maintaining indexes for attributes that are not commonly used in searches increases the overhead without improving the search performance.
- Attributes that are not indexed can still be used in search requests, although the search performance can be degraded significantly, depending on the type of search.
Indexes can become very time-consuming. For example, if Directory Server receives an add operation, the server examines the indexing attributes to determine whether an index is maintained for the attribute values. If the created attribute values are indexed, Directory Server adds the new attribute values to the index, and then the actual attribute values are created in the entry.
Example 2.1. Indexing steps Directory Server performs when a user adds an entry
Assume that Directory Server maintains the following indexes:
-
Equality, approximate, and substring indexes for the
cn
andsn
attributes. -
Equality and substring indexes for the
telephoneNumber
attribute. -
Substring indexes for the
description
attribute.
For example, a user adds the following entry:
dn: cn=John Doe,ou=People,dc=example,dc=com objectclass: top objectClass: person objectClass: orgperson objectClass: inetorgperson cn: John Doe cn: John sn: Doe ou: Manufacturing ou: people telephoneNumber: 408 555 8834 description: Manufacturing lead
When the user adds the entry, Directory Server performs the following steps:
-
Create the
cn
equality index entry forJohn
andJohn Doe
. -
Create the
cn
approximate index entries forJohn
andJohn Doe
. -
Create the
cn
substring index entries forJohn
andJohn Doe
. -
Create the
sn
equality index entry forDoe
. -
Create the
sn
approximate index entry forDoe
. -
Create the
sn
substring index entry forDoe
. -
Create the
telephoneNumber
equality index entry for408 555 8834
. -
Create the
telephoneNumber
substring index entry for408 555 8834
. -
Create the
description
substring index entry forManufacturing lead
.
This example illustrates that the number of actions required to create and maintain databases for a large directory can be very resource-intensive.
Do not define a substring index for membership attributes (for example, member
,uniquemember
) because it can impact Directory Server performance. When adding or removing members, for example,uniquemember
to a group with many members, the computation of the uniquemember
substring index requires to evaluating all uniquemember
values and not only added or removed values.
2.3. Default index attributes
Directory Server stores the default index attributes in the cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config
entry. To display them, including their index types, enter:
# ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "cn=default indexes,cn=config,cn=ldbm database,cn=plugins,cn=config" -s one -o ldif-wrap=no
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Removing the attributes listed in the table (system indexes) from the index of databases can significantly affect the Directory Server performance.
2.4. Maintaining the indexes of a specific database using the command line
You can use the dsconf
utility to maintain index settings using the command line.
Procedure
For example, to add the
roomNumber
attribute to the index of theuserRoot
database with the index typeseq
andsub
, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend index add --attr roomNumber --index-type eq --index-type sub --reindex userRoot
The
--reindex
option causes that Directory Server automatically re-indexes the database.For example, to add the
pres
index type to the index settings of theroomNumber
attribute in theuserRoot
database, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend index set --attr roomNumber --add-type pres userRoot
For example, to remove the
pres
index type from the index settings of theroomNumber
attribute in theuserRoot
database, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend index set --attr roomNumber --del-type pres userRoot
For example, to remove the
roomNumber
attribute from the index in theuserRoot
database, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend index delete --attr roomNumber userRoot
Verification
List the index settings of the
userRoot
database:#
dsconf -D "cn=Directory Manager" ldap://server.example.com backend index list userRoot
2.5. Recreating an index while the instance offline
You can use the dsctl db2index
utility for reindexing the whole database while the instance is offline.
Prerequisites
-
You created an indexing entry or added additional index types to the existing
userRoot
database.
Procedure
Shut down the instance:
# dsctl instance_name stop
Recreate the index:
For all indexes in the database, run:
# dsctl instance_name db2index [23/Feb/2023:05:38:28.034826108 -0500] - INFO - check_and_set_import_cache - pagesize: 4096, available bytes 1384095744, process usage 27467776 [23/Feb/2023:05:38:28.037952026 -0500] - INFO - check_and_set_import_cache - Import allocates 540662KB import cache. [23/Feb/2023:05:38:28.055104135 -0500] - INFO - bdb_db2index - userroot: Indexing attribute: aci ... [23/Feb/2023:05:38:28.134350191 -0500] - INFO - bdb_db2index - userroot: Finished indexing. [23/Feb/2023:05:38:28.151907852 -0500] - INFO - bdb_pre_close - All database threads now stopped db2index successful
For specific attribute indexes, run:
# dsctl instance_name db2index userRoot --attr aci cn givenname
The following command recreates indexes for
aci
,cn
, andgivenname
attributes.For more information regarding
dsctl
(offline) command, run:# dsctl instance_name db2index --help
Start the instance:
# dsctl instance_name start
Verification
List the index settings of the
userRoot
database:# dsconf -D "cn=Directory Manager" ldap://server.example.com backend index list userRoot
2.6. Maintaining the indexes of a specific database using the web console
You can use the web console to maintain index settings in Directory Server.
Prerequisites
- You are logged in to the instance in the web console.
Procedure
Navigate to
. To add an attribute to the index:
- Click .
-
Enter the attribute name to the
Select An Attribute
field. - Select the index types.
-
Select
Index attribute after creation
. - Click .
To update the index settings of an attribute:
-
Click the overflow menu next to the attribute, and select
Edit Index
. - Update the index settings to your needs.
-
Select
Index attribute after creation
. - Click .
-
Click the overflow menu next to the attribute, and select
To delete an attribute from the index:
-
Click the overflow menu next to the attribute, and select
Delete Index
. -
Select
Yes, I am sure
, and click . -
In the
Reindex Suffix
. menu, select
-
Click the overflow menu next to the attribute, and select
Verification
-
Navigate to
, and verify that the index settings reflect the changes you made.