Query

@dynamicMemberLookup
public struct Query<T>

Query is a class used to create type-safe query predicates.

With Query you are given the ability to create Swift style query expression that will then be constructed into an NSPredicate. The Query class should not be instantiated directly and should be only used as a parameter within a closure that takes a query expression as an argument. Example:

public func where(_ query: ((Query<Element>) -> Query<Element>)) -> Results<Element>

You would then use the above function like so:

let results = realm.objects(Person.self).query {
   $0.name == "Foo" || $0.name == "Bar" && $0.age >= 21
}

Supported predicate types

Prefix

  • NOT ! swift let results = realm.objects(Person.self).query { !$0.dogsName.contains("Fido") || !$0.name.contains("Foo") }

Comparisions

  • Equals ==
  • Not Equals !=
  • Greater Than >
  • Less Than <
  • Greater Than or Equal >=
  • Less Than or Equal <=
  • Between .contains(_ range:)

Collections

  • IN .contains(_ element:)
  • Between .contains(_ range:)

Map

  • @allKeys .keys
  • @allValues .values

Compound

  • AND &&
  • OR ||

Collection Aggregation

  • @avg .avg
  • @min .min
  • @max .max
  • @sum .sum
  • @count .count swift let results = realm.objects(Person.self).query { !$0.dogs.age.avg >= 0 || !$0.dogsAgesArray.avg >= 0 }

Other

  • NOT !
  • Subquery ($0.fooList.intCol >= 5).count > n

In

  • Checks if the value is present in the collection.

    Declaration

    Swift

    public func `in`<U>(_ collection: U) -> Query<Bool> where T == U.Element, U : Sequence

Query Construction

  • For testing purposes only. Do not use directly.

    Declaration

    Swift

    public static func _constructForTesting() -> Query<T>
  • Constructs an NSPredicate compatible string with its accompanying arguments.

    Note

    This is for internal use only and is exposed for testing purposes.

    Declaration

    Swift

    public func _constructPredicate() -> (String, [Any])

Available where T == AnyRealmValue

Available where T: RealmCollection

  • Query the count of the objects in the collection.

    Declaration

    Swift

    public var count: Query<Int> { get }
  • Checks if an element exists in this collection.

    Declaration

    Swift

    public func contains(_ value: T.Element) -> Query<Bool>
  • Checks if any elements contained in the given array are present in the collection.

    Declaration

    Swift

    public func containsAny<U>(in collection: U) -> Query<Bool> where U : Sequence, T.Element == U.Element

Available where T: RealmCollection, T.Element: Comparable

  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: Range<T.Element>) -> Query<Bool>
  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: ClosedRange<T.Element>) -> Query<Bool>

Available where T: RealmCollection, T.Element: OptionalProtocol, T.Element.Wrapped: Comparable

  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: Range<T.Element.Wrapped>) -> Query<Bool>
  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: ClosedRange<T.Element.Wrapped>) -> Query<Bool>

Available where T: RealmCollection, T.Element.PersistedType: _QueryNumeric

  • min

    Returns the minimum value in the collection.

    Declaration

    Swift

    public var min: Query<T.Element> { get }
  • max

    Returns the maximum value in the collection.

    Declaration

    Swift

    public var max: Query<T.Element> { get }
  • avg

    Returns the average in the collection.

    Declaration

    Swift

    public var avg: Query<T.Element> { get }
  • sum

    Returns the sum of all the values in the collection.

    Declaration

    Swift

    public var sum: Query<T.Element> { get }

Available where T: RealmKeyedCollection

  • Checks if any elements contained in the given array are present in the map’s values.

    Declaration

    Swift

    public func containsAny<U>(in collection: U) -> Query<Bool> where U : Sequence, T.Value == U.Element
  • Checks if an element exists in this collection.

    Declaration

    Swift

    public func contains(_ value: T.Value) -> Query<Bool>
  • Allows a query over all values in the Map.

    Declaration

    Swift

    public var values: Query<T.Value> { get }

Available where T: RealmKeyedCollection, T.Key == String

  • Allows a query over all keys in the Map.

    Declaration

    Swift

    public var keys: Query<String> { get }

Available where T: RealmKeyedCollection, T.Value: Comparable

  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: Range<T.Value>) -> Query<Bool>
  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: ClosedRange<T.Value>) -> Query<Bool>

Available where T: RealmKeyedCollection, T.Value: OptionalProtocol, T.Value.Wrapped: Comparable

  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: Range<T.Value.Wrapped>) -> Query<Bool>
  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: ClosedRange<T.Value.Wrapped>) -> Query<Bool>

Available where T: RealmKeyedCollection, T.Value.PersistedType: _QueryNumeric

  • min

    Returns the minimum value in the keyed collection.

    Declaration

    Swift

    public var min: Query<T.Value> { get }
  • max

    Returns the maximum value in the keyed collection.

    Declaration

    Swift

    public var max: Query<T.Value> { get }
  • avg

    Returns the average in the keyed collection.

    Declaration

    Swift

    public var avg: Query<T.Value> { get }
  • sum

    Returns the sum of all the values in the keyed collection.

    Declaration

    Swift

    public var sum: Query<T.Value> { get }

