How to perform rich queries on app local data

[ This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation ]

Learn how an app can use the file APIs in the Windows.Storage namespace to perform rich queries against files in the app’s local stored data.

Windows Store apps can use the file APIs to perform rich queries over content stored in user libraries. This is especially valuable for apps that manage rich content such as documents, mail, or media. Media may include photos, music, and videos. You can use these queries to add features like full text search and query-based filtering against metadata stored within files.

What you need to know




Step 1: Enable rich queries for your app data

To provide rich queries over files, you use the Windows Search Service to index those files. Typically, files in an app’s local stored data aren't indexed. This is because indexing requires a performance cost that's unnecessary when the app doesn't require rich query functionality.

To enable indexing of files within app data, you must create a folder named indexed under the app data folder. Then, store the content that you want to index in that folder. The Windows Search Service indexes the file contents and metadata in this indexed folder and all subfolders.

JJ835814.wedge(en-us,WIN.10).gifTo enable indexing of files within app data

  1. Plan the indexed folder that goes under the localFolder. Here are some rules about indexed and localFolder:

    • The indexed folder must be created under the localFolder root.

    • The Windows Search Service indexes the file properties and content in this folder deeply. That is, the Windows Search Service indexes any file that is locally stored in this folder or its subfolders, which includes all levels of subfolders.

      The Windows Search Service supports full text indexing and searching for the HTML, PDF, XML, and RTF file formats, file formats for Microsoft Office files, and more. For info about filters for the Windows Search Service, see Filter Handlers that Ship with Windows.

    • You can have only one indexed folder per app.

    • The folder name indexed isn't case sensitive.

    • Although the app data folder is called localFolder in the Windows Runtime API, it's named LocalState on the physical hard drive. If you want to access this folder for testing purposes, use this folder path:

      %user%\ AppData\Local\Packages\%packageName%\LocalState
    • The folder structure under the indexed folder can be deep, but the Windows API doesn’t allow the length of the path for a file or folder to be longer than MAX_PATH, which is defined as 260 characters. So you need to ensure that the files or folders under the indexed folder don't exceed this limit. For more info about MAX_PATH, see Maximum Path Length Limitation.

    • Similarly to how the Windows Search Service indexes other locations, it indexes only the local stored data. In other words, only the files that are locally stored in the indexed folder or its subfolders are indexed.

  2. Create the indexed folder under the localFolder. You can't create the indexed folder during installation. You can create it only while the app runs. Here is a code snippet that shows how to create the indexed folder when the app first runs:

                    function (result) {
                       //your code here
  3. Store your files and folders in this indexed folder. You can use StorageFolder or IStorageFolder to store files and folders. All files and folders that you store in this indexed folder will then be available for rich queries using the file APIs in the Windows.Storage namespace.

Step 2: Fetch indexed content

After the Windows Search Service indexes the app data, the app can fetch the data via the file APIs in the Windows.Storage namespace. For example, to perform queries, use CreateFileQuery or CreateFolderQuery from a StorageFolder that represents the indexed folder or any child folder under the indexed folder.


Windows Search Service