<!--
{
  "availability" : [
    "iOS: 16.0.0 -",
    "iPadOS: 16.0.0 -",
    "macCatalyst: -",
    "macOS: 13.0.0 -",
    "tvOS: 16.0.0 -",
    "visionOS: -",
    "watchOS: 9.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "AppIntents",
  "identifier" : "/documentation/AppIntents/EntityQuery",
  "metadataVersion" : "0.1.0",
  "role" : "Protocol",
  "symbol" : {
    "kind" : "Protocol",
    "modules" : [
      "App Intents"
    ],
    "preciseIdentifier" : "s:10AppIntents11EntityQueryP"
  },
  "title" : "EntityQuery"
}
-->

# EntityQuery

An interface for locating app entity instances by identifier.

```
protocol EntityQuery : DynamicOptionsProvider, PersistentlyIdentifiable, Sendable
```

## Overview

An entity query defines how Apple Intelligence, Siri, and the Shortcuts app retrieve instances of
a specific [`AppEntity`](/documentation/AppIntents/AppEntity) type, and implements the lookup logic. To let Siri and Shortcuts retrieve
`AppEntity` instances, create a type that conforms to [`EntityQuery`](/documentation/AppIntents/EntityQuery).

### Resolve entities by identifier

In some scenarios, Apple Intelligence already knows exactly which entity the person is referring to,
and needs to retrieve the actual entity instance given its unique identifier.

To support this retrieval method, implement [`entities(for:)`](/documentation/AppIntents/EntityQuery/entities(for:)), which, given an array of [`AppEntity`](/documentation/AppIntents/AppEntity)
identifiers, returns corresponding entity instances.
In your `entities(for:)` implementation, first look up whether the instance already exists in memory.
If the instance doesn’t exist, make asynchronous calls — for example, retrieving from disk or
a backend service. If the entity for a provided identifier is no longer available,
omit it from the returned array.

```swift
struct MyPhotoQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [MyPhoto] {
        myPhotoStore.filter { identifiers.contains($0.id) }
    }
}
```

## Topics

### Creating a query

[`init()`](/documentation/AppIntents/EntityQuery/init())

### Searching for entities

[`entities(for:)`](/documentation/AppIntents/EntityQuery/entities(for:))

Retrieves instances by identifier.

[`Entity`](/documentation/AppIntents/EntityQuery/Entity)

The entity type that this query knows how to resolve.

### Suggesting entities

[`suggestedEntities()`](/documentation/AppIntents/EntityQuery/suggestedEntities())

Returns the initial results to display when the system presents options backed by this query.

## Relationships

### Inherited By

[`EnumerableEntityQuery`](/documentation/AppIntents/EnumerableEntityQuery)

[`EntityStringQuery`](/documentation/AppIntents/EntityStringQuery)

[`IndexedEntityQuery`](/documentation/AppIntents/IndexedEntityQuery)

[`UniqueAppEntityQuery`](/documentation/AppIntents/UniqueAppEntityQuery)

[`EntityPropertyQuery`](/documentation/AppIntents/EntityPropertyQuery)

### Inherits From

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

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

[`PersistentlyIdentifiable`](/documentation/AppIntents/PersistentlyIdentifiable)

[`DynamicOptionsProvider`](/documentation/AppIntents/DynamicOptionsProvider)

### Conforming Types

[`UniqueAppEntityProvider`](/documentation/AppIntents/UniqueAppEntityProvider)

---

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)