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.

You must grant users access to this control by invoking 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 the search returns:

  • 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 could 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 the search would return them to the client.

    An examined count might be less than an unexamined count if the set of matching entries includes those that the search would remove, including special entries, such as LDAP subentries, replication conflict entries, or soft-deleted entries, and entries excluded through access control evaluation.

  • 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 server processes the unindexed search, which can be very expensive. Instead of getting the matching entries back, the server returns the examined count. If allowUnindexed is false, the server returns an unknown count. If allowUnindexed is true, the requester needs to have the unindexed-search privilege to get the exact count.

Example

The following example demonstrates an ldapsearch using the --matchingEntryCountControl option:

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