Page created: 24 Jul 2019 |
Page updated: 6 Nov 2019
The ldapsearch command can be used with the --matchingEntryCountControl option to determine the count of entries that match a search filter. Users will need to be granted access to this control by its OID 22.214.171.124.4.1.30126.96.36.199 with the following command:
$ bin/dsconfig set-access-control-handler-prop \ --add "global-aci:(targetcontrol=\"188.8.131.52.4.1.30184.108.40.206\") (version 3.0; acl \"Allow members of the Index Debugging Users group to use the matching entry count request control \"; allow (read) groupdn=\"ldap:///cn=Index Debugging Users,ou=Groups,dc=example,dc=com\";)"
An examineCount control can be used for searches that are at least partially indexed, in order to determine whether to return an examined count, an unexamined count, or an upper bound count. The factors that determine what is returned are:
- A search is fully indexed if indexes can be used to identify the entry IDs for all entries that match the filter without ambiguity. Indexes can also be used to make sure that all of those candidates are within the scope of the search.
- A search is partially indexed if indexes can be used to identify the entry IDs for all entries that match the search criteria, but the candidate list may potentially also include entries that either don't match the filter or are outside the scope of the search.
- A search is unindexed if it is not possible to retrieve a candidate list based on either the filter or the search scope.
- An unexamined count is a count of the exact number of entries that match the search criteria, only through the use of index processing.
- An examined count is the same as an unexamined count, except that all of the candidate entries are examined to determine whether they would have been returned to the client. An examined count may be less than an unexamined count if the set of matching entries includes those that would be removed by access control evaluation, or special entries like LDAP sub-entries, replication conflict entries, or soft-deleted entries.
- An upper bound count is the maximum number of entries that match the criteria, but indicates that the server could not determine exactly how many matching entries there were without examining each candidate, which it did not do.
- If a search is fully indexed, the result is an examined count or an unexamined count. If alwaysExamine is true and examineCount is greater than or equal to the number of candidates, the result is an examined count. If alwaysExamine is false, or if the number of candidates exceeds examineCount, the result is an unexamined count.
- If a search is partially indexed, the result is either an examined count or an upper bound count. The alwaysExamine flag isn't relevant in this case. If examineCount is greater than or equal to the number of candidates, the result is an examined count. If not, the result is an upper bound count.
- If a search is unindexed, the result is either an examined count or an unknown count. If allowUnindexed is true, the unindexed search is processed, which can be very expensive. Instead of getting the matching entries back, the examined count is returned. If allowUnindexed is false, an unknown count is returned. If allowUnindexed is true, the requester needs to have the unindexed-search privilege to get the exact count.
The following is a sample
$./ldapsearch \ --bindDN "cn=directory manager" \ --bindPassword password \ --baseDN dc=example,dc=com \ --matchingEntryCountControl examineCount=100:alwaysExamine:allowUnindexed:debug \ "(objectclass=*)"