Indexing Directory Data

This section describes how to index attributes using the dsconfig command-line tool. Indexes are configured per server and index configuration is not replicated.

You can use dsconfig to create local database indexes and Virtual List View (VLV) indexes. A local database index is used to find entries that match search criteria. A VLV index is used to process searches efficiently with VLV controls.

Unindexed searches are denied by default, unless the user has the unindexed-search privilege. For more information, see To Change a Root User's Privileges.

You can determine whether a search is indexed in two ways:

• Try to perform the search anonymously. (The server rejects unindexed anonymous searches by default.)

• Use the debugsearchindex operational attribute. This attribute provides the indexes used in the search, the number of candidate entries from each index, and the final indexed status. Include the debugsearchindex attribute in your ldapsearch command, as follows:

  $ ldapsearch -h localhost -p 1389 -b "dc=example,dc=com" "(objectClass=*)" debugsearchindex

Configuring Indexes on the Local DB Back End

The Local DB back end supports the following index types:

• approximate — Improves the efficiency of searches using approximate search filters.

• equality - Improves the efficiency of searches using equality search filters.

• ordering - Improves the efficiency of searches using "greater than or equal to" or "less than or equal to" search filters. In the future, this index type might also be used for server-side sorting.

• presence - Improves the efficiency of searches using presence search filters.

• substring - Improves the efficiency of searches using substring search filters.

The directory server supports indexing for only a subset of extensible matching operations, including indexes based on collation matching rules and the relative time and partial date and time matching rules. For more information, see Searching Internationalized Entries and Relative Time Matching Rules and Partial Date Or Time Matching Rules in Oracle Fusion Middleware Architecture Reference for Oracle Unified Directory.

When you create a new local DB back end with dsconfig, the following default indexes are created automatically:

• aci (presence index)

• ds-sync-hist (ordering index)

• entryuuid (equality index)

• objectclass (equality index)

To Create a New Local DB Index

This procedure demonstrates the steps for creating a new local DB index.

1. Create the new index.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
     create-local-db-index \
     --backend-name backend --index-name attribute \
     --set index-type:index-type

2. Check that the index was created by listing the local DB indexes for that back end.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
     list-local-db-indexes \
     --backend-name backend

3. Configure any specific index properties.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \ 
     set-local-db-index-prop \
     --backend-name backend --index-name attribute \
     --set property:value

4. List the index properties to verify your change.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
     get-local-db-index-prop \
     --backend-name backend --index-name attribute

5. Rebuild the index.
   • Either stop the server, rebuild the index, then restart the server.

     $ stop-ds
     $ rebuild-index --baseDN baseDN --index attribute
     $ start-ds

   • Or, rebuild the index online by running the rebuild-index command as a task.

     $ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -w password -X \
       --baseDN dc=example,dc=com --index aci
     Rebuild Index task 20110201162742312 scheduled to start immediately
     ...
     Rebuild Index task 20110201162742312 has been successfully completed

Example 7-7 Creating a New Equality Index

This example creates a new equality index for the employeeNumber attribute, verifies the index properties, and sets the index entry limit to 5000.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  create-local-db-index \
  --backend-name userRoot --index-name employeeNumber \
  --set index-type:equality
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  list-local-db-indexes \
  --backend-name userRoot
Local DB Index : Type    : index-type
---------------:---------:-----------
...
employeeNumber : generic : equality
...
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  get-local-db-index-prop \
  --backend-name userRoot --index-name employeeNumber
Property                       : Value(s)
-------------------------------:---------------
attribute                      : employeenumber
index-entry-limit              : 4000
index-extensible-matching-rule : -
index-type                     : equality
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  set-local-db-index-prop \
  --backend-name userRoot --index-name employeeNumber --set index-entry-limit:5000
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  get-local-db-index-prop \
  --backend-name userRoot --index-name employeeNumber
Property                       : Value(s)
-------------------------------:---------------
attribute                      : employeenumber
index-entry-limit              : 5000
index-extensible-matching-rule : -
index-type                     : equality
$ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -w password -X \
  --baseDN dc=example,dc=com --index employeeNumber

Example 7-8 Adding a Substring Index

This example adds a substring index to the index created in the previous example.

$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  set-local-db-index-prop \
  --backend-name userRoot --index-name employeeNumber \
  --add index-type:substring
$ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -X -n \
  get-local-db-index-prop \
  --backend-name userRoot --index-name employeeNumber
Property                       : Value(s)
-------------------------------:---------------
attribute                      : employeenumber
index-entry-limit              : 5000
index-extensible-matching-rule : -
index-type                     : equality, substring
$ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -w password -X \
  --baseDN dc=example,dc=com --index employeeNumbe

Configuring VLV Indexes

A VLV index applies to a particular search on a given base entry and its subtree. The sort order, scope of the index, base DN, and filter must be defined when you create the index.

To Create a New VLV Index

1. Use dsconfig to create a new VLV index as follows:

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     create-local-db-vlv-index \
     --backend-name backend --index-name name --set sort-order:attributes \
     --set scope:scope --set base-dn:baseDN --set filter:filter

   where:

   • index-name specifies a unique index name, which cannot be altered after the VLV index is created.

   • sort-order specifies the names of the attributes by which the entries are sorted and their order of precedence, from highest to lowest.

   • scope specifies the LDAP scope of the query being indexed and can be one of base-object, single-level, subordinate-subtree, or whole-subtree.

   • base-dn specifies the base DN used in the search query being indexed.

   • filter specifies the LDAP filter used in the query being indexed and can be any valid LDAP filter.

2. Check that the index was created by listing the existing VLV indexes.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     list-local-db-vlv-indexes \
     --backend-name backend

3. Display the index properties to verify your change.

   $ dsconfig -h localhost -p 4444 -D "cn=directory manager" -w password -n \
     get-local-db-vlv-index-prop \
     --backend-name backend --index-name name

4. Rebuild the index.
   • Either stop the server, rebuild the index, then restart the server.

     $ stop-ds
     $ rebuild-index --baseDN baseDN --index vlv.name
     $ start-ds

   • Or, rebuild the index online by running the rebuild-index command as a task.

     $ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -w password -X \
       --baseDN baseDN --index vlv.name

Example 7-9 Creating a New VLV Index

The following example creates a new VLV index to sort entries first by surname and then by common name for queries sn=*. The example then rebuilds the index online.

$ dsconfig -D "cn=directory manager" -w password -n create-local-db-vlv-index \
  --backend-name userRoot --index-name myVLVIndex --set sort-order:"sn cn" \
  --set scope:base-object --set base-dn:dc=example,dc=com --set filter:sn=*
$ rebuild-index -h localhost -p 4444 -D "cn=Directory manager" -w password -X \
  -b "dc=example,dc=com" --index vlv.myVLVIndex