Using Advanced Query Syntax Programmatically
Advanced Query Syntax (AQS) is the default query syntax used by Windows Search to query the index and to refine and narrow search parameters. AQS is employed by developers to build queries programmatically (and by users to narrow their search parameters). Canonical AQS was introduced in Windows 7 and must be used in Windows 7 and later to programmatically generate AQS queries.
This topic is organized as follows:
- About Advanced Query Syntax
- Keyword Use in Local Languages
- Canonical Advanced Query Syntax in Windows 7
- Scope Restrictions
- Additional Resources
- Related topics
About Advanced Query Syntax
A query consists of basic queries connected with AND, OR, and NOT, as shown in the following example syntax:
<query> ::=
<basic query>
| ( <query> )
| <query> AND <query>
| <query> <query> // Same as <query> AND <query>
| <query> OR <query>
| NOT <query>
Note
AQS is not case sensitive, with the exception of AND, OR, and NOT, which must be in all uppercase.
If a query has two or more uses of AND or OR, they will bind from left to right, regardless of whether it is AND or OR. That is, the query, "apple AND pear OR plum" will be interpreted as if it were written as "(apple AND pear) OR plum", and the query, "apple OR pear AND plum", will be interpreted as if it were written as "(apple OR pear) AND plum". So if a document contains the word plum but neither apple, nor pear, the first query will return it but the second query will not. Hence, we recommend that you use explicit parentheses for any query that mixes AND and OR to avoid mistakes or misinterpretations.
A basic query searches for items that satisfy a restriction over a property. The only required portion of a basic query is the restriction or search value. If you do not specify a property, Windows Search searches all properties.
The following forms for a basic query are valid: A property is designated by a keyword such as author or size, or by a canonical property name such as System.DateModified. Valid forms for a property are as follows: An operator indicates an operation such as < or =. For a list of valid operators, see the Query Operators section later in this topic. A basic restriction is a simple restriction on a property that can be written without parentheses: A restriction is a search value such as a number value or string value, optionally with an operator. Valid forms for a restriction are as follows: If you do not specify an operator, Windows Search chooses the most appropriate operator for your query: For the programmatic use of AQS, we recommend that you always have an explicit operator. The valid form for searching a simple value or value range is as follows: A simple value can consist of any of the following types: A query that searches for a document containing the phase "last quarter," authored by Theresa or Lee, and that was saved to the folder MyDocs, combines three basic queries as follows: The three basic queries are: A basic query that uses canonical syntax is: Properties are referred to by a keyword, which can be a canonical property name in Windows 7 and later. AQS in the Windows UI can use the label instead of the canonical property name, such as author instead of System.Author. In Windows Vista and earlier it was possible to use English labels regardless of the UI language. In Windows 7 and later, Windows Search recognizes keywords in the current default UI language only. In Windows Vista and earlier, custom properties were not available in AQS. In Windows 7 and later, AQS works with custom properties that are registered with the property system. For more information on creating custom properties, see Property System. As of Windows 8, DateTime properties (like System.DateModified) support the canonical date and time format specified by ISO-8601, optionally including the UTC time zone. Windows 8 and earlier, date-time without UTC time zone: YYYY-MM-DDThh:mm:ss This format specifies a local time, regardless of the user or system locale. Windows 8, date-time with UTC time zone: YYYY-MM-DDThh:mm:ssTZD This format specifies a time at the specified UTC time zone. In Windows 7 and later, mnemonic keywords work in the system language only, such as German keywords only on a German operating system, and English keywords only on an English operating system. System.Author is a canonical keyword, and the mnemonic value for the System.Author property is Author, for example. The introduction of canonical keywords compensates for the fact that English mnemonic keywords are no longer universally recognized on all operating systems regardless of language, as was the case in Windows Vista and earlier. Note In Windows 7 and later, Windows Search recognizes keywords in the current default language only, and not in English unless English is the current default. We recommend that developers always use canonical syntax so that their application won't have language problems with keywords. Canonical syntax was introduced for keywords in Windows 7. An example of a query with a canonical property is The conventions for canonical keyword syntax are as follows: Note There is no canonical syntax for numbers in Windows 7 and later. Because floating point formats vary among locales, the use of a canonical query that involves a floating point constant is not supported. Integer constants, in contrast, can be written using only digits (no separators for thousands) and can be safely used in canonical queries in Windows 7 and later. The following table shows some examples of canonical properties and the syntax for using them. For more information about canonical properties and the property system generally, see System Properties. Alternatively, refer to the public header files. If a property, p, has multiple values for some item, an AQS query for p:
The syntax listed in the following table consists of an operator, operator symbol, example and example description. The operator and symbol can be used in any language and included in any query. Do not use the COP_IMPLICIT or COP_APPLICATION_SPECIFIC operators. Some of the operators have interchangeable symbols. ¹ Empty square brackets ([]) denote "no value". For string properties the default operation is either COP_WORD_STARTS_WITH or COP_WORD_EQUAL. Useful examples of how query values can be restricted are listed in the following table. Users can limit the scope of their searches to specific folder locations or data stores. For example, if you use several email accounts and you want to limit a query to either Microsoft Outlook or Microsoft Outlook Express, you can use <basic query> ::=
<prop>:<basic restr>
| <restr>
<prop> ::=
<canonical property name>
| <property label in UI language>
<basic restr> ::=
<value>
| <op><value>
| NOT <basic restr>
| ( <restr> )
<restr> ::=
<basic restr>
| <restr> AND <restr>
| <restr> <restr> // Same as <restr> AND <restr>
| <restr> OR <restr>
<value> ::=
<simplevalue>
| <simplevalue> .. <simplevalue>
<simplevalue> ::=
[] // No value, or a null value
| <word> // A sequence of characters without whitespace
| <number> // An integer or a floating point number
| <datetime> // A relative date, or an absolute date and/or time
| <Boolean>
| "..." // A phrase
| <enumeration range>
Examples
"last quarter" author:(theresa OR lee) folder:MyDocs
System.Size:>1kb
Properties
Support for Custom Properties
DateTime properties in Windows 8
Keyword Use in Local Languages
Canonical Advanced Query Syntax in Windows 7
System.Message.FromAddress:=me@microsoft.com
. When coding queries in applications running on Windows 7 and later, you must use canonical syntax to programmatically generate AQS queries. If you do not use canonical syntax and your application is deployed in a locale or UI language different from the language in the application code, your queries will not be interpreted correctly.
System.Photo.LightSource
. Canonical names are not case sensitive.P
has enumerated values or ranges named N₁ through Nₖ, the canonical syntax for the Ith value or range is the canonical name for P, followed by the character #, followed by NI, as illustrated in the following example:
System.Photo.LightSource#Daylight
, System.Photo.LightSource#StandardA
, and so forth.
System.Devices.LaunchDeviceStageFromExplorer:=System.StructuredQueryType.Boolean#True
System.Author:sanjay
System.Keywords:"Animal"
System.FileCount:>100
Examples
Type of canonical property
Example
Syntax
String value
System.Author
The string value is searched for in the author property:
System.Author:Jacobs
Enumeration range
System.Priority
The priority property can have a numerical value range:
System.Priority:System.Priority#High
Boolean
System.IsDeleted
Boolean values can be used with any Boolean property:
System.IsDeleted:System.StructuredQueryType.Boolean#True
, and System.IsDeleted:System.StructuredQueryType.Boolean#False
Numerical
System.Size
It is not possible to write safely a canonical query that involves a floating point constant, because floating point formats vary among locales. Integers must be written with no separators for thousands. For example:
System.Size:<12345
Query Operators
Operator
Symbol
Example
Description
COP_EQUAL
=
System.FileExtension:=".txt"
The value is the string ".txt".
COP_NOTEQUAL
≠
-
<>
NOT
- -System.Kind:≠picture
System.Photo.DateTaken:-[]¹
System.Kind:<>picture
System.Kind:NOT picture
System.Kind:- -pictureThe System.Kind property is not a picture.
The System.Photo.DateTaken property has a value.
The System.Kind property is not a picture.
The System.Kind property is not a picture.
Double NOT operators applied to the same property do not cancel out. Hence, System.Kind:- -picture is equivalent to System.Kind:-picture and System.Kind:NOT picture.
COP_LESSTHAN
System.Size:<>
This value is less than 1kb.
COP_GREATERTHAN
>
System.ItemDate:>System.StructuredQueryType.DateTime#Today
This value is greater than today.
COP_LESSTHANOREQUAL
<>
≤System.Size:<>
This value is less than or equal to 1kb.
COP_GREATERTHANOREQUAL
>=
≥System.Size:>=1kb
This value is equal to or greater than 1kb.
COP_VALUE_STARTSWITH
~
System.FileName:~<"c++>"c++>
Finds items where the file name begins with the characters "C++ Primer".
COP_VALUE_ENDSWITH
~>
System.Photo.CameraModel:~>non
Finds items where the property value ends with the characters non.
COP_VALUE_CONTAINS
~=
~~System.Subject.~=round
System.Search.Autosummary:~~roundFinds a message that has this string in the subject, and will match "ground rules" for example.
Finds all items with an Autosummary that contains the characters round.
COP_VALUE_NOTCONTAINS
~!
System.Author:~!"sanjay"
Finds authors that do not have the character sequence"sanjay" in them.
COP_DOSWILDCARDS
~
System.FileName:~"Mic?osoft W*d"
Finds files where the file name starts with Mic, followed by some character, followed by osoft w, followed by any characters ending with d.
The ? and * characters are not interpreted literally, and work like DOS-style wildcard characters:
COP_WORD_EQUAL
$=
$$System.StructuredQuery.Virtual.From:$="Sanjay Jacobs"
For Windows 7 and later. Finds the phrase "Sanjay Jacobs" in all From properties. The word Sanjay must be followed by the word Jacobs.
COP_WORD_STARTSWITH
$
System.Author:$<"san">"san"><"micro>"micro>
For Windows 7 and later. Finds any item where Author contains a word starting with the characters "San".
Finds any file in which the file name contains a word starting with micro, followed by a word starting with exe.Query Values
Value/symbol
Examples
Description
String
auto
Any sequence of characters that can be searched for. The string must not contain whitespace or character combinations that are part of the syntax. This example searches for a word beginning with auto.
Quoted string ""
"Conclusions: valid" "The ""blue"" team"
Any sequence of characters. The string is not interpreted as part of the syntax.
Quotation marks can be included in a query if they are doubled. This example searches for The "blue" team.
Integer
5678
Use only digits for integers. Do not use any separators for thousands.
Floating point number
5678.1234
Because floating point formats vary among locales, a canonical query cannot use a floating point constant. The use of canonical syntax with floating point numbers is not localization safe.
Boolean true/false
System.IsRead:=System.StructuredQueryType.Boolean#True
System.IsEncrypted:-System.StructuredQueryType.Boolean#FalseThe TRUE Boolean value.
The FALSE Boolean value.
[]
System.Keywords:=[]
Empty square brackets denote that there is no value. This example finds all items that have not been tagged.
Absolute dates
System.ItemDate:1/26/2010
SystemDateModified 10/15/2002 19:00Finds items with a date of 26 January 2010.
Finds items that were modified on 15 October 2002 between the hours 19:00:00 and 19:00:59.
[!Note]
Because date formats (like floating point formats) vary among locales, the use of canonical syntax with absolute dates is not supported and is not localization safe.
Relative dates
System.ItemDate:System.StructuredQueryType.DateTime#Today
System.DateAcquired:System.StructuredQueryType.DateTime#NextMonth
System.Message.DateReceived:System.StructuredQueryType.DateTime#LastYearFinds items with today's date.
Finds items with a date in the next month.
Finds items with a date in the last year.
[!Note]
In addition to searching on specific dates and date ranges, AQS recognizes relative date values (like today, tomorrow, nextweek, nextmonth), and day (like Tuesday or Monday..Wednesday), and month (February).
..
System.ItemDate:11/05/04..11/10/04 System.Size:5kb..10kb
Double periods indicate a value range. Finds items with a date between 11/05/04 and 11/10/04, inclusive.
Finds items between 5 and 10kb in size.Scope Restrictions
System.Search.Store:mapi
or System.Search.Store:oe
respectively. The following table shows some examples of how to restrict a search by data store.
Restrict search by data store
Keyword
Example
Files
file
System.Search.Store:file
Outlook
mapi
System.Search.Store:mapi
Outlook Express
oe
System.Search.Store:oe
Offline files
csc
System.Search.Store:csc
Specific folder on local drive
folder
System.ItemFolderNameDisplay:C:"\MyFolder"
Additional Resources
Related topics