51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER START
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! This work is licensed under the Creative Commons
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! To view a copy of this license, visit
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! or send a letter to Creative Commons, 444 Castro Street,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Suite 900, Mountain View, California, 94041, USA.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! You can also obtain a copy of the license at
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! See the License for the specific language governing permissions
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! and limitations under the License.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! If applicable, add the following below this CCPL HEADER, with the fields
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! enclosed by brackets "[]" replaced with your own identifying information:
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! Portions Copyright [yyyy] [name of copyright owner]
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark ! CCPL HEADER END
88fe6d2cfe60d200787b16076993a3fbdb4668a7mark ! Copyright 2011-2015 ForgeRock AS.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xmlns='http://docbook.org/ns/docbook' version='5.0' xml:lang='en'
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ provides several indexing schemes to speed up searches.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When a client requests a directory search operation, the client sends
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the server a filter expression such as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>(&(uid=*jensen*)(l=Stavanger))</literal>. The server then uses
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark applicable indexes to find entries with attribute values likely to match
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the search. If no indexes are applicable, then the server potentially has
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to go through all entries to look for candidate matches.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Looking through all entries is resource-intensive for large directories.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark For this reason, the <literal>unindexed-search</literal> privilege, allowing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark users to request searches for which no applicable index exists, is reserved
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for the directory root user by default.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Rather than granting the <literal>unindexed-search</literal> privilege
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to more users and client applications, you configure indexes to correspond
760976698b783a47fe7de0a3aaae012924009da7mark to the searches that clients need to perform. See
760976698b783a47fe7de0a3aaae012924009da7mark <xref linkend="debug-search-indexes" /> for details.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <para>This chapter first describes index types, and demonstrates how to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark index attribute values. This chapter also lists the default indexing
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark configuration for OpenDJ directory server.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ provides several different index types, each corresponding
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to a different type of search.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>An approximate index is used to match values that "sound like" those
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark provided in the filter. An approximate index on <literal>cn</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark allows clients to find people even when they misspell names as in the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark following example.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn~=Babs Jansen)" cn</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkcn: Babs Jensen</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>An equality index is used to match values that correspond exactly
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark (though generally without case sensitivity) to the value provided in
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the search filter. An equality index requires clients to match values
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark without wildcards or misspellings.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=bjensen)" mail</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bjensen,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkmail: bjensen@example.com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>An ordering index is used to match values for a filter that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark specifies a range. The <literal>ds-sync-hist</literal> has an ordering
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark index by default because searches on that attribute often seek entries
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark with changes more recent than the last time a search was performed.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example shows a search that specifies ranges.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(&(uidNumber>=1120)(roomNumber>=4500))" uid</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=charvey,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: charvey
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=eward,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=mvaughan,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkuid: mvaughan
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=pchassin,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkuid: pchassin</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A presence index is used to match the fact that an attribute is
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark present on the entry, regardless of the value. The <literal>aci</literal>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute is indexed for presence by default to allow quick retrieval
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark of entries with ACIs.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(aci=*)" -</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkdn: ou=People,dc=example,dc=com</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A substring index is used to match values specified with wildcards
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the filter. Substring indexes can be expensive to maintain, especially
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark for large attribute values.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(cn=Barb*)" cn</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: uid=bfrancis,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Francis
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bhal2,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Hall
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjablons,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jablonski
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bjensen,ou=People,dc=example,dc=com
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Barbara Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkcn: Babs Jensen
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarkdn: uid=bmaddox,ou=People,dc=example,dc=com
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkcn: Barbara Maddox</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>A VLV or browsing index are designed to help the server respond to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark client applications that need virtual list view results, for example to
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark browse through a long list in a GUI. They also help the server respond
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to clients that request server-side sorting of the search results.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>VLV indexes correspond to particular searches. Configure your
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark VLV indexes using the Control Panel, and copy the command-line
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark equivalent from the Details pane for the operation, if necessary.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In some cases you need an index for a matching rule other than those
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark described above. For example, OpenDJ supports generalized time based
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark matching so applications can search for all times later than, or earlier
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark than a specified time.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
760976698b783a47fe7de0a3aaae012924009da7mark <indexterm>
760976698b783a47fe7de0a3aaae012924009da7mark </indexterm>
760976698b783a47fe7de0a3aaae012924009da7mark <para>OpenDJ search performance depends on indexes. As mentioned above,
760976698b783a47fe7de0a3aaae012924009da7mark unindexed searches are so resource intensive that by default OpenDJ refuses
760976698b783a47fe7de0a3aaae012924009da7mark to perform unindexed searches. This is because, in order to find candidate
760976698b783a47fe7de0a3aaae012924009da7mark matches for an unindexed search, OpenDJ has to scan the entire directory
760976698b783a47fe7de0a3aaae012924009da7mark database. Most searches should therefore use indexes.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <para>A simple way of checking the indexes that match a search is to request
760976698b783a47fe7de0a3aaae012924009da7mark the <literal>debugsearchindex</literal> attribute in your results.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(uid=user.1000)" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark debugsearchindex</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=debugsearch
760976698b783a47fe7de0a3aaae012924009da7markdebugsearchindex: filter=(uid=user.1000)[INDEX:uid.equality][COUNT:1] final=[COU
08248b5c5b494aff8d1922e8e0b5777796d7450dmark NT:1]</computeroutput>
760976698b783a47fe7de0a3aaae012924009da7mark <para>When you request the <literal>debugsearchindex</literal> attribute,
760976698b783a47fe7de0a3aaae012924009da7mark instead of performing the search, OpenDJ returns debug information indicating
760976698b783a47fe7de0a3aaae012924009da7mark how it would process the search operation. In the example above you notice
760976698b783a47fe7de0a3aaae012924009da7mark OpenDJ hits the equality index for <literal>uid</literal> right away.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <para>A less exact search requires more work from OpenDJ. In the following
760976698b783a47fe7de0a3aaae012924009da7mark example OpenDJ would have to return over 10,000 entries.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(uid=*)" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark debugsearchindex</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=debugsearch
760976698b783a47fe7de0a3aaae012924009da7markdebugsearchindex: filter=(uid=*)[NOT-INDEXED] scope=wholeSubtree[LIMIT-EXCEEDED:
08248b5c5b494aff8d1922e8e0b5777796d7450dmark 10002] final=[NOT-INDEXED]</computeroutput>
760976698b783a47fe7de0a3aaae012924009da7mark <para>By default OpenDJ rejects unindexed searches when the number of
760976698b783a47fe7de0a3aaae012924009da7mark candidate entries goes beyond the search or look-though limit.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*)"</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>SEARCH operation failed
760976698b783a47fe7de0a3aaae012924009da7markResult Code: 50 (Insufficient Access Rights)
760976698b783a47fe7de0a3aaae012924009da7markAdditional Information: You do not have sufficient privileges to perform
08248b5c5b494aff8d1922e8e0b5777796d7450dmark an unindexed search</computeroutput>
760976698b783a47fe7de0a3aaae012924009da7mark <para>When an unindexed search is performed, it shows up in the access
760976698b783a47fe7de0a3aaae012924009da7mark log with the <literal>unindexed</literal> label.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark...SEARCH RES ... result=50 message="You do not have sufficient privileges
08248b5c5b494aff8d1922e8e0b5777796d7450dmark to perform an unindexed search" nentries=0 unindexed etime=1
08248b5c5b494aff8d1922e8e0b5777796d7450dmark </programlisting>
760976698b783a47fe7de0a3aaae012924009da7mark <para>If directory users tell you their client applications are getting this
760976698b783a47fe7de0a3aaae012924009da7mark error, then you can work with them either to help them make their search
760976698b783a47fe7de0a3aaae012924009da7mark filter specific enough to use existing indexes, or to index attributes they
760976698b783a47fe7de0a3aaae012924009da7mark need indexed in order to perform their searches. For example, if a
760976698b783a47fe7de0a3aaae012924009da7mark directory client application is having trouble performing a search with
760976698b783a47fe7de0a3aaae012924009da7mark a filters such as <literal>(objectClass=person)</literal>, you can suggest
760976698b783a47fe7de0a3aaae012924009da7mark that they adjust the search to be more specific, such as
760976698b783a47fe7de0a3aaae012924009da7mark <literal>(&(mail=username@maildomain.net)(objectClass=person))</literal>,
760976698b783a47fe7de0a3aaae012924009da7mark so that the server can use an index, in this case equality for mail, to
760976698b783a47fe7de0a3aaae012924009da7mark limit the number of candidate entries to check for matches.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <para>You can view and edit what is indexed through OpenDJ Control Panel,
760976698b783a47fe7de0a3aaae012924009da7mark Indexes > Manage Indexes. Alternatively you can manage indexes using the
760976698b783a47fe7de0a3aaae012924009da7mark command-line tools demonstrated in <xref linkend="configure-indexes" />.
760976698b783a47fe7de0a3aaae012924009da7mark If an index already exists, but you suspect it is not working properly, see
760976698b783a47fe7de0a3aaae012924009da7mark <para>If you do need to allow some applications to perform unindexed searches,
760976698b783a47fe7de0a3aaae012924009da7mark because they need to retrieve very large numbers of entries for example, then
760976698b783a47fe7de0a3aaae012924009da7mark you can assign them the <literal>unindexed-search</literal> privilege. See
760976698b783a47fe7de0a3aaae012924009da7mark <link xlink:show="new" xlink:href="admin-guide#configure-privileges"
760976698b783a47fe7de0a3aaae012924009da7mark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Configuring
760976698b783a47fe7de0a3aaae012924009da7mark Privileges</citetitle></link> for details. A successful unindexed search also
760976698b783a47fe7de0a3aaae012924009da7mark shows up in the access log with the label <literal>unindexed</literal>,
760976698b783a47fe7de0a3aaae012924009da7mark usually with a large etime as well.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark...SEARCH RES conn=11 op=1 msgID=2 result=0 nentries=10000 unindexed etime=1129
08248b5c5b494aff8d1922e8e0b5777796d7450dmark </programlisting>
760976698b783a47fe7de0a3aaae012924009da7mark <para>There is a trade off between the cost of maintaining an index and the
760976698b783a47fe7de0a3aaae012924009da7mark value the index has in speeding up searches. Although monitoring index use
760976698b783a47fe7de0a3aaae012924009da7mark is not something to leave active in production due to the additional cost and
760976698b783a47fe7de0a3aaae012924009da7mark memory needed to maintain the statistics, in a test environment you can
760976698b783a47fe7de0a3aaae012924009da7mark activate index analysis using the <command>dsconfig set-backend-prop</command>
760976698b783a47fe7de0a3aaae012924009da7mark command.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-backend-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-filter-analyzer-enabled:true \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
760976698b783a47fe7de0a3aaae012924009da7mark <para>The command causes OpenDJ to analyze filters used and keep the results
760976698b783a47fe7de0a3aaae012924009da7mark in memory, so that you can read them through the <literal>cn=monitor</literal>
760976698b783a47fe7de0a3aaae012924009da7mark interface.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>ldapsearch \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 1389 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN "cn=userRoot Database Environment,cn=monitor" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark "(objectclass=*)" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark filter-use</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>dn: cn=userRoot Database Environment,cn=monitor
760976698b783a47fe7de0a3aaae012924009da7markfilter-use: (mail=aa*@maildomain.net) hits:1 maxmatches:0 message:
760976698b783a47fe7de0a3aaae012924009da7markfilter-use: (objectClass=*) hits:1 maxmatches:-1 message:presence index type is
760976698b783a47fe7de0a3aaae012924009da7mark disabled for the objectClass attribute
760976698b783a47fe7de0a3aaae012924009da7markfilter-use: (uid=user.1000) hits:2 maxmatches:1 message:
760976698b783a47fe7de0a3aaae012924009da7markfilter-use: (uid=user.1001) hits:1 maxmatches:1 message:
760976698b783a47fe7de0a3aaae012924009da7markfilter-use: (cn=aa*) hits:1 maxmatches:10 message:
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkfilter-use: (cn=b*) hits:1 maxmatches:834 message:</computeroutput>
760976698b783a47fe7de0a3aaae012924009da7mark <para>The <literal>filter-use</literal> values consist of the filter, followed
760976698b783a47fe7de0a3aaae012924009da7mark by <literal>hits</literal> being the number of times the filter was used,
760976698b783a47fe7de0a3aaae012924009da7mark followed by <literal>maxmatches</literal> being the number of matches found
760976698b783a47fe7de0a3aaae012924009da7mark for the filter, followed by a message.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <para>You can turn off index analysis with the <command>dsconfig
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-backend-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-filter-analyzer-enabled:false \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll</userinput>
760976698b783a47fe7de0a3aaae012924009da7mark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark You modify index configurations by using the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark The configuration changes then take effect
ec40cc0dc62425cea5d63fd9d984f8614479de25mark after you rebuild the index according to the new configuration, using the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark The <command>dsconfig --help-database</command> command lists subcommands
ec40cc0dc62425cea5d63fd9d984f8614479de25mark for creating, reading, updating, and deleting index configuration.
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Indexes are per directory backend rather than per suffix. To maintain
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark separate indexes for different suffixes on the same directory server, put
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the suffixes in different backends.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can configure standard indexes from the Control Panel, and also
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark on the command line using the <command>dsconfig</command> command. After
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you finish configuring the index, you must rebuild the index for the changes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to take effect.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example creates a new substring index for
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark create-local-db-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index-name description \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-type:substring \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example configures an approximate index for
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-local-db-index-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index-name cn \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-type:approximate \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The OpenDJ Control Panel New Index window does not help you set up
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark extensible matching rule indexes. Use the <command>dsconfig</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command instead.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example configures an extensible matching rule
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark index for "later than" and "earlier than" generalized time matching on
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark create-local-db-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-type:extensible \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.5 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-extensible-matching-rule:1.3.6.1.4.1.26027.1.4.6 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index-name lastLoginTime \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark <para>In the OpenDJ Control Panel, select Manage Indexes >
08248b5c5b494aff8d1922e8e0b5777796d7450dmark New VLV Index, and then set up your VLV index using the New VLV
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Index window.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imageobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <imagedata fileref="images/create-vlv-index.png" format="PNG" />
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </imageobject>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark <textobject>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark The New VLV Index window helps you to configure a browsing index.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark </textobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </mediaobject>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>After you finish configuring your index and click OK, the Control
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Panel prompts you to make the additional changes necessary to complete the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark VLV index configuration, and then to build the index.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>You can also create the equivalent index configuration using the
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark create-local-db-vlv-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDn "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index-name people-by-last-name \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set base-dn:ou=People,dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set filter:"(|(givenName=*)(sn=*))" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set scope:single-level \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set sort-order:"+sn +givenName" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When referring to a virtual list view (VLV) index after creation, you
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark must add <literal>vlv.</literal> as a prefix. In other words, if you named
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the VLV index <literal>people-by-last-name</literal>, you refer to it as
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>vlv.people-by-last-name</literal> when rebuilding indexes,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark changing index properties such as the index entry limit, or verifying
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark indexes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>After you change an index configuration, or when you find that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark an index is corrupt, you can rebuild the index. When you rebuild indexes,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark you specify the base DN of the data to index, and either the list of indexes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to rebuild or <option>--rebuildAll</option>. You can rebuild indexes while
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the server is offline, or while the server is online. If you rebuild the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark index while the server is online, then you must schedule the rebuild process
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark as a task.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example rebuilds the <literal>cn</literal> index
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark immediately with the server online.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>rebuild-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index cn \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --start 0</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Rebuild Index task 20110607171639867 scheduled to start Jun 7, 2011 5:16:39 PM</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example rebuilds degraded indexes immediately with
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the server online.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>rebuild-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --rebuildDegraded</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=7 msgID=8847510
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark message="Due to changes in the configuration, index
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark dc_example_dc_com_description is currently operating in a degraded state
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark and must be rebuilt before it can be used"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=8 msgID=8847591
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark message="Rebuild of all degraded indexes started with 160 total entries
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark to process"
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[31/Jan/2012:16:43:25 +0100] severity="NOTICE" msgCount=10 msgID=8847493
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark message="Rebuild complete. Processed 160 entries in 0 seconds (average
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkRebuild Index task 20120131164324838 has been successfully completed</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you add a new attribute as described in <link
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Updating
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark Directory Schema</citetitle></link>, and then create indexes for the new
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark attribute, the new indexes appear as degraded, even though the attribute
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark has not yet been used, and so indexes are sure to be empty, rather than
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark degraded.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In this special case, you can safely use the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <option>--clearDegradedState</option> option to avoid having to scan
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the entire directory backend to rebuild the new, unused index. This
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark is shown in the following example, where an index has just been created
ec40cc0dc62425cea5d63fd9d984f8614479de25mark Start by testing the index status by using the
ec40cc0dc62425cea5d63fd9d984f8614479de25mark The final column show in the output is the Index Valid column,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark <literal>false</literal> before the rebuild, <literal>true</literal> after.
88fe6d2cfe60d200787b16076993a3fbdb4668a7mark The <command>dbtest list-index-status</command> command
88fe6d2cfe60d200787b16076993a3fbdb4668a7mark can take a long time to complete, as it reads all indexes for all backends.
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dbtest \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark list-index-status \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backendID userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark | grep newUnusedAttribute</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>newUnusedAttribute.equality Index ...newUnusedAttribute.equality false...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewUnusedAttribute.presence Index ...newUnusedAttribute.presence false...
08248b5c5b494aff8d1922e8e0b5777796d7450dmarknewUnusedAttribute.substring Index ...newUnusedAttribute.substring false...</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>rebuild-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --clearDegradedState \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index newUnusedAttribute \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --start 0</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Rebuild Index task 20130211175925012 scheduled to start Feb 11, 2013 5:59:25
08248b5c5b494aff8d1922e8e0b5777796d7450dmark PM CET</computeroutput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dbtest \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark list-index-status \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backendID userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark | grep newUnusedAttribute</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>newUnusedAttribute.equality Index ...newUnusedAttribute.equality true...
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmarknewUnusedAttribute.presence Index ...newUnusedAttribute.presence true...
08248b5c5b494aff8d1922e8e0b5777796d7450dmarknewUnusedAttribute.substring Index ...newUnusedAttribute.substring true...</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>If the newly indexed attribute has already been used, rebuild indexes
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark instead.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>As the number of entries in your directory grows, it can make sense
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark not to maintain indexes for particular values. For example, every entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark in the directory has the value <literal>top</literal> for the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>objectClass</literal> attribute, so maintaining a list of entries
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that match the filter <literal>(objectClass=top)</literal> is not a
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark reasonable use of resources. In a very, very large directory, the same can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>In an index, each index key points to a list of entries that
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark are candidates to match. For the <literal>objectClass</literal> index key
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark that corresponds to <literal>=top</literal>, the list of entries can
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark include every entry in the directory.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>OpenDJ directory server therefore defines an index entry limit. When
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark the number of entries that an index key points to exceeds the index entry
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark limit, OpenDJ stops maintaining the list of entries for that index key.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <para>The default index entry limit value is 4000. 4000 is intended to be
760976698b783a47fe7de0a3aaae012924009da7mark large enough for most index keys, though it prevents OpenDJ from maintaining
760976698b783a47fe7de0a3aaae012924009da7mark indexes at any cost. You can use the <command>dbtest</command> command to
760976698b783a47fe7de0a3aaae012924009da7mark evaluate how well attributes are indexed, and consider whether to change
760976698b783a47fe7de0a3aaae012924009da7mark the index entry limit. Non-zero values in the "Undefined" column indicate
760976698b783a47fe7de0a3aaae012924009da7mark the number of index keys that have reached the limit and are no longer
760976698b783a47fe7de0a3aaae012924009da7mark maintained. The "Undefined keys" are then listed below.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dbtest list-index-status --backendID userRoot --baseDN dc=example,dc=com</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Index Name Index Type JE Database Name Index Valid Record Count Undefined 95% 90% 85%
760976698b783a47fe7de0a3aaae012924009da7mark---------------------------------------------------------------------------------------------------------------------------------------
760976698b783a47fe7de0a3aaae012924009da7markid2children Index dc_example_dc_com_id2children true 2 1 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markid2subtree Index dc_example_dc_com_id2subtree true 2 2 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markuid.equality Index dc_example_dc_com_uid.equality true 10000 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markaci.presence Index dc_example_dc_com_aci.presence true 0 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markds-sync-conflict.equality Index dc_example_dc_com_ds-sync-conflict.equality true 0 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markgivenName.equality Index dc_example_dc_com_givenName.equality true 8605 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markgivenName.substring Index dc_example_dc_com_givenName.substring true 19629 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markobjectClass.equality Index dc_example_dc_com_objectClass.equality true 6 4 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markmember.equality Index dc_example_dc_com_member.equality true 0 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markuniqueMember.equality Index dc_example_dc_com_uniqueMember.equality true 0 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markcn.equality Index dc_example_dc_com_cn.equality true 10000 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markcn.substring Index dc_example_dc_com_cn.substring true 86040 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7marksn.equality Index dc_example_dc_com_sn.equality true 10000 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7marksn.substring Index dc_example_dc_com_sn.substring true 32217 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7marktelephoneNumber.equality Index dc_example_dc_com_telephoneNumber.equality true 10000 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7marktelephoneNumber.substring Index dc_example_dc_com_telephoneNumber.substring true 73235 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markds-sync-hist.ordering Index dc_example_dc_com_ds-sync-hist.ordering true 0 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markmail.equality Index dc_example_dc_com_mail.equality true 10000 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markmail.substring Index dc_example_dc_com_mail.substring true 31235 15 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markentryUUID.equality Index dc_example_dc_com_entryUUID.equality true 10002 0 0 0 0
760976698b783a47fe7de0a3aaae012924009da7markUndefined keys: [inetorgperson] [organizationalperson] [person] [top]
760976698b783a47fe7de0a3aaae012924009da7markIndex: id2children
760976698b783a47fe7de0a3aaae012924009da7markUndefined keys: [2]
760976698b783a47fe7de0a3aaae012924009da7markUndefined keys: [.net] [@maild] [aildom] [ain.ne] [domain] [et] [ildoma] [in.net] [ldomai] [maildo] [main.n] [n.net] [net] [omain.] [t]
760976698b783a47fe7de0a3aaae012924009da7markIndex: id2subtree
08248b5c5b494aff8d1922e8e0b5777796d7450dmarkUndefined keys: [1] [2]</computeroutput>
760976698b783a47fe7de0a3aaae012924009da7mark </informalexample>
760976698b783a47fe7de0a3aaae012924009da7mark <para>In this case (for a directory with only about 10,000 entries) the
760976698b783a47fe7de0a3aaae012924009da7mark list of undefined keys is perfectly reasonable. Every user entry has the
760976698b783a47fe7de0a3aaae012924009da7mark object classes listed, and every user entry has a mail address ending in
760976698b783a47fe7de0a3aaae012924009da7mark <literal>@maildomain.net</literal>, so those values are not specific enough
760976698b783a47fe7de0a3aaae012924009da7mark to be used in search filters. The <literal>id2children</literal> and
760976698b783a47fe7de0a3aaae012924009da7mark <literal>id2subtree</literal> are for OpenDJ's internal use.</para>
d5b26224b2955d6938bf85eb63a713e1ecd3d913mark For an explanation of the output
d5b26224b2955d6938bf85eb63a713e1ecd3d913mark of the <command>dbtest list-index-status</command> command, see
d5b26224b2955d6938bf85eb63a713e1ecd3d913mark xlink:role="http://docbook.org/xlink/role/olink">dbtest(1)</link>.
760976698b783a47fe7de0a3aaae012924009da7mark <para>If you do find the limit is too low for a certain key, you can change
760976698b783a47fe7de0a3aaae012924009da7mark the index entry limit on a per index basis.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example changes the index entry limit for the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>objectClass</literal> index, and then rebuilds the index for the
760976698b783a47fe7de0a3aaae012924009da7mark configuration change to take effect. The example is contrived, but the
760976698b783a47fe7de0a3aaae012924009da7mark steps are the same for any other index.</para>
760976698b783a47fe7de0a3aaae012924009da7mark <important>
760976698b783a47fe7de0a3aaae012924009da7mark <para>Changing the index entry limit significantly can result in
760976698b783a47fe7de0a3aaae012924009da7mark serious performance degradation. Be prepared to test performance
760976698b783a47fe7de0a3aaae012924009da7mark thoroughly before you roll out an index entry limit change in
760976698b783a47fe7de0a3aaae012924009da7mark production.</para>
760976698b783a47fe7de0a3aaae012924009da7mark </important>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>dsconfig \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark set-local-db-index-prop \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --backend-name userRoot \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index-name objectClass \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --set index-entry-limit:5000 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --trustAll \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --no-prompt</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>rebuild-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --port 4444 \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindDN "cn=Directory Manager" \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --bindPassword password \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index objectclass \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --start 0</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>Rebuild Index task 20110607160349596 scheduled to start Jun 7, 2011 4:03:49 PM</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Alternatively, you can configure the index entry limit for all
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark indexes stored in a backend by using the <command>dsconfig
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark set-backend-prop</command> command with the <option>--backend-name
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark index-entry-limit:<replaceable>limitValue</replaceable></option>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark options.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
ec40cc0dc62425cea5d63fd9d984f8614479de25mark You can verify that indexes correspond to current directory data,
ec40cc0dc62425cea5d63fd9d984f8614479de25mark and that indexes do not contain errors by using the
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>The following example verifies the <literal>cn</literal> (common
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark name) index for completeness and for errors.</para>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark$ <userinput>verify-index \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --baseDN dc=example,dc=com \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --index cn \
08248b5c5b494aff8d1922e8e0b5777796d7450dmark --countErrors</userinput>
08248b5c5b494aff8d1922e8e0b5777796d7450dmark<computeroutput>[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=9437595 msg=Local DB backend userRoot does not specify the number of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark lock tables: defaulting to 97
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[07/Jun/2011:16:06:50 +0200] category=BACKEND severity=INFORMATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=9437594 msg=Local DB backend userRoot does not specify the number of
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark cleaner threads: defaulting to 24 threads
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[07/Jun/2011:16:06:51 +0200] category=JEB severity=NOTICE msgID=8847461
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msg=Checked 1316 records and found 0 error(s) in 0 seconds
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=8388710 msg=Number of records referencing more than one entry: 315
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=8388711 msg=Number of records that exceed the entry limit: 0
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=8388712 msg=Average number of entries referenced is 1.58/record
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark[07/Jun/2011:16:06:51 +0200] category=JEB severity=INFORMATION
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark msgID=8388713 msg=Maximum number of entries referenced by any
08248b5c5b494aff8d1922e8e0b5777796d7450dmark record is 32</computeroutput>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>Ignore the messages regarding lock tables and cleaner threads. The
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark important information is whether any errors are found in the indexes.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </example>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </indexterm>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you first install OpenDJ directory server and import your
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark data from LDIF, the following indexes are configured.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <entry namest="c2" nameend="c7" align="center">Non-configurable
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark internal index</entry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <entry namest="c2" nameend="c7" align="center">Non-configurable
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark internal index</entry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <entry namest="c2" nameend="c7" align="center">Non-configurable
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark internal index</entry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <entry><literal>telephone­Number</literal></entry>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <para>When you create a JE backend using the <command>dsconfig</command>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark command, OpenDJ creates the <literal>aci</literal> presence,
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark <literal>objectClass</literal> equality indexes automatically.</para>
51607ea01068c9047391e4c8b46bc9dbd0edb7fdmark </section>