QueryOptions class

Applies to Windows only

Specifies the parameters of a search query for enumerating the contents of storage folders.

Syntax


var queryOptions = new Windows.Storage.Search.QueryOptions();
var queryOptions = new Windows.Storage.Search.QueryOptions(query);
var queryOptions = new Windows.Storage.Search.QueryOptions(query, fileTypeFilter);

Attributes

[MarshalingBehavior(Agile)]
[Version(0x06020000)]

Members

The QueryOptions class has these types of members:

Constructors

The QueryOptions class has these constructors.

ConstructorDescription
QueryOptions() Creates an instance of the QueryOptions class for enumerating storage items, and initializes it with the following default settings: QueryOptions.FolderDepth gets FolderDepth.Shallow and QueryOptions.IndexerOption gets IndexerOption.DoNotUseIndexer.
QueryOptions(CommonFileQuery, IIterable(String)) Creates an instance of the QueryOptions class for enumerating files and initializes it with values provided by the specified CommonFileQuery and an optional file type filter that determines which files to include in query results.
QueryOptions(CommonFolderQuery) Creates an instance of the QueryOptions class for enumerating subfolders and initializes it with values based on the specified CommonFolderQuery.

 

Methods

The QueryOptions class has these methods. With C#, Visual Basic, and C++, it also inherits methods from the Object class.

MethodDescription
LoadFromString Initializes the current instance of the QueryOptions class with search parameters specified by a string that was created by the SaveToString method.
SaveToString Converts the values of a QueryOptions object to a string that can be used to initialize the values of a QueryOptions object by calling LoadFromString.
SetPropertyPrefetch Specifies properties that the system should load in advance for all items in the query result set while the query is being executed (instead of retrieving them on a case-by-case basis).
SetThumbnailPrefetch Specifies the type and size of thumbnails that the system should start loading immediately when items are accessed (instead of retrieving them on a case-by-case basis).
StorageProviderIdFilter Gets the filter for storage provider identifiers.

 

Properties

The QueryOptions class has these properties.

PropertyAccess typeDescription

ApplicationSearchFilter

Read/writeGets or sets an application-defined Advanced Query Syntax (AQS) string for filtering files by keywords or properties. This property is combined with the UserSearchFilter to create the query's search filter.

DateStackOption

Read-onlyGets the unit of time used to group files into folders if the QueryOptions object was created with a CommonFolderQuery based on date.

FileTypeFilter

Read-onlyGets a list of file name extensions used to filter the search results. If the list is empty, the results include all file types.

FolderDepth

Read/writeIndicates whether the search query should produce a shallow view of the folder contents or a deep recursive view of all files and subfolder.

GroupPropertyName

Read-onlyGets the name of the property used to group query results if the QueryOptions object was created using a CommonFolderQuery.

IndexerOption

Read/writeGets or sets a value that specifies whether the system index or the file system is used to retrieve query results.

Language

Read/writeGets or sets the Internet Engineering Task Force (IETF) language tag (BCP47 standard) that identifies the language associated with the query. This determines the language-specific algorithm used by the system to break the query into individual search tokens.

SortOrder

Read-onlyGets the list of SortEntry structures that specify how to sort content (like files and subfolders) in query results.

UserSearchFilter

Read/writeGets or sets a user-defined Advanced Query Syntax (AQS) string for filtering files by keywords or properties. This property is combined with the ApplicationSearchFilter to create the query's search filter.

 

Remarks

You can create a file query for any folder you have access to and that you can get as a StorageFolder.

You can use QueryOptions and CreateFileQueryWithOptions to create an indexed backed file query that lets you get properties that rely on another app's property handler.

For more code examples that show you how to use QueryOptions, see the Folder enumeration sample and the File system search sample.

For more code samples about accessing properties, see the File access sample.

Examples

This example demonstrates how to use QueryOptions to query files in a location.



// Set query options with filter and sort order for results
var fileTypeFilter = [".jpg", ".png", ".bmp", ".gif"];
var queryOptions = new Windows.Storage.Search.QueryOptions(search.CommonFileQuery.orderByName, fileTypeFilter);

// Create query and retrieve files
var query = Windows.Storage.KnownFolders.picturesLibrary.createFileQueryWithOptions(queryOptions);
query.getFilesAsync().done(function (files) {
    // Process results
    files.forEach(function (file) {
        // Process file
    });
});

The previous example relies on the Pictures library capability through PicturesLibrary to get a StorageFolder object. To learn more about accessing files and folders, see File access and permissions in Windows Store apps.

This example demonstrates how to use a file query that is backed by the system index to retrieve properties that may rely on another app's property handler (like Title document property).



// Create index backed file query and get results
var picturesLibrary = Windows.Storage.KnownFolders.picturesLibrary;
var fileTypeFilter = [".png"];
var queryOptions = new Windows.Storage.Search.QueryOptions(Windows.Storage.Search.CommonFileQuery.orderByName, fileTypeFilter);
queryOptions.indexerOption = Windows.Storage.Search.IndexerOption.onlyUseIndexer;
var fileQuery = picturesLibrary.createFileQueryWithOptions(queryOptions);
fileQuery.getFilesAsync().then(function (files) {
    // Process resulting files
    if (files.size === 0) {
        // Perform tasks to handle no files found
    } else {
        // Access properties for each file
        files.forEach(function (file) {
            // Get document properties
            file.properties.getDocumentPropertiesAsync().done(function (documentProperties) {
                // Perform tasks with document properties
                var title = documentProperties.title;
            });
        });
    }
},
// Handle errors with an error function
function (error) {
    // Handle errors encountered while processing files
});

The previous example relies on the Pictures library capability through PicturesLibrary to get a StorageFolder object. To learn more about accessing files and folders, see File access and permissions in Windows Store apps.

In the example, file contains a StorageFile that represents the file to retrieve properties for.

Requirements

Minimum supported client

Windows 8 [Windows Store apps only]

Minimum supported server

Windows Server 2012 [Windows Store apps only]

Minimum supported phone

None supported

Namespace

Windows.Storage.Search
Windows::Storage::Search [C++]

Metadata

Windows.winmd

 

 

Show:
© 2014 Microsoft