Overview #
The simple paged results control is a SupportedControl that can be attached to a search operation to indicate that only a subset of the results should be returned.The simple paged results control is defined in RFC 2696.
Simple Paged Results Control may be used to iterate through the search results a page at a time.
Similar to the virtual list view control with the exception that it doesn't require the results to be sorted and can only be used to iterate sequentially through the search results.
Simple Paged Results Control may be useful when:
- the LDAP client has limited resources
- on very large result sets where the client may not be able to process the entire result set from a given LDAP query
- or when the LDAP client is connected over a low-bandwidth connection.
- there are limits set on the LDAP server as when using Microsoft Active Directory and MaxPageSize is exceeded.
The same control is used for both the SearchRequest and SearchResultDone messages.
Simple Paged Results Control has an OID of 1.2.840.113556.1.4.319, and the value is encoded as follows:
realSearchControlValue ::= SEQUENCE { size INTEGER (0..maxInt), -- requested page size from client -- result set size estimate from server cookie OCTET STRING }
An Example LDAPSEARCH#
Simple Paged Results Control allows a search operation to return only a subset of the results at a time. It can be used to iterate through the search results a page at a time.Simple Paged Results Control is similar to the Virtual List View Control with the exception that it does not require the results to be sorted and can only be used to iterate sequentially through the search results.
Use the ldapsearch command with the --simplePageSize option. The following command also uses the --countEntries option to mark each page.
$ ldapsearch --hostname localhost --port 1389 --bindDN "cn=Directory Manager" --bindPassword password --searchScope sub --baseDN dc=example,dc=com --simplePageSize 2 --countEntries "(objectclass=*)" dn: ou=Groups,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: Groups dn: ou=People,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: People # Total number of matching entries: 2 dn: ou=Special Users,dc=example,dc=com objectClass: organizationalUnit objectClass: top description: Special Administrative Accounts ou: Special Users dn: ou=Company Servers,dc=example,dc=com objectClass: organizationalUnit objectClass: top description: Standard branch for Company Server registration ou: Company Servers # Total number of matching entries: 2 dn: ou=Contractors,dc=example,dc=com objectClass: organizationalUnit objectClass: top ou: Contractors ou: Product Testing ou: Product Development ou: Accounting # Total number of matching entries: 1
For Example, Microsoft Active Directory have a default server-side limit of 1000 entries, controlled by the MaxPageSize within the LDAP policy in Active Directory, of results that are returned in a single request. If the results of a query exceed the MaxPageSize value, the Paged Results control is used with a page size equal to or less than the server-side limit in order to retrieve all of the results of the query.
More Information #
There might be more information for this subject on one of the following:- Active Directory Service Interfaces
- EDirectoryLDAPVirtualListViewAndServerSideSortControls
- Glossary Of LDAP And Directory Terminology
- LDAP Extensions and Controls Listing
- LDAP policy in Active Directory
- LDAP_ADMINLIMIT_EXCEEDED
- MaxPageSize
- MaxQueryDuration
- MaxResultSetSize
- Search Using the Simple Paged Results Control
- SupportedControl
- Virtual List View Control