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
Show on GitHub

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
    Show on GitHub

Query Construction

  • For testing purposes only. Do not use directly.

    Declaration

    Swift

    public static func _constructForTesting() -> Query<T>
    Show on GitHub

  • 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])
    Show on GitHub

Available where T: RealmCollection

  • Query the count of the objects in the collection.

    Declaration

    Swift

    public var count: Query<Int> { get }
    Show on GitHub

  • Checks if an element exists in this collection.

    Declaration

    Swift

    public func contains(_ value: T.Element) -> Query<Bool>
    Show on GitHub

  • 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
    Show on GitHub

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>
    Show on GitHub

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

    Declaration

    Swift

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

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>
    Show on GitHub

  • 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>
    Show on GitHub

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 }
    Show on GitHub
  • max

    Returns the maximum value in the collection.

    Declaration

    Swift

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

    Returns the average in the collection.

    Declaration

    Swift

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

    Returns the sum of all the values in the collection.

    Declaration

    Swift

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

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
    Show on GitHub

  • Checks if an element exists in this collection.

    Declaration

    Swift

    public func contains(_ value: T.Value) -> Query<Bool>
    Show on GitHub

  • Allows a query over all values in the Map.

    Declaration

    Swift

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

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

  • Allows a query over all keys in the Map.

    Declaration

    Swift

    public var keys: Query<String> { get }
    Show on GitHub

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>
    Show on GitHub

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

    Declaration

    Swift

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

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>
    Show on GitHub

  • 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>
    Show on GitHub

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 }
    Show on GitHub
  • max

    Returns the maximum value in the keyed collection.

    Declaration

    Swift

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

    Returns the average in the keyed collection.

    Declaration

    Swift

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

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

    Declaration

    Swift

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

Available where T: RealmKeyedCollection

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

    Declaration

    Swift

    public var count: Query<Int> { get }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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 }
    Show on GitHub

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>
    Show on GitHub

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

    Declaration

    Swift

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

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.
    Show on GitHub

  • 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.
    Show on GitHub

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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

  • 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.
    Show on GitHub

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>
    Show on GitHub

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

    Declaration

    Swift

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

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 }
    Show on GitHub

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 }
    Show on GitHub
  • max

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

    Declaration

    Swift

    public var max: Query { get }
    Show on GitHub
  • avg

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

    Declaration

    Swift

    public var avg: Query { get }
    Show on GitHub
  • sum

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

    Declaration

    Swift

    public var sum: Query { get }
    Show on GitHub

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
    Show on GitHub