Saved Search File Format

In Windows Vista and later, users can save searches as a Search Folder which is generated by an XML file that stores the query in a form that can be used by the Windows search subsystem. This topic describes the file format (*.search-ms) and includes the following sections:

• Overview of Saved Searches
• <viewInfo> Element
  • <viewInfo> Attributes
  • <viewInfo> Child Elements
• <query> Element
  • <query> Child Elements
• <properties> Element
• Full Specification of the search-ms File Format
• Examples of Saved Searches

Overview of Saved Searches

Users can save a search query as a Search Folder, a virtual folder displayed in Windows Explorer under the Searches folder. Opening a Search Folder runs the saved search and displays up-to-date results. The saved search file stores the query in a format Windows Search can act on, specifying what to search for, where to search, and how to present the results.

The saved search is generated from an XML file (*.search-ms) in the %userprofile%\Searches folder. The data is divided into three primary elements in the XML file:

• <viewInfo> specifies presentation information
• <query> specifies (search query information
• <properties> specifies properties of the *.search-ms file itself

The following example shows the high-level structure of a saved search file.

<?xml version="1.0"?>
<persistedQuery version="1.0">

    <viewInfo ...>
        ...
    </viewInfo>

    <query>
        ...
    </query>

    <properties>
        ...
    </properties>

</persistedQuery>

<viewInfo> Element

The <viewInfo> element specifies how the results are presented to the end user. The following example shows the structure of the element.

...
    <viewInfo viewMode=""
              iconSize=""
              stackIconSize=""
              autoListFlags=""
              folderFlags=""
              taskFlags=""
              displayName="">

        <visibleColumns>
            <column viewField=""/>
        </visibleColumns>

        <frequentlyUsedColumns>
            <column viewField= ""/>
        </frequentlyUsedColumns>

        <columnChooserColumns >
            <column viewField=""/>
        </columnChooserColumns >

        <groupBy viewField=""
                 direction=""/>

        <stackList>
            <stack viewField=""/>
        </stackList>

        <sortList>
            <sort viewField=""
                  direction=""/>
        </sortList>
    </viewInfo>
...

<viewInfo> Attributes

The following table describes the attributes of the <viewInfo> element.

Attribute	Description	Values
viewMode	Specifies the folder view.	Details | Icons | Tiles
iconSize	Controls the default size of the icons and thumbnails for items when not stack.	Integer between 16 and 256
stackIconSize	For internal use only. Do not use.	n/a
displayName	For internal use only. Do not use.	n/a
autoListFlags	For internal use only. Do not use.	n/a
folderFlags	For internal use only. Do not use.	n/a
taskFlags	For internal use only. Do not use.	n/a

<viewInfo> Child Elements

The child elements of the <viewInfo> element specify which columns appear in the Windows Explorer search results and how the results are grouped and sorted. Each child element contains an ordered set of columns, identified by canonical names of system properties (for example, System.DisplayName). If not defined in the saved search file, the search results are presented with a default set of columns appropriate for the file types displayed.

Element	Description	Values
visibleColumns	Specifies an ordered list of columns to appear in the results view. The user can change this list.	Any system property.
frequentlyUsedColumns	For internal use only. Do not use.	n/a
columnChooserColumns	For internal use only. Do not use.	n/a
groupBy	Specifies a single system property by which to group the results. The user can change this value.	Any system property.
sortList	Specifies an ordered list of columns to sort the results by.	Up to four system properties. The user can change this list.
stackList	For internal use only. Do not use.	n/a

<query> Element

The <query> element specifies the attributes which define how the results are queried. The following example shows the structure of the element.

...
    <query>
        <providers>
            <provider clsid=""/>    <!-- Do not use -->
        </providers>

        <subQueries>
            <subQuery path=""/>           <!-- Do not use -->
            <subQuery knownSearch=""/>    <!-- Do not use -->
        </subQueries>

        <scope>
            <include path=""        nonRecursive=""/>   <!-- [path of location to include] -->
            <include knownFolder="" nonRecursive=""/>   <!-- Known folder ID  -->
            <exclude path=""        nonRecursive=""/>   <!-- [path of location to exclude] -->
            <exclude knownFolder="" nonRecursive=""/>   <!-- Known folder ID  -->
        </scope>

        <kindList>
            <kind name=""/>     <!-- Kind value -->
        </kindList>

        <conditions>
            <condition type="" ...>     <!-- andCondition | orCondition | notCondition | leafCondition -->
                <attributes>
                    <attribute attributeID="" .../> <!-- Do not use -->
                </attributes>
            </condition>
        </conditions>
    </query>
...

<query> Child Elements

The following table describes the child elements of the <scope> element.

Element	Description	Value
providers	For internal use only. Do not use.	n/a
subQueries	For internal use only. Do not use.	n/a
Scope	Identifies locations to include or exclude in the search.	Either a path or a known folder ID of the location to be included or excluded. This element can also specify whether the search should include/exclude child paths (a shallow or deep search).
kindList	Identifies the kind of file(s) to search for.	Any System.Kind value.
conditions	Specifies rules for filtering results. For example, results could be limited to emails sent by or to a particular person.	andCondition, orCondition, notCondition, leafCondition.

<scope> Element

The <scope> element identifies the locations to include or exclude from the search. The <scope> element must contain at least one <include> child element present and zero or more <exclude> elements. The locations can be specified as either a path (environment variables are supported) or as a known folder identifier. Furthermore, each of these locations can be specified to be searched deep or shallow by setting the nonRecursive to "true" or "false" (default is recursive). Parts of the included list of locations can be excluded by specifying exclude elements.

The following shows a <scope> element that will search the documents special folder, but not its children, the "E:" volume and its children, but not "E:\windows" directory or any of its children:

...
    <query>
        ...
        <scope>
            <include knownFolder="{FDD39AD0-238F-46AF-ADB4-6C85480369C7}" nonRecursive="true"/>
            <include path="E:\"/>
            <exclude path="E:\Windows" nonRecursive="false"/>
        </scope>
        ...
    </query>
...

<kindList> Element

These elements define the union of the "kind" of items that should appear in the library. The valid values are:

• calendar
• communication
• contact
• document
• email
• feed
• folder
• game
• instantmessage
• journal
• link
• movie
• music
• note
• picture
• program
• recordedtv
• searchfolder
• task
• video
• webhistory
• item
• other

<conditions> Element

Conditions are filters against which search results are compared. For example, you can filter results that meet certain criteria, like author name or file size. The set of conditions are built into a single condition tree with logical AND, OR and NOT branches.

The following example shows the structure of the <condition> element.

...
    <query>
        ...
        <conditions>
            <condition type="" ...>
                <attributes>
                    <attribute attributeID="" .../>
                </attributes>
            </condition>
        </conditions>
    </query>
...

The condition type can be one of the following:

Type	Description	Available Attributes
andCondition	Conjunction of two or more child conditions	n/a
orCondition	Disjunction of two of more child conditions	n/a
notCondition	Negation of a child condition	n/a
leafCondition	Compares a property to value	property, propertyType, operator, value, valuetype

The <leafCondition> element's attributes identify the properties and values the results are filtered against.

Example: <conditions> Element

The following example filters results for all unread items authored by John. That is, the System.IsRead property is false and the string "john" appears in the System.Author or System.ItemAuthors properties.

...
    <query>
        ...
        <conditions>

            <condition type="andCondition">

                <condition type="leafCondition"
                           property="System.IsRead"
                           operator="eq"
                           value="FALSE"/>

                <condition type="orCondition">

                    <condition type="leafCondition"
                               property="System.Author"
                               propertyType="string"
                               operator="wordmatch"
                               value="John"
                               valueType="System.StructuredQueryType.String"/>

                    <condition type="leafCondition"
                               property="System.ItemAuthors"
                               propertyType="string"
                               operator="wordmatch"
                               value="John"
                               valueType="System.StructuredQueryType.String"/>

                </condition>

            </condition>

        </conditions>

    </query>
...

<properties> Element

The <properties> element describes the properties of the saved search itself. Saved search files support four properties: <author>, <kind>, <description>, and <tags>. These are for internal use only.

Full Specification of the search-ms File Format

The following is an example of the full XML for a saved search file.

<?xml version="1.0"?>

<persistedQuery version="1.0">

    <!-- The viewInfo section defines how results are displayed to the end user -->
    <viewInfo viewMode=""       <!-- details | icons | tiles -->
              iconSize=""       <!-- Integer -->
              stackIconSize=""  <!-- Do not use -->
              displayName=""    <!-- Do not use -->
              folderFlags=""    <!-- Do not use -->
              taskFlags=""      <!-- Do not use -->
              autoListFlags=""> <!-- Do not use -->

        <visibleColumns>
            <column viewField=""/>  <!-- System.[propertyname] -->
        </visibleColumns>

        <frequentlyUsedColumns>
            <column viewField= ""/> <!-- Do not use -->
        </frequentlyUsedColumns>

        <columnChooserColumns >
            <column viewField=""/>  <!-- Do not use -->
        </columnChooserColumns >

        <groupBy viewField=""       <!-- System.[propertyname] -->
                 direction=""/>     <!-- ascending | descending -->

        <stackList>
            <stack viewField=""/>   <!-- Do not use -->
        </stackList>

        <sortList>
            <sort viewField=""      <!-- System.[propertyname] -->
                  direction=""/>    <!-- ascending | descending -->
        </sortList>
    </viewInfo>

    <!-- The query section defines what gets searched (locations, file kinds) -->
    <query>
        <providers>
            <provider clsid=""/>          <!-- Do not use -->
        </providers>

        <subQueries>
            <subQuery path=""/>           <!-- Do not use -->
            <subQuery knownSearch=""/>    <!-- Do not use -->
        </subQueries>

        <scope>
            <include path=""        nonRecursive=""/>   <!-- [path of location to include] -->
            <include knownFolder="" nonRecursive=""/>   <!-- Known folder ID  -->
            <exclude path=""        nonRecursive=""/>   <!-- [path of location to exclude] -->
            <exclude knownFolder="" nonRecursive=""/>   <!-- Known folder ID  -->
        </scope>

        <kindList>
            <kind name=""/>     <!-- Kind value -->
        </kindList>

        <conditions>
            <condition type="" ...>     <!-- andCondition | orCondition | notCondition | leafCondition -->
                <attributes>
                    <attribute attributeID="" .../> <!-- Do not use -->
                </attributes>
            </condition>
        </conditions>
    </query>

    <!-- The properties section identifies properties of the saved search file itself. -->
    <properties>
        ...             <!-- Do not use -->
    </properties>

</persistedQuery>

Examples of Saved Searches

The following are examples of *.search-ms files.

Recent Documents.search-ms

<?xml version="1.0"?>
<persistedQuery version="1.0">
    <viewInfo viewMode="details" iconSize="16">
        <sortList>
            <sort viewField="System.DateModified" direction="descending"/>
        </sortList>
    </viewInfo>

    <query>
        <conditions>
            <condition type="leafCondition" valuetype="System.StructuredQueryType.DateTime" property="System.DateModified" operator="imp" value="R00UUUUUUUUZZXD-30NU" propertyType="wstr" />
        </conditions>
        <kindList>
            <kind name="Document"/>
        </kindList>
        <subQueries>
            <subQuery knownSearch="{4f800859-0bd6-4e63-bbdc-38d3b616ca48}"/>
        </subQueries>
    </query>
</persistedQuery>

Recent Music.search-ms

<?xml version="1.0"?>
<persistedQuery version="1.0">
    <viewInfo viewMode="details" iconSize="16">
        <sortList>
            <sort viewField="System.DateModified" direction="descending"/>
        </sortList>
    </viewInfo>

    <query>
        <conditions>
            <condition type="leafCondition" valuetype="System.StructuredQueryType.DateTime" property="System.DateModified" operator="imp" value="R00UUUUUUUUW-1WNNU" propertyType="wstr"/>
        </conditions>
        <kindList>
            <kind name="Music"/>
        </kindList>
        <subQueries>
            <subQuery knownSearch="{4f800859-0bd6-4e63-bbdc-38d3b616ca48}"/>
        </subQueries>
    </query>
</persistedQuery>

Recently Shared by Me.search-ms

<?xml version="1.0"?>
<persistedQuery version="1.0">
    <viewInfo viewMode="details" iconSize="16">
        <visibleColumns>
            <column viewField="System.ItemNameDisplay"/>
            <column viewField="System.DateModified"/>
            <column viewField="System.Keywords"/>
            <column viewField="System.SharedWith"/>
            <column viewField="System.ItemFolderPathDisplayNarrow"/>
        </visibleColumns>
        <frequentlyUsedColumns>
            <column viewField="System.Author"/>
            <column viewField="System.Kind"/>
            <column viewField="System.Size"/>
            <column viewField="System.Title"/>
            <column viewField="System.Rating"/>
        </frequentlyUsedColumns>
        <sortList>
            <sort viewField="System.SharedWith" direction="descending"/>
        </sortList>
    </viewInfo>

    <query>
        <conditions>
            <condition type="andCondition">
                <condition type="leafCondition" property="System.IsShared" operator="eq" value="true"/>
                <condition type="leafCondition" property="System.FileOwner" operator="eq" value="[Me]"/>
            </condition>
        </conditions>
        <kindList>
            <kind name="item"/>
        </kindList>
        <scope>
            <include knownFolder="{5E6C858F-0E22-4760-9AFE-EA3317B67173}"/>
            <include knownFolder="{DFDF76A2-C82A-4D63-906A-5644AC457385}"/>
        </scope>
    </query>
</persistedQuery>