14.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.
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.

Note

When performing a substring search using a matching rule filter, use the asterisk (*) character as a wildcard to represent zero or more characters.
For example, to search for an attribute value that starts with the letter l and ends with the letter n, enter a l*n in the value portion of the search filter. Similarly, to search for all attribute values beginning with the letter u, enter a value of u* in the value portion of the search filter.
To search for a value that contains the asterisk (*) character, the asterisk must be escaped with the designated escape sequence, \5c2a. For example, to search for all employees with businessCategory attribute values of Example*Net product line, enter the following value in the search filter:
Example\5c2a*Net product line

Note

A common mistake is to assume that the directory is searched based on the attributes used in the distinguished name. The distinguished name is only a unique identifier for the directory entry and cannot be used as a search key. Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is uid=user_name,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless the dc attribute exists in this entry and is set to example.

14.3.1. Using Attributes in Search Filters

The most basic sort of search looks for the presence of attributes or specific values in entries. There are many variations on how to look for attributes in entries. It is possible to check that the attribute merely exists, to match an exact value, or to list matches against a partial value.
A presence search uses a wild card (an asterisk) to return every entry which has that attribute set, regardless of value. For example, this returns every entry which has a manager attribute:
"(manager=*)"
It is also possible to search for an attribute with a specific value; this is called an equality search. For example:
"(cn=example)"
This search filter returns all entries that contain the common name set to example. Most of the time, equality searches are not case sensitive.
When an attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match the "(cn=example)" filter:
cn: example
cn;lang-fr: example
It is also possible to search for a partial match on an attribute value, a substring index. For example:
"(description=*X.500*)"
"(sn=*nderson)"
"(givenname=car*)"
The length of the substring searches is configured in the substring index itself, as described in Section 13.6, “Changing the Width for Indexed Substring Searches”.

14.3.2. Using Operators in Search Filters

Operators in search filters set the relationship between the attribute and the given search value. For people searches, operators can be used to set a range, to return a last names within a subset of letters in the alphabet or employee numbers that come after a certain number.
"(employeeNumber>=500)"
"(sn~=suret)"
"(salary<=150000)"
Operators also enable phonetic and approximate searches, which allow more effective searches with imperfect information and are particularly useful in internationalized directories.
The operators that can be used in search filters are listed in Table 14.2, “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 D.4, “Searching an Internationalized Directory”.

Table 14.2. Search Filter Operators

Search Type Operator Description
Equality = Returns entries containing attribute values that exactly match the specified value. For example, cn=example
Substring =string* string Returns entries containing attributes containing the specified substring. For example, cn=exa*l. 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, uidNumber >= 5000.
Less than or equal to <= Returns entries containing attributes that are less than or equal to the specified value. For example, uidNumber <= 5000.
Presence =* Returns entries containing one or more values for the specified attribute. For example, cn=*.
Approximate ~= Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, l~=san fransico can return l=san francisco.

14.3.3. Using Compound Search Filters

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 14.3, “Search Filter Boolean Operators”.
For example, this filter returns all entries that do not contain the specified value:
(!(objectClass=person))
Obviously, compound search filters are most useful when they are nested together into completed expressions:
(Boolean-operator(filter)((Boolean-operator(filter)(filter)))
These compound filters can be combined with other types of searches (approximate, substring, other operators) to get very detailed results. For example, this filter returns all entries whose organizational unit is Marketing and whose description attribute does not contain the substring X.500:
(&(ou=Marketing)(!(description=*X.500*)))
That filter can be expanded to return entries whose organizational unit is Marketing, that do not have the substring X.500, and that have example or demo set as a manager:
(&(ou=Marketing)(!(description=*X.500*))(|(manager=cn=example,ou=Marketing,dc=example,dc=com)(manager=cn=demo,ou=Marketing,dc=example,dc=com)))
This filter returns all entries that do not represent a person and whose common name is similar to printer3b:
(&(!(objectClass=person))(cn~=printer3b))

Table 14.3. Search Filter Boolean Operators

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.

14.3.4. Using Matching Rules

A matching rule tells the Directory Server how to compare two values (the value stored in the attribute and the value in the search filter). A matching rule also defines how to generate index keys. Matching rules are somewhat related to attribute syntaxes. Syntaxes define the format of an attribute value; matching rules define how that format is compared and indexed.
There are three different types of matching rules:
  • EQUALITY specifies how to compare two values for an equal match. For example, how to handle strings like "Fred" and "FRED". Search filters that test for equality (for example, attribute=value) use the EQUALITY rule. Equality (eq) indexes use the EQUALITY rule to generate the index keys. Update operations use the EQUALITY rule to compare values to be updated with values already in an entry.
  • ORDERING specifies how to compare two values to see if one value is greater or less than another value. Search filters that set a range (for example, attribute<=value or attribute>=value) use the ORDERING rule. An index for an attribute with an ORDERING rule orders the equality values.
  • SUBSTR specifies how to do substring matching. Substring search filters (for example, attribute=*partial_string* or attribute=*end_string) use the SUBSTR rule. Substring (sub) indexes use the SUBSTR rule to generate the index keys.

Important

A matching rule is required in order to support searching or indexing for the corresponding search filter or index type. For example, an attribute must have an EQUALITY matching rule in order to support equality search filters and eq indexes for that attribute. An attribute must have both an ORDERING matching rule and an EQUALITY matching rule in order to support range search filters and indexed range searches.
A search operation will be rejected with PROTOCOL_ERROR or UNWILLING_TO_PERFORM if an attempt is made to use a search filter for an attribute that has no corresponding matching rule.

Example 14.1. Matching Rules and Custom Attributes

Example Corp. administrators create a custom attribute type called MyFirstName with IA5 String (7-bit ASCII) syntax and an EQUALITY matching rule of caseExactIA5Match. An entry with a MyFirstName value of Fred is returned in a search with a filter of (MyFirstName=Fred), but it is not returned for filters like (MyFirstName=FRED) and (MyFirstName=fred) Fred, FRED, and fred are all valid IA5 String values, but they do not match using the caseExactIA5Match rule.
For all three variants of Fred to be returned in a search, then the MyFirstName should be defined to use the caseIgnoreIA5Match matching rule.
An extensible matching rule search filter can be used to search for an attribute value with a different matching rule than the one defined for the attribute. The matching rule must be compatible with the syntax of the attribute being searched. For example, to run a case insensitive search for an attribute that has a case-sensitive matching rule defined for it, specify a case insensitive matching rule in the search filter.
(MyFirstName:caseIgnoreIA5Match:=fred)

Note

Matching rules are used for searches in internationalized directories, to specify the language types to use for the results. This is covered in Section D.4, “Searching an Internationalized Directory”.

Note

An index for an attributes uses whatever matching rules are defined for that attribute in its schema definition. Additional matching rules to use for an index can be configured using the nsMatchingRule attribute, as in Section 13.2.1, “Creating Indexes Using the Command Line”.
The syntax of the matching rule filter inserts a matching rule name or OID into the search filter:
attr:matchingRule:=value
  • attr is an attribute belonging to entries being searched, such as cn or mail.
  • matchingRule is a string that contains the name or OID of the rule to use to match attribute values according to the required syntax.
  • value is either the attribute value to search for or a relational operator plus the attribute value to search for. The syntax of the value of the filter depends on the matching rule format used.
A matching rule is actually a schema element, and, as with other schema elements is uniquely identified by an object identifier (OID).
Many of the matching rules defined for Red Hat Directory Server relate to language codes and set internationalized collation orders supported by the Directory Server. For example, the OID 2.16.840.1.113730.3.3.2.17.1 identifies the Finnish collation order.

Note

Unlike other schema elements, additional matching rules cannot be added to the Directory Server configuration.
Most of the matching rules list in following list are used for equality indexes. Matching rules with ordering in their name are used for ordering indexes, and those with substring in their name are used for substring (SUBSTR) indexes. (The matching rules used for international matching and collation orders use a different naming scheme.)
Bitwise AND match
Performs bitwise AND matches.
OID: 1.2.840.113556.1.4.803
Compatible syntaxes: Typically used with Integer and numeric strings. Directory Server converts numeric strings automatically to integer.
Bitwise OR match
Performs bitwise OR matches.
OID: 1.2.840.113556.1.4.804
Compatible syntaxes: Typically used with Integer and numeric strings. Directory Server converts numeric strings automatically to integer.
booleanMatch
Evaluates whether the values to match are TRUE or FALSE
OID: 2.5.13.13
Compatible syntaxes: Boolean
caseExactIA5Match
Makes a case-sensitive comparison of values.
OID: 1.3.6.1.4.1.1466.109.114.1
Compatible syntaxes: IA5 Syntax, URI
caseExactMatch
Makes a case-sensitive comparison of values.
OID: 2.5.13.5
Compatible syntaxes: Directory String, Printable String, OID
caseExactOrderingMatch
Allows case-sensitive ranged searches (less than and greater than).
OID: 2.5.13.6
Compatible syntaxes: Directory String, Printable String, OID
caseExactSubstringsMatch
Performs case-sensitive substring and index searches.
OID: 2.5.13.7
Compatible syntaxes: Directory String, Printable String, OID
caseIgnoreIA5Match
Performs case-insensitive comparisons of values.
OID: 1.3.6.1.4.1.1466.109.114.2
Compatible syntaxes: IA5 Syntax, URI
caseIgnoreIA5SubstringsMatch
Performs case-insensitive searches on substrings and indexes.
OID: 1.3.6.1.4.1.1466.109.114.3
Compatible syntaxes: IA5 Syntax, URI
caseIgnoreListMatch
Performs case-insensitive comparisons of values.
OID: 2.5.13.11
Compatible syntaxes: Postal address
caseIgnoreListSubstringsMatch
Performs case-insensitive searches on substrings and indexes.
OID: 2.5.13.12
Compatible syntaxes: Postal address
caseIgnoreMatch
Performs case-insensitive comparisons of values.
OID: 2.5.13.2
Compatible syntaxes: Directory String, Printable String, OID
caseIgnoreOrderingMatch
Allows case-insensitive ranged searches (less than and greater than).
OID: 2.5.13.3
Compatible syntaxes: Directory String, Printable String, OID
caseIgnoreSubstringsMatch
Performs case-insensitive searches on substrings and indexes.
OID: 2.5.13.4
Compatible syntaxes: Directory String, Printable String, OID
distinguishedNameMatch
Compares distinguished name values.
OID: 2.5.13.1
Compatible syntaxes: Distinguished name (DN)
generalizedTimeMatch
Compares values that are in a Generalized Time format.
OID: 2.5.13.27
Compatible syntaxes: Generalized Time
generalizedTimeOrderingMatch
Allows ranged searches (less than and greater than) on values that are in a Generalized Time format.
OID: 2.5.13.28
Compatible syntaxes: Generalized Time
integerMatch
Evaluates integer values.
OID: 2.5.13.14
Compatible syntaxes: Integer
integerOrderingMatch
Allows ranged searches (less than and greater than) on integer values.
OID: 2.5.13.15
Compatible syntaxes: Integer
keywordMatch
Compares the given search value to a string in an attribute value.
OID: 2.5.13.33
Compatible syntaxes: Directory String
numericStringMatch
Compares more general numeric values.
OID: 2.5.13.8
Compatible syntaxes: Numeric String
numericStringOrderingMatch
Allows ranged searches (less than and greater than) on more general numeric values.
OID: 2.5.13.9
Compatible syntaxes: Numeric String
numericStringSubstringMatch
Compares more general numeric values.
OID: 2.5.13.10
Compatible syntaxes: Numeric String
objectIdentifierMatch
Compares object identifier (OID) values.
OID: 2.5.13.0
Compatible syntaxes: OID
octetStringMatch
Evaluates octet string values.
OID: 2.5.13.17
Compatible syntaxes: Octet String
octetStringOrderingMatch
Supports ranged searches (less than and greater than) on a series of octet string values.
OID: 2.5.13.18
Compatible syntaxes: Octet String
telephoneNumberMatch
Evaluates telephone number values.
OID: 2.5.13.20
Compatible syntaxes: Telephone Number
telephoneNumberSubstringsMatch
Performs substring and index searches on telephone number values.
OID: 2.5.13.21
Compatible syntaxes: Telephone Number
uniqueMemberMatch
Compares both name and UID values.
OID: 2.5.13.23
Compatible syntaxes: Name and Optional UID
wordMatch
Compares the given search value to a string in an attribute value. This matching rule is case-insensitive.
OID: 2.5.13.32
Compatible syntaxes: Directory String

Table 14.4. Language Ordering Matching Rules

Matching Rule Object Identifiers (OIDs)
English (Case Exact Ordering Match) 2.16.840.1.113730.3.3.2.11.3
Albanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.44.1
Arabic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.1.1
Belorussian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.2.1
Bulgarian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.3.1
Catalan (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.4.1
Chinese - Simplified (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.49.1
Chinese - Traditional (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.50.1
Croatian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.22.1
Czech (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.5.1
Danish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.6.1
Dutch (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.33.1
Dutch - Belgian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.34.1
English - US (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.11.1
English - Canadian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.12.1
English - Irish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.14.1
Estonian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.16.1
Finnish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.17.1
French (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.18.1
French - Belgian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.19.1
French - Canadian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.20.1
French - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.21.1
German (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.7.1
German - Austrian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.8.1
German - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.9.1
Greek (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.10.1
Hebrew (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.27.1
Hungarian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.23.1
Icelandic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.24.1
Italian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.25.1
Italian - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.26.1
Japanese (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.28.1
Korean (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.29.1
Latvian, Lettish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.31.1
Lithuanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.30.1
Macedonian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.32.1
Norwegian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.35.1
Norwegian - Bokmul (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.36.1
Norwegian - Nynorsk (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.37.1
Polish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.38.1
Romanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.39.1
Russian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.40.1
Serbian - Cyrillic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.45.1
Serbian - Latin (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.41.1
Slovak (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.42.1
Slovenian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.43.1
Spanish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.15.1
Swedish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.46.1
Turkish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.47.1
Ukrainian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.48.1

Table 14.5. Language Substring Matching Rules

Matching Rule Object Identifiers (OIDs)
English (Case Exact Substring Match) 2.16.840.1.113730.3.3.2.11.3.6
Albanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.44.1.6
Arabic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.1.1.6
Belorussian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.2.1.6
Bulgarian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.3.1.6
Catalan (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.4.1.6
Chinese - Simplified (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.49.1.6
Chinese - Traditional (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.50.1.6
Croatian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.22.1.6
Czech (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.5.1.6
Danish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.6.1.6
Dutch (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.33.1.6
Dutch - Belgian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.34.1.6
English - US (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.11.1.6
English - Canadian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.12.1.6
English - Irish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.14.1.6
Estonian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.16.1.6
Finnish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.17.1.6
French (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.18.1.6
French - Belgian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.19.1.6
French - Canadian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.20.1.6
French - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.21.1.6
German (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.7.1.6
German - Austrian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.8.1.6
German - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.9.1.6
Greek (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.10.1.6
Hebrew (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.27.1.6
Hungarian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.23.1.6
Icelandic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.24.1.6
Italian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.25.1.6
Italian - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.26.1.6
Japanese (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.28.1.6
Korean (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.29.1.6
Latvian, Lettish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.31.1.6
Lithuanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.30.1.6
Macedonian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.32.1.6
Norwegian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.35.1.6
Norwegian - Bokmul (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.36.1.6
Norwegian - Nynorsk (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.37.1.6
Polish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.38.1.6
Romanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.39.1.6
Russian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.40.1.6
Serbian - Cyrillic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.45.1.6
Serbian - Latin (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.41.1.6
Slovak (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.42.1.6
Slovenian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.43.1.6
Spanish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.15.1.6
Swedish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.46.1.6
Turkish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.47.1.6
Ukrainian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.48.1.6