B.3. LDAP Search Filters
Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When using ldapsearch, there can be multiple search filters in a file, with each filter on a separate line in the file, or a search filter can be specified directly on the command-line.
For example, the following filter specifies a search for the common name Babs Jensen:
cn=babs jensen
This search filter returns all entries that contain the common name Babs Jensen. Searches for common name values are not case sensitive.
When the common name attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match this filter:
cn: babs jensen cn;lang-fr: babs jensen
For a list of all the supported language tags, see Table D.1, “Supported Locales”.
The basic syntax of a search filter is:
attribute operator value
For example:
buildingname>=alpha
In this example, buildingname is the attribute, >= is the operator, and alpha is the value. Filters can also be defined that use different attributes combined together with Boolean operators.
Search filters are described in detail in the following sections:
When searching for an entry, the attributes associated with that type of entry can be specified, such as using the cn attribute to search for people with a specific common name.
Examples of attributes that people entries include are the following:
cn for the person's common name.
sn for the person's surname, last name, or family name.
telephoneNumber for the person's telephone number.
buildingName for the name of the building in which the person resides.
l for the physical location of the person.
The operators that can be used in search filters are listed in Table B.1, “Search Filter Operators”. In addition to these search filters, special filters can be specified to work with a preferred language collation order. For information on how to search a directory with international charactersets, see Section B.4, “Searching an Internationalized Directory”.
| Search Type | Operator | Description |
|---|---|---|
| Equality | = |
Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson
|
| Substring | =string* string |
Returns entries containing attributes containing the specified substring. For example, cn=Bob* cn=*Johnson cn=*John* cn=B*John. The asterisk (*) indicates zero (0) or more characters.
|
| Greater than or equal to | >= |
Returns entries containing attributes that are greater than or equal to the specified value. For example, buildingname >= alpha.
|
| Less than or equal to | <= |
Returns entries containing attributes that are less than or equal to the specified value. For example, buildingname <= alpha.
|
| Presence | =* |
Returns entries containing one or more values for the specified attribute. For example, cn=* telephonenumber=* manager=*.
|
| Approximate | ~= |
Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, cn~=suret l~=san fransico could return cn=sarette l=san francisco.
|
Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows:
(Boolean-operator(filter)(filter)(filter)...)
Boolean-operator is any one of the Boolean operators listed in Table B.2, “Search Filter Boolean Operators”.
Boolean operators can be combined and nested together to form complex expressions, such as:
(Boolean-operator(filter)((Boolean-operator(filter)(filter)))
The Boolean operators available for use with search filters include the following:
| Operator | Symbol | Description |
|---|---|---|
| AND | & | All specified filters must be true for the statement to be true. For example, (&(filter)(filter)(filter)...). |
| OR | | | At least one specified filter must be true for the statement to be true. For example, (|(filter)(filter)(filter)...) |
| NOT | ! |
The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, (!(filter)).
|
Boolean expressions are evaluated in the following order:
Innermost to outermost parenthetical expressions first.
All expressions from left to right.
The following filter searches for entries containing one or more values for the manager attribute. This is also known as a presence search:
manager=*
The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:
cn=Ray Kultgen
The following filter returns all entries that do not contain the common name Ray Kultgen:
(!(cn=Ray Kultgen))
The following filter returns all entries that contain a description attribute that contains the substring X.500:
description=*X.500*
The following filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:
(&(ou=Marketing)(!(description=*X.500*)))
The following filter returns all entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:
(&(ou=Marketing)(|(manager=cn=Julie Fulmer,ou=Marketing,dc=example,dc=com)
(manager=cn=Cindy Zwaska,ou=Marketing,dc=example,dc=com)))
The following filter returns all entries that do not represent a person:
(!(objectClass=person))
The following filter returns all entries that do not represent a person and whose common name is similar to printer3b:
(&(!(objectClass=person))(cn~=printer3b))