# Titanium.App.iOS.SearchQuery

> A search query object manages the criteria to apply when searching app content that you have previously indexed by using the Core Spotlight APIs.

- Source: https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.App.iOS.SearchQuery
- Titanium SDK version: 12.6.3
- Kind: proxy
- Platforms: iPhone, iPad, macOS
- Since: Titanium SDK 5.5.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

You can use this API to search multiple [Titanium.App.iOS.SearchableItem](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.SearchableItem.md) objects at the same time. You can do that 
by using the `queryString` parameter that has a special syntax to filter and index several items. Please refer 
to the official [Apple documentation](https://developer.apple.com/reference/corespotlight/cssearchquery) for detailed information on how to structure your search-query to get the 
best possible results.

To use this feature make sure you have a compatible device running iOS 10 or later.

To create a SearchableItem object, use the Titanium.App.iOS.createSearchableItem method.
Pass a dictionary of properties to the method that will help identify the item.
At minimum, you must set the [attributeSet](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.SearchableItem.md#attributeSet) property, which associates
the metadata with the SearchableItem object.

## Example: Perform a simple search-query for all items that start with "Searchable" in it.

The following example demonstrates how to search a Ti.App.iOS.SearchableItem using the iOS 10
Ti.App.iOS.SearchQuery API.

#### app.js
``` js
var win = Ti.UI.createWindow({
    backgroundColor: "#fff"
});
var btn = Ti.UI.createButton({
    title: "Start search-query"
});

var searchItems = [];
var itemAttr = Ti.App.iOS.createSearchableItemAttributeSet({
    itemContentType: Ti.App.iOS.UTTYPE_IMAGE,
    title: "Titanium Core Spotlight Tutorial"
});

itemAttr.contentDescription = "Tech Example \nOn: " + String.formatDate(new Date(), "short");
itemAttr.keywords = ["Mobile", "Appcelerator", "Titanium"];
itemAttr.displayName = "Hello world";

var item = Ti.App.iOS.createSearchableItem({
    uniqueIdentifier: "my-id",
    domainIdentifier: "com.mydomain",
    attributeSet: itemAttr
});
searchItems.push(item);

var indexer = Ti.App.iOS.createSearchableIndex();

indexer.addToDefaultSearchableIndex(searchItems, function(e) {
    if (e.success) {
        Ti.API.info("Press the home button and now search for your keywords");
    } else {
        alert("Searchable index could not be created: " + JSON.stringify(e.error));
    }
});

btn.addEventListener("click", function() {
    // An array of found Ti.App.iOS.SearchableItem's
    var allItems = [];

    // The search-query
    var searchQuery = Ti.App.iOS.createSearchQuery({
        queryString: 'title == "Titanium*"',
        attributes: ["title", "displayName", "keywords", "contentType"]
    });

    // The event to be called when a new batch of items is found
    searchQuery.addEventListener("founditems", function(e) {
        for (var i = 0; i < e.items.length; i++) {
            allItems.push(e.items[i]);
        }
    });

    // The event to be called when the search-query completes
    searchQuery.addEventListener("completed", function(e) {
        if (!e.success) {
            alert(e.error);
        }

        for (var i = 0; i < allItems.length; i++) {
            var attributeSet = allItems[i].attributeSet
            var foundTitle = attributeSet.title
            var foundDisplayName = attributeSet.displayName

            Ti.API.info("title: " + foundTitle + ", displayName: " + foundDisplayName);
        }
    });

    // Start the search-query (or use searchQuery.cancel()) to abort it
    searchQuery.start();
});

win.add(btn);
win.open();
```

## Properties

### attributes

- Type: Array<String>
- Platforms: iPhone, iPad, macOS

An array of strings that represent the attributes of indexed items.

Each string corresponds to a property name that can be set for an item. For a list of possible properties, see
the [Titanium.App.iOS.SearchableItemAttributeSet](https://titaniumsdk.com/docs/sdk/Titanium.App.iOS.SearchableItemAttributeSet.md) API. Passing null for this parameter means that the query does not use 
attributes to find matching items.

### queryString

- Type: String
- Platforms: iPhone, iPad, macOS

A formatted string that defines the matching criteria to apply to indexed items.

This parameter cannot be null.

## Methods

### cancel

- Platforms: iPhone, iPad, macOS

Cancels a query operation.

### isCancelled

- Platforms: iPhone, iPad, macOS

A Boolean value that indicates if the query has been cancelled (`true`) or not (`false`).

Returns: Boolean - Returns `true` if the query was cancelled.

### start

- Platforms: iPhone, iPad, macOS

Asynchronously queries the index for items that match the query object's specifications.

## Events

### completed

- Platforms: iPhone, iPad, macOS

Fired when the query completes to inform you about it's success. 
To receive items, use the `founditems` event.

Event properties:

- `success` (Boolean): Indicates if the operation succeeded. Returns true if download succeeded, false otherwise.
- `error` (String): Error message, if any returned. Undefined otherwise.

### founditems

- Platforms: iPhone, iPad, macOS

Fired when the query finds a new batch of matching items.

Event properties:

- `items` (Array<Titanium.App.iOS.SearchableItem>): An array of indexed items that match the specified query.
- `foundItemsCount` (Number): The number of items that are currently fetched.

## Inherited members

6 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.3/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.