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. <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.
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 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:=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.
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
Phas 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.
- 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 NI, 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:sanjaySystem.Keywords:"Animal"System.FileCount:>100
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.
Examples
The following table shows some examples of canonical properties and the syntax for using them.
| 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 |
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.
| 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:- -picture |
The 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:<1kb |
This value is less than 1kb. |
| COP_GREATERTHAN | > |
System.ItemDate:>System.StructuredQueryType.DateTime#Today |
This value is greater than today. |
| COP_LESSTHANOREQUAL | <= ≤ |
System.Size:<=1kb |
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++ Primer" |
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:~~round |
Finds 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" System.Filename:$<"Micro Exe" |
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. |
¹ 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.
| 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#False |
The 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:00 |
Finds 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: |
| Relative dates | System.ItemDate:System.StructuredQueryType.DateTime#Today System.DateAcquired:System.StructuredQueryType.DateTime#NextMonth System.Message.DateReceived:System.StructuredQueryType.DateTime#LastYear |
Finds items with today's date. Finds items with a date in the next month. Finds items with a date in the last year. Note: |
| .. | 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
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.
| 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
- 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