Available where T: RealmKeyedCollection

  • Returns the count of all the values in the keyed collection.

    Declaration

    Swift

    public var count: Query<Int> { get }

Available where T: PersistableEnum, T.RawValue: _RealmSchemaDiscoverable

  • Query on the rawValue of the Enum rather than the Enum itself.

    This can be used to write queries which can be expressed on the RawValue but not the enum. For example, this lets you query for .starts(with:) on a string enum where the prefix is not a member of the enum.

    Declaration

    Swift

    public var rawValue: Query<T.RawValue> { get }

Available where T: OptionalProtocol, T.Wrapped: PersistableEnum, T.Wrapped.RawValue: _RealmSchemaDiscoverable

  • Query on the rawValue of the Enum rather than the Enum itself.

    This can be used to write queries which can be expressed on the RawValue but not the enum. For example, this lets you query for .starts(with:) on a string enum where the prefix is not a member of the enum.

    Declaration

    Swift

    public var rawValue: Query<T.Wrapped.RawValue?> { get }

Available where T: RealmCollection, T.Element: PersistableEnum, T.Element.RawValue: RealmCollectionValue

  • Query on the rawValue of the Enums in the collection rather than the Enums themselves.

    This can be used to write queries which can be expressed on the RawValue but not the enum. For example, this lets you query for .starts(with:) on a string enum where the prefix is not a member of the enum.

    Declaration

    Swift

    public var rawValue: Query<AnyRealmCollection<T.Element.RawValue>> { get }

Available where T: RealmKeyedCollection, T.Value: PersistableEnum, T.Value.RawValue: RealmCollectionValue

  • Query on the rawValue of the Enums in the collection rather than the Enums themselves.

    This can be used to write queries which can be expressed on the RawValue but not the enum. For example, this lets you query for .starts(with:) on a string enum where the prefix is not a member of the enum.

    Declaration

    Swift

    public var rawValue: Query<Map<T.Key, T.Value.RawValue>> { get }

Available where T: RealmCollection, T.Element: OptionalProtocol, T.Element.Wrapped: PersistableEnum, T.Element.Wrapped.RawValue: _RealmCollectionValueInsideOptional

  • Query on the rawValue of the Enums in the collection rather than the Enums themselves.

    This can be used to write queries which can be expressed on the RawValue but not the enum. For example, this lets you query for .starts(with:) on a string enum where the prefix is not a member of the enum.

    Declaration

    Swift

    public var rawValue: Query<AnyRealmCollection<T.Element.Wrapped.RawValue?>> { get }

Available where T: RealmKeyedCollection, T.Value: OptionalProtocol, T.Value.Wrapped: PersistableEnum, T.Value.Wrapped.RawValue: _RealmCollectionValueInsideOptional

  • Query on the rawValue of the Enums in the collection rather than the Enums themselves.

    This can be used to write queries which can be expressed on the RawValue but not the enum. For example, this lets you query for .starts(with:) on a string enum where the prefix is not a member of the enum.

    Declaration

    Swift

    public var rawValue: Query<Map<T.Key, T.Value.Wrapped.RawValue?>> { get }

Available where T: _HasPersistedType

  • Query on the persistableValue of the value rather than the value itself.

    This can be used to write queries which can be expressed on the persisted type but not on the type itself, such as range queries on the persistable value or to query for values which can’t be converted to the mapped type.

    For types which don’t conform to PersistableEnum, CustomPersistable or FailableCustomPersistable this doesn’t do anything useful.

    Declaration

    Swift

    public var persistableValue: Query<T.PersistedType> { get }

Available where T: RealmCollection

  • Query on the persistableValue of the values in the collection rather than the values themselves.

    This can be used to write queries which can be expressed on the persisted type but not on the type itself, such as range queries on the persistable value or to query for values which can’t be converted to the mapped type.

    For types which don’t conform to PersistableEnum, CustomPersistable or FailableCustomPersistable this doesn’t do anything useful.

    Declaration

    Swift

    public var persistableValue: Query<AnyRealmCollection<T.Element.PersistedType>> { get }

Available where T: RealmKeyedCollection

  • Query on the persistableValue of the values in the collection rather than the values themselves.

    This can be used to write queries which can be expressed on the persisted type but not on the type itself, such as range queries on the persistable value or to query for values which can’t be converted to the mapped type.

    For types which don’t conform to PersistableEnum, CustomPersistable or FailableCustomPersistable this doesn’t do anything useful.

    Declaration

    Swift

    public var persistableValue: Query<Map<T.Key, T.Value.PersistedType>> { get }

Available where T: Comparable

  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: Range<T>) -> Query<Bool>
  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: ClosedRange<T>) -> Query<Bool>

