Search Filter Syntax

Search filters enable you to define search criteria and provide more efficient and effective searches.

ADSI supports the LDAP search filters as defined in RFC2254. These search filters are represented by Unicode strings. The following table lists some examples of LDAP search filters.

These search filters use one of the following formats.

<filter>=(<attribute><operator><value>)

or

(<operator><filter1><filter2>)

The ADSI search filters are used in two ways. They form a part of the LDAP dialect for submitting queries through the OLE DB provider. They are also used with the IDirectorySearch interface.

Operators

The following table lists some frequently used search filter operators.

Wildcards

You can also add wildcards and conditions to an LDAP search filter. The following examples show substrings that can be used to search the directory.

Get all entries:

(objectClass=*)

Get entries containing 'bob' somewhere in the common name:

(cn=*bob*)

Get entries with a common name greater than or equal to 'bob':

(cn>='bob')

Get all users with an e-mail attribute:

(&(objectClass=user)(email=*))

Get all user entries with an e-mail attribute and a surname equal to 'smith':

(&(sn=smith)(objectClass=user)(email=*))

Get all user entries with a common name that starts with 'andy', 'steve', or 'margaret':

(&(objectClass=user) | (cn=andy*)(cn=steve)(cn=margaret))

Get all entries without an e-mail attribute:

(!(email=*))

The formal definition of the search filter is as follows (from RFC 1960):

<filter> ::= '(' <filtercomp> ')'
<filtercomp> ::= <and> | <or> | <not> | <item>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter> | <filter> <filterlist>
<item> ::= <simple> | <present> | <substring>
<simple> ::= <attr> <filtertype> <value> 
<filtertype> ::= <equal> | <approx> | <ge> | <le>
<equal> ::= '='
<approx> ::= '~='
<ge> ::= '>='
<le> ::= '<='
<present> ::= <attr> '=*'
<substring> ::= <attr> '=' <initial> <any> <final>
<initial> ::= NULL | <value>
<any> ::= '*' <starval>
<starval> ::= NULL | <value> '*' <starval>
<final> ::= NULL | <value>

If a <value> must contain one of the characters * or ( or ), the character should be preceded by the backslash escape character (\).

Special Characters

If any of the following special characters must appear in the search filter as literals, they must be replaced by the listed escape sequence.

In addition, arbitrary binary data may be represented using the escape sequence syntax by encoding each byte of binary data with the backslash (\) followed by two hexadecimal digits. For example, the four-byte value 0x00000004 is encoded as \00\00\00\04 in a filter string.