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
  • Examples
  • Properties
• Keyword Use in Local Languages
• Canonical Advanced Query Syntax in Windows 7
  • Examples
  • Query Operators
  • Query Values
• 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>

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. <restr> represents the search restriction.

The following forms for a basic query are valid:

<basic query> ::=
     <prop>:<basic restr>
| <restr>

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:

<prop> ::= 
     <canonical property name>
| <property label in UI language>

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:

<basic restr> ::=
     <value>
| <op><value>
| NOT <basic restr>
| ( <restr> )

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:

<restr> ::=
    <basic restr>
| <restr> AND <restr>
| <restr> <restr>      // Same as <restr> AND <restr>
| <restr> OR <restr>

If you do not specify an operator, Windows Search chooses the most appropriate operator for your query:

• For a string property, the COP_WORD_STARTSWITH $< operator is assumed.
• For all other properties, the COP_EQUAL = operator is assumed.

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:

<value> ::=
    <simplevalue>
| <simplevalue> .. <simplevalue>

A simple value can consist of any of the following types:

<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

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:

"last quarter" author:(theresa OR lee) folder:MyDocs

The three basic queries are:

• "last quarter"
• author:(theresa OR lee)
• folder:MyDocs

A basic query that uses canonical syntax is:

System.Size:>1kb

Properties

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.

Support for Custom Properties

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.

DateTime properties in Windows 8

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.

Keyword Use in Local Languages

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.

Canonical Advanced Query Syntax in Windows 7

Canonical syntax was introduced for keywords in Windows 7. An example of a query with a canonical property is System.Message.FromAddress:[email protected]. 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.

The conventions for canonical keyword syntax are as follows:

• The canonical syntax for a property is its canonical name, such as System.Photo.LightSource. Canonical names are not case sensitive.
• The canonical syntax for the Boolean operators consists of the keywords AND, OR, and NOT, in all uppercase.
• The operators <, >, =, and so forth, are not localized and are thus also part of the canonical syntax.
• If a property 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 N_I, as illustrated in the following example:
  • System.Photo.LightSource#Daylight, System.Photo.LightSource#StandardA, and so forth.
• For a defined semantic type T with values or ranges named N₁ through Nₖ, the canonical syntax for the Ith value or range is the canonical name for T, followed by the character #, followed by N_I, as illustrated in the following example:
  • System.Devices.LaunchDeviceStageFromExplorer:=System.StructuredQueryType.Boolean#True
• For literal values such as words or phrases, the canonical syntax is the same as the regular syntax. Examples of queries with literal values in canonical syntax are:
  • System.Author:sanjay
  • System.Keywords:"Animal"
  • System.FileCount:>100

Examples

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.

Query Operators

If a property, p, has multiple values for some item, an AQS query for p:<restr> returns the item if <restr> is true for at least one of the values. (<restr> represents a restriction.)

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.

Query Values

Useful examples of how query values can be restricted are listed in the following table.

Scope Restrictions

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

Additional Resources

• In Windows 7 and later, a shortcut menu option can be available based on whether an AQS condition is met. For more information, see "Getting Dynamic Behavior for Static Verbs by Using Advanced Query Syntax" in Creating Context Menu Handlers.
• AQS queries can be limited to specific types of files, which are known as file kinds. For more information, see File Types and Associations. For property reference documentation, see System.Kind, and System.KindText.

Related topics

Querying the Index Programmatically

Using SQL and AQS Approaches to Query the Index

Querying the Index with ISearchQueryHelper

Querying the Index with the search-ms Protocol

Querying the Index with Windows Search SQL Syntax