Available where T: _HasPersistedType, T.PersistedType: _QueryString

  • Checks for all elements in this collection that equal the given value. ? and * are allowed as wildcard characters, where ? matches 1 character and * matches 0 or more characters.

    Declaration

    Swift

    public func like(_ value: T, caseInsensitive: Bool = false) -> Query<Bool>

    Parameters

    value

    value used.

    caseInsensitive

    true if it is a case-insensitive search.

  • Checks for all elements in this collection that equal the given value. ? and * are allowed as wildcard characters, where ? matches 1 character and * matches 0 or more characters.

    Declaration

    Swift

    public func like<U>(_ column: Query<U>, caseInsensitive: Bool = false) -> Query<Bool>

    Parameters

    value

    value used.

    caseInsensitive

    true if it is a case-insensitive search.

Available where T: _HasPersistedType, T.PersistedType: _QueryBinary

  • Checks for all elements in this collection that contains the given value.

    Declaration

    Swift

    public func contains(_ value: T, options: StringOptions = []) -> Query<Bool>

    Parameters

    value

    value used.

    options

    A Set of options used to evaluate the search query.

  • Compares that this column contains a value in another column.

    Declaration

    Swift

    public func contains<U>(_ column: Query<U>, options: StringOptions = []) -> Query<Bool> where U : _Persistable, U.PersistedType : _QueryBinary

    Parameters

    column

    The other column.

    options

    A Set of options used to evaluate the search query.

  • Checks for all elements in this collection that starts with the given value.

    Declaration

    Swift

    public func starts(with value: T, options: StringOptions = []) -> Query<Bool>

    Parameters

    value

    value used.

    options

    A Set of options used to evaluate the search query.

  • Compares that this column starts with a value in another column.

    Declaration

    Swift

    public func starts<U>(with column: Query<U>, options: StringOptions = []) -> Query<Bool>

    Parameters

    column

    The other column.

    options

    A Set of options used to evaluate the search query.

  • Checks for all elements in this collection that ends with the given value.

    Declaration

    Swift

    public func ends(with value: T, options: StringOptions = []) -> Query<Bool>

    Parameters

    value

    value used.

    options

    A Set of options used to evaluate the search query.

  • Compares that this column ends with a value in another column.

    Declaration

    Swift

    public func ends<U>(with column: Query<U>, options: StringOptions = []) -> Query<Bool>

    Parameters

    column

    The other column.

    options

    A Set of options used to evaluate the search query.

  • Checks for all elements in this collection that equals the given value.

    Declaration

    Swift

    public func equals(_ value: T, options: StringOptions = []) -> Query<Bool>

    Parameters

    value

    value used.

    options

    A Set of options used to evaluate the search query.

  • Compares that this column is equal to the value in another given column.

    Declaration

    Swift

    public func equals<U>(_ column: Query<U>, options: StringOptions = []) -> Query<Bool>

    Parameters

    column

    The other column.

    options

    A Set of options used to evaluate the search query.

  • Checks for all elements in this collection that are not equal to the given value.

    Declaration

    Swift

    public func notEquals(_ value: T, options: StringOptions = []) -> Query<Bool>

    Parameters

    value

    value used.

    options

    A Set of options used to evaluate the search query.

  • Compares that this column is not equal to the value in another given column.

    Declaration

    Swift

    public func notEquals<U>(_ column: Query<U>, options: StringOptions = []) -> Query<Bool>

    Parameters

    column

    The other column.

    options

    A Set of options used to evaluate the search query.

Available where T: OptionalProtocol, T.Wrapped: Comparable

  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: Range<T.Wrapped>) -> Query<Bool>
  • Checks for all elements in this collection that are within a given range.

    Declaration

    Swift

    public func contains(_ range: ClosedRange<T.Wrapped>) -> Query<Bool>

Available where T == Bool

  • Completes a subquery expression.

    • Usage: (($0.myCollection.age >= 21) && ($0.myCollection.siblings == 4))).count >= 5

    Note

    Do not mix collections within a subquery expression. It is only permitted to reference a single collection per each subquery.

    Declaration

    Swift

    public var count: Query<Int> { get }

Available where T: _HasPersistedType, T.PersistedType: _QueryNumeric

  • min

    Returns the minimum value of the objects in the collection based on the keypath.

    Declaration

    Swift

    public var min: Query { get }
  • max

    Returns the maximum value of the objects in the collection based on the keypath.

    Declaration

    Swift

    public var max: Query { get }
  • avg

    Returns the average of the objects in the collection based on the keypath.

    Declaration

    Swift

    public var avg: Query { get }
  • sum

    Returns the sum of the objects in the collection based on the keypath.

    Declaration

    Swift

    public var sum: Query { get }

Available where T: OptionalProtocol, T.Wrapped: EmbeddedObject

  • Use geoWithin function to filter objects whose location points lie within a certain area, using a Geospatial shape (GeoBox, GeoPolygon or GeoCircle).

    Note

    There is no dedicated type to store Geospatial points, instead points should be stored as GeoJson-shaped embedded object. Geospatial queries (geoWithin) can only be executed in such a type of objects and will throw otherwise.

    See

    GeoPoint

    Declaration

    Swift

    func geoWithin<U>(_ value: U) -> Query<Bool> where U : RLMGeospatial