6.2. Setting Search Base & Scope

Directory servers organize entries somewhat like a file system. Directory data is often depicted as an upside-down tree.

Directory data is often depicted as an upside-down tree.

In the figure shown above, entries are represented by the relevant parts of their DNs. The entry with DN dc=example,dc=com is the base entry for a suffix. Under the base entry, you see two organizational units, one for people, ou=People, the other for groups, ou=Groups. The entries for people include those of Babs Jensen, Kirsten Vaughan, and Sam Carter.

When you are searching for a person's entry somewhere under dc=example,dc=com, you can start from dc=example,dc=com, from ou=People,dc=example,dc=com, or if you have enough information to pinpoint the user entry and only want to look up another attribute value for example, then directly from the entry such as cn=Babs Jensen,ou=People,dc=example,dc=com. The DN of the entry where you choose to start the search is the base DN for the search.

When searching, you also define the scope. Scope defines what entries the server considers when checking for entries that match your search.

  • For SearchScope.BASE_OBJECT the server considers only the base entry.

    This is the scope you use if you know the full DN of the object that interests you. For example, if your base DN points to Babs Jensen's entry, cn=Babs Jensen,ou=People,dc=example,dc=com, and you want to read some of Babs's attributes, you would set scope to SearchScope.BASE_OBJECT.

  • For SearchScope.SINGLE_LEVEL the server considers all entries directly below the base entry.

    You use this scope if for example you want to discover organizational units under dc=example,dc=com, or if you want to find people's entries and you know they are immediately under ou=People,dc=example,dc=com.

  • For SearchScope.SUBORDINATES the server considers all entries below the base entry.

    This scope can be useful if you know that the base DN for your search is an entry that you do not want to match.

  • For SearchScope.WHOLE_SUBTREE (default) the server considers the base entry and all entries below.

In addition to a base DN and scope, a search request also calls for a search filter.