# EntityPropertyQuery An interface for locating entities by matching values against one or more of their properties. ``` protocol EntityPropertyQuery : EntityQuery ``` ## Overview `EntityPropertyQuery` provides an [`EntityQuery`](/documentation/AppIntents/EntityQuery) with the ability to query instances according to its traits as they are modeled through query properties and their corresponding comparators. At runtime, [`entities(matching:mode:sortedBy:limit:)`](/documentation/AppIntents/EntityPropertyQuery/entities(matching:mode:sortedBy:limit:)) receives an array of `ComparatorMappingType` instances - a type of your choice that represents the different comparator mappings given by the user - and is responsible for fetching entities matching those comparators. The `properties` property on a `EntityPropertyQuery` contains the set of [`EntityQueryProperty`](/documentation/AppIntents/EntityQueryProperty)s the query accepts. When declaring each property’s set of supported [`EntityQueryComparator`](/documentation/AppIntents/EntityQueryComparator)s, you will supply a closure that will transform a runtime user-supplied value into an instance of `ComparatorMappingType`. The AppIntents runtime will invoke query comparator mapping closures for each comparator included in the user request, gather their output `ComparatorMappingType` values, and then invoke the `entities` function. It is then up to you to retrieve entities matching those comparators, using whichever backend (in-memory lookup, CoreData, remote network call, …) suits your application. For example, consider the following simplified `AppEntity` for a photo: ``` class MyPhoto: AppEntity { @Property(title: "Date taken") let takenAt: Date @Property(title: "Tags") let tags: [String] } ``` The following example shows how you would build a `EntityPropertyQuery` that allows the user to query for photos taken: - Before a certain date - After a certain date - Containing a given tag In `entities` you want to retrieve photos through a network request, so you supply mapping closures returning `URLQueryItem` instances for each [`EntityQueryComparator`](/documentation/AppIntents/EntityQueryComparator). Then you can use those `URLQueryItem` in `entities` to construct the correct `URL` to fetch entities. ``` struct MyPhotoQuery: EntityPropertyQuery { static var properties = QueryProperties { Property(\.$takenAt) { LessThanMapping { URLQueryItem(name: "takenBefore", value: $0) } GreaterThanMapping { URLQueryItem(name: "takenAfter": value: $0) } } Property(\.$tags) { ContainsComparator { URLQueryItem(name: "tagsContains", value: $0) } } } func entities( matching comparators: [URLQueryItem], mode: ComparatorMode, sortedBy: [Sort], limit: Int? ) async throws -> [MyPhoto] { let components = URLComponents() components.queryItems = comparators let url = components.url(relativeTo: "https://myphotosbackend.com/photos") return try await PhotosBackend.fetch(url: url) } } ``` ## Topics ### Specifying the queryable properties [`properties`](/documentation/AppIntents/EntityPropertyQuery/properties) The set of query properties supported by this query. [`EntityPropertyQuery.QueryProperties`](/documentation/AppIntents/EntityPropertyQuery/QueryProperties) [`EntityPropertyQuery.Property`](/documentation/AppIntents/EntityPropertyQuery/Property) [`ComparatorMappingType`](/documentation/AppIntents/EntityPropertyQuery/ComparatorMappingType) Type produced by `EntityQueryComparator` mapping closures and supplied as input to `results`. ### Sorting the results [`sortingOptions`](/documentation/AppIntents/EntityPropertyQuery/sortingOptions-swift.type.property) The set of sorting orders supported by this query. [`EntityPropertyQuery.SortingOptions`](/documentation/AppIntents/EntityPropertyQuery/SortingOptions-swift.typealias) [`EntityPropertyQuery.SortableBy`](/documentation/AppIntents/EntityPropertyQuery/SortableBy) ### Searching for entities [`entities(matching:mode:sortedBy:limit:)`](/documentation/AppIntents/EntityPropertyQuery/entities(matching:mode:sortedBy:limit:)) Retrieves instances matching the supplied comparators. [`EntityPropertyQuery.Sort`](/documentation/AppIntents/EntityPropertyQuery/Sort) [`EntityPropertyQuery.ComparatorMode`](/documentation/AppIntents/EntityPropertyQuery/ComparatorMode) [`EntityQueryComparatorMode`](/documentation/AppIntents/EntityQueryComparatorMode) Modes that determine how to apply a query’s comparators. --- Copyright © 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)