PingDirectory

Working with the matching entry count control

You can use the ldapsearch command with the --matchingEntryCountControl option to determine the count of entries that match a search filter.

Users must be granted access to this control by its OID 1.3.6.1.4.1.30221.2.5.36 with the following command.

$ bin/dsconfig set-access-control-handler-prop \
 --add "global-aci:(targetcontrol=\"1.3.6.1.4.1.30221.2.5.36\")
   (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\";)"

You can use an examineCount control for searches that are at least partially indexed to determine whether to return an examined count, an unexamined count, or an upper bound count. The following factors determine what is returned:

  • A search is fully indexed if indexes can be used to identify the entry IDs for all entries that match the filter without ambiguity. You can also use indexes to make sure that all of those candidates are within the scope of the search.

  • A search is partially indexed if you can use indexes to identify the entry IDs for all entries that match the search criteria.

    The candidate list might also include entries that either don’t match the filter or are outside the scope of the search.

  • A search is unindexed if it’s 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 might 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, such as 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 doesn’t 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.

Example

The following example is a ldapsearch with the --matchingEntryCountControl option.

$./ldapsearch \
  --bindDN "cn=directory manager" \
  --bindPassword password \
  --baseDN dc=example,dc=com \
  --matchingEntryCountControl examineCount=100:alwaysExamine:allowUnindexed:debug \
  "(objectclass=*)"