Understanding Search Criteria

Base DN. By specifying the base DN, you are defining the topmost distinguished name (DN) or starting point in the directory to conduct the search. All searches begin at or below the base DN, depending on the scope, and move down the tree, never upwards. Examples of base DNs are: dc=example,dc=com and ou=People,dc=example,dc=com.
Scope. The scope determines which set of entries at or below the base DN should be evaluated by the search filter. The search scope and base DN together indicate "where" to look for entries in the directory.
Search filter. The search filter specifies the conditions that the entries must meet to be returned to the client.

Specifying Filter Types and Operators

The directory server provides seven types of search filters, defined in the LDAP protocol. With each search filter type, you use operators that test the relationships between two entities, attribute and value.

The following table shows how search filters are used to return specific entries in a search query.

Search Filter	Operator	Description
Presence	`attr=*`	Return all entries that have any value associated with the specified attribute. The filter uses the wildcard character to denote zero or more characters in the string. For example, the following filter is common and returns all entries that have an object class with any value, which every entry has: `(objectclass=\)`. Note -* the LDAP protocol specifies that filters should have the form "(filter)", which includes parentheses surrounded by quotation marks. Although most directory servers accept filters without the parentheses and quotation marks, it is good practice to include them.
Equality	`attr=value`	Return entries containing attributes equal to a specified value. For example: `(sn=Bergin)` returns all entries that have a surname (`sn`) attribute with the value of `Bergin`. Note - The `sn` value is case insensitive, so entries associated with `sn=bergin` or `sn=Bergin` will be returned.
Substring	`attr=<initial-string><any substring><final-string>`	Return entries with attributes containing a specified substring or partial substring. The filter uses the wildcard character to denote zero or more characters in the string. Run an initial substring search that looks for all attribute values that have the characters `Ber` at the start of the string: `(sn=Ber\)` Specify the middle substring of an attribute value. For example: `(sn=\erg\)` Specify the end of a substring of an attribute value. For example: `(sn=\gin)`. Or you can specify some combination of substrings Specify the initial and middle substring: `(sn=ber\gi\)` Specify the initial and ending substrings: `(sn=be\in)` Specify the middle and end substrings: `(sn=\er\in)` Note -* Substring filters do not use true wild cards such as in system listings or regular expressions. Thus, the following filter would be invalid because of too many criteria: `(sn=\B\rg\*n)`.
Greater than or equal to	`attr>=value`	Return entries containing attributes that are greater than or equal to the specified value. For example, `(sn>=Bergin)` returns all entries that have an attribute greater than or equal to the value, `Bergin`, based on the matching rules for attributes (see Understanding Matching Rules in Sun OpenDS Standard Edition 2.0 Architectural Reference).
Less than or equal to	`attr<=value`	Return entries containing attributes that are less than or equal to the specified value. For example, `(sn<=Bergin)` returns all entries that have an attribute less than or equal to the value, `Bergin`, based on the matching rules for attributes.
Approximate	`attr~=value`	Return entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example: `(sn~=Bergan)` could return the entry associated with `(sn=Bergin)` or `(sn=Bergan)`. The Approximate search filter works only with English language strings. It does not work with non-ASCII-based strings, such as Ja or Zn.
Extensible match	`attr= attr [":dn"] [":" matchingrule] ":=" value Or:[:dn] ":" matchingrule ":=" value`	Return the results entries when an attribute equals the value with the specified matching rule. LDAP version 3 enables you to build match operators and rules for a particular attribute. Matching rules define how to compare attribute values with a particular syntax. In other words, an extensible search filter enables you to add a matching rule to a search filter. For example, the following search filter compares entries containing the surname attribute with value equal to "`Jensen`" by using the matching rule designated by OID 2.5.13.5: `(sn:2.5.13.5:=Jensen)`. Another example illustrates the use of the `":dn"` notation to indicate that the OID `2.5.13.5` should be used when making comparisons, and that the attributes of an entry should be considered part of the entry when evaluating the match:`(sn:dn:2.5.13.5:=Jensen)`

Using Compound Search Filters

Multiple search filter components can be combined and evaluated by using the operator:

(Boolean-Operator(filter)(filter)(filter))

Boolean operators can be combined and nested together to form complex expressions:

(Boolean-Operator(filter)(Boolean-operator(filter)(filter)))

The following table describes the Boolean operators.

Search Filter	Operator	Description
AND	`(&(filter)(filter))`	All specified filters must be true for the statement to be true. For example, `(&(sn=Carter)(l=Cupertino))` returns all entries that have the surname attribute equal to "Carter" and the location attribute equal to `Cupertino` if any.
OR	`(\|(filter)(filter))`	At least one specified filter must be true for the statement to be true. For example, `(\|(sn=Carter)(l=Cupertino))` returns all entries that have the surname attribute equal to "Carter" or the location attribute equal to `Cupertino` if any.
NOT	`(!(filter)(filter))`	The specified filter must not be true for the statement to be true. For example, `(!(sn=Bergin))` returns all entries that do not have a surname attribute equal to the string `Smith`. The filter also returns all entries that do not have the `sn` attribute.

Using UTF-8 Encoding in Search Filters

UTF8 is a byte-order, variable-length character code for Unicode and a subset of ASCII. You use UTF-8 for multiple-language support by replacing each character of a non 7-bit ASCII character with a byte of a UTF-8 encoding. Typically, you must escape the UTF-8 encoding with a backslash.

For example, the character é has a UTF-8 representation of c3a9 and è has a UTF-8 representation c3a8. A UTF-8 encoding is represented with an escaped backslash. So, é is represented as \\c3\\a9 and è is represented as \\c3\\a8. To represent cn=Hélène Laurent, you would use the following encoding:

(cn=H\\c3\\a9l\\c3\\a8ne Laurent)

Using Special Characters in Search Filters

You must specify special characters (for example, a space, backslash, asterisk, comma, period, or others) by using the escape backslash.

Asterisk. Represent an asterisk (*) as \\2a. For example, Five*Star would be represented as "(cn=Five\\2aStar)".
Backslash. Represent a backslash (\) as \\5c. For example, c:\\file would be represented as "(cn=c:\\5c\\5cfile)".
Parentheses. Represent parentheses ( ) as \\28 and \\29, respectively. For example, John Doe (II) would be represented as "(cn=John Doe \\28II\\29)".
Null. Represent null as \\00. For example, 0001 would be represented as "(bin=\\00\\00\\00\\01)".
Comma. Represent a comma (,) by escaping it as \\,. For example, "(cn=Mkt\\,Peru,dc=example,dc=com)".
Space. Generally, use quotation marks around strings that contain a space. For example, (cn="HR Managers,ou=Groups,dc=example,dc=com").

Exit Print View
Sun OpenDS Standard Edition 2.0 Administration Guide