Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
Export (0) Print
Expand All

Saved Search File Format

In Windows Vista, 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

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

AttributeDescriptionValues
viewModeSpecifies the folder view.Details | Icons | Tiles
iconSizeControls the default size of the icons and thumbnails for items when not stack.Integer between 16 and 256
stackIconSizeFor internal use only. Do not use.n/a
displayNameFor internal use only. Do not use.n/a
autoListFlagsFor internal use only. Do not use.n/a
folderFlagsFor internal use only. Do not use.n/a
taskFlagsFor 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.

ElementDescriptionValues
visibleColumnsSpecifies an ordered list of columns to appear in the results view. The user can change this list.Any system property.
frequentlyUsedColumnsFor internal use only. Do not use.n/a
columnChooserColumnsFor internal use only. Do not use.n/a
groupBySpecifies a single system property by which to group the results. The user can change this value.Any system property.
sortListSpecifies an ordered list of columns to sort the results by.Up to four system properties. The user can change this list.
stackListFor 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.

ElementDescriptionValue
providersFor internal use only. Do not use.n/a
subQueriesFor internal use only. Do not use.n/a
ScopeIdentifies 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).
kindListIdentifies the kind of file(s) to search for.Any System.Kind value.
conditionsSpecifies 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:

TypeDescriptionAvailable Attributes
andConditionConjunction of two or more child conditionsn/a
orConditionDisjunction of two of more child conditionsn/a
notConditionNegation of a child conditionn/a
leafConditionCompares a property to valueproperty, 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 Vista Saved Searches

Windows Vista ships with a number of standard search folders. The following are examples of these Windows Vista *.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>

 

 

Community Additions

ADD
Show:
© 2015 Microsoft