<!--
{
  "availability" : [
    "iOS: 16.0.0 -",
    "iPadOS: 16.0.0 -",
    "macCatalyst: 16.0.0 -",
    "macOS: 13.0.0 -",
    "visionOS: 1.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CoreSpotlight",
  "identifier" : "/documentation/CoreSpotlight/CSUserQuery",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "Core Spotlight"
    ],
    "preciseIdentifier" : "c:objc(cs)CSUserQuery"
  },
  "title" : "CSUserQuery"
}
-->

# CSUserQuery

A type you use to initiate searches from your interface and
offer suggested text completions.

```
class CSUserQuery
```

## Overview

A `CSUserQuery` object provides the back-end support for your
app’s search features. Combine this object with your app’s search
interface to perform lexical and semantic searches of human-entered
search terms. You can configure a query object to return ranked
or unranked results. You can also use it to get a list of suggestions
to display from your search interface.

When the text in your search control changes, create a query object
to begin searching for results based on the current text. You use a
query object only once to perform a search. If the text changes again
while a previous query is in progress, cancel the old query and
execute the new one. For this reason, it’s a good idea to delay the
start of each query until there is a sufficient gap between changes.

Configure the query parameters using a [`CSUserQueryContext`](/documentation/CoreSpotlight/CSUserQueryContext) object,
which you can reuse for multiple queries. The context lets you configure
the behavior for ranking results, specify the maximum number of results
and suggestions, and filter the results using a predicate string. When
you’re ready to start the query, choose one of the following options:

- Get the value of the [`responses`](/documentation/CoreSpotlight/CSUserQuery/responses-swift.property) property and iterate over the results.
- Configure the [`foundItemsHandler`](/documentation/CoreSpotlight/CSSearchQuery/foundItemsHandler) property and call [`start()`](/documentation/CoreSpotlight/CSUserQuery/start()) to execute the query manually.

Each query runs until Spotlight returns the requested maximum number
of results. If you don’t specify the maximum number of results, Spotlight
runs until it returns all results. To end a search before you receive all
the results, call the [`cancel()`](/documentation/CoreSpotlight/CSUserQuery/cancel()) method. Cancelling a query is especially
important if you’re about to start a new query with an updated search string.

For more information about configuring a `CSUserQuery` object,
see [Building a search interface for your app](/documentation/CoreSpotlight/building-a-search-interface-for-your-app).

## Topics

### Creating a user query

[`-  initWithUserQueryString:userQueryContext:`](/documentation/CoreSpotlight/CSUserQuery/init(userQueryString:userQueryContext:))

Creates a new user query that searches for the specified term.

### Preparing to search

[`+  prepare`](/documentation/CoreSpotlight/CSUserQuery/prepare())

Performs one-time tasks that prepare Spotlight to search for
content in all search indexes.

[`+  prepareProtectionClasses:`](/documentation/CoreSpotlight/CSUserQuery/prepareProtectionClasses(_:))

Performs one-time tasks that prepare Spotlight to search for
content in one or more protected search indexes.

### Executing the query automatically

[`responses`](/documentation/CoreSpotlight/CSUserQuery/responses-swift.property)

The matching results and suggestions for the current query string.

[`suggestions`](/documentation/CoreSpotlight/CSUserQuery/suggestions-swift.property)

An asynchronous sequence of suggested completions for the current query text.

[`Responses`](/documentation/CoreSpotlight/CSUserQuery/Responses-swift.struct)

An asynchronous sequence that contains the results and suggestions
for a query string.

[`Suggestions`](/documentation/CoreSpotlight/CSUserQuery/Suggestions-swift.struct)

An asynchronous sequence that contains the suggested completions
for a search string.

[`Item`](/documentation/CoreSpotlight/CSUserQuery/Item)

A search result that the query returns in a response.

[`Suggestion`](/documentation/CoreSpotlight/CSUserQuery/Suggestion)

A suggested text completion for a query’s search term.

### Executing the query with handler blocks

[`-  start`](/documentation/CoreSpotlight/CSUserQuery/start())

Starts searching the index for items that match the current query
string and parameters.

[`-  cancel`](/documentation/CoreSpotlight/CSUserQuery/cancel())

Cancels the current query operation.

[`foundSuggestionsHandler`](/documentation/CoreSpotlight/CSUserQuery/foundSuggestionsHandler)

The block to execute when the query delivers a new batch of suggested items.

[`foundSuggestionCount`](/documentation/CoreSpotlight/CSUserQuery/foundSuggestionCount)

The number of suggested items the query found so far.

### Improving the quality of ranked results

[`userEngaged(_:visibleItems:interaction:)`](/documentation/CoreSpotlight/CSUserQuery/userEngaged(_:visibleItems:interaction:))

Notifies the system that someone engaged with a specific search
result in your app’s interface.

[`userEngaged(_:visibleSuggestions:interaction:)`](/documentation/CoreSpotlight/CSUserQuery/userEngaged(_:visibleSuggestions:interaction:))

Notifies the system that someone engaged with a specific text
completion in your app’s interface.

[`UserInteractionKind`](/documentation/CoreSpotlight/CSUserQuery/UserInteractionKind)

Constants that indicate how someone engaged with search-related content.

## Relationships

### Conforms To

[`CustomStringConvertible`](/documentation/Swift/CustomStringConvertible)

[`CVarArg`](/documentation/Swift/CVarArg)

[`Equatable`](/documentation/Swift/Equatable)

[`NSObjectProtocol`](/documentation/ObjectiveC/NSObjectProtocol)

[`CustomDebugStringConvertible`](/documentation/Swift/CustomDebugStringConvertible)

[`Hashable`](/documentation/Swift/Hashable)

### Inherits From

[`CSSearchQuery`](/documentation/CoreSpotlight/CSSearchQuery)

---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)