Query

public class Query<E: EntityInspectable & __EntityRelatable>: CustomDebugStringConvertible
        where E == E.EntityBindingType.EntityType

A reusable query returning entities or their IDs.

You can hold on to a Query once it is set up and re-query it e.g. using find().

Use the block-based query method to state conditions using operator overloads, like:

let query = box.query { Person.age > 21 && Person.name.startsWith(“M”) }.build()

If you want to return aggregate results or just property values and not whole entities, use property(_:) to obtain a PropertyQuery.

EntityType
The entity type this query is going to target.
Declaration
Swift

public typealias EntityType = E


                    
                    
                    find(offset:limit:)

Find all objects matching the query between the given offset and limit.

Declaration

Swift

public func find(offset: Int = 0, limit: Int = 0) throws -> [EntityType]

Parameters

`offset`	How many results to skip. (Useful when paginating results.)
`limit`	Maximum number of objects that may be returned (may give fewer).

Return Value

Collection of objects matching the query conditions.


                    
                    
                    findContiguous(offset:limit:)

Undocumented

Declaration

Swift

public func findContiguous(offset: Int = 0, limit: Int = 0) throws -> ContiguousArray<EntityType>


                    
                    
                    findIds(offset:limit:)

Find all object IDs matching the query between the given offset and limit.

Declaration

Swift

public func findIds(offset: Int = 0, limit: Int = 0) throws -> [EntityId<EntityType>]

Parameters

`offset`	How many results to skip. (Useful when paginating results.)
`limit`	Maximum number of results that may be returned (may give fewer).

Return Value

Collection of object IDs matching the query conditions.

findWithScores(offset:limit:)
Finds objects matching the query associated to their query score (e. g. distance in NN search).

This only works on objects with a property with an HNSW index.
Declaration
Swift

public func findWithScores(offset: Int = 0, limit: Int = 0) throws -> [ObjectWithScore<EntityType>]
Return Value

A list of ObjectWithScore that wraps matching objects and their score, sorted by score in ascending order.
findIdsWithScores(offset:limit:)
Finds IDs of objects matching the query associated to their query score (e. g. distance in NN search).

This only works on objects with a property with an HNSW index.
Declaration
Swift

public func findIdsWithScores(offset: Int = 0, limit: Int = 0) throws -> [IdWithScore]
Return Value

A list of IdWithScore that wraps IDs of matching objects and their score, sorted by score in ascending order.
remove()
Delete all objects matching the query.
Declaration
Swift

@discardableResult public func remove() throws -> UInt64
Return Value

Number of objects deleted.
findFirst()
Find the first Object matching the query.
Declaration
Swift

public func findFirst() throws -> EntityType?
findUnique()
Find the single object matching the query (the result must be unique).

Throws
ObjectBoxError.nonUniqueResult when there is more than one match
Declaration
Swift

public func findUnique() throws -> EntityType?
Return Value

The one and only object matching the query conditions, or nil if the query did not match anything.
count()
The number of objects matching the query.
Declaration
Swift

public func count() throws -> Int


                    
                    
                    property(_:)

Accessor to get a PropertyQuery object based on the query conditions.

You use Query to get objects, PropertyQuery to get aggregate results for entity properties. For example, for an Int property, you can get the average, sum, min, and max, among other things.

Declaration

Swift

public func property<T>(_ property: Property<EntityType, T, Void>) -> PropertyQuery<EntityType, T>
        where T: EntityPropertyTypeConvertible

Parameters


                                property

Object property to modify the query for.

Return Value

New PropertyQuery to configure.


                    
                    
                    property(_:)

Undocumented

Declaration

Swift

public func property<T>(_ property: Property<EntityType, T?, Void>) -> PropertyQuery<EntityType, T>
        where T: EntityPropertyTypeConvertible


                    
                    
                    propertyInt64(_:)

Allows having a PropertyQuery for Date properties via their Int64 unix timestamps

Declaration

Swift

public func propertyInt64(_ property: Property<EntityType, Date, Void>) -> PropertyQuery<EntityType, Int64>


                    
                    
                    propertyInt64(_:)

Allows having a PropertyQuery for Date properties via their Int64 unix timestamps

Declaration

Swift

public func propertyInt64(_ property: Property<EntityType, Date?, Void>) -> PropertyQuery<EntityType, Int64>

Parameter changes


                    
                    
                    setParameter(_:to:)

Sets a parameter previously specified using a ParameterAlias to a new value.

This is the binary operator variant. See setParameters(alias:to:_:) for operators with 2 values.

Declaration

Swift

public func setParameter(_ alias: String, to string: String)

Parameters

`alias`	Condition’s alias.
`string`	New value.


                    
                    
                    setParameters(_:to:)

Sets a parameter previously specified during query construction to a new collection value.

This is used to change the value of e.g. isContained(in:) and similar operations.

Declaration

Swift

public func setParameters(_ alias: String, to collection: [String])

Parameters

`alias`	Condition’s alias.
`collection`	New collection of values for the condition.

publisher
Return a Combine publisher for this query that you can subscribe to.
Declaration
Swift

public var publisher: QueryPublisher<EntityType> { get }


                    
                    
                    subscribe(dispatchQueue:flags:changeHandler:)

Receive a callback whenever an entity in this query is added/removed or modified. This method takes no parameters and is intended for the case where you do not want to display the objects, but want to for example run a property query or count the entities in the query without retrieving their data.

Important

There may be spurious calls to your callback when your query results haven’t actually changed, but something else in this box has.

Declaration

Swift

public func subscribe(dispatchQueue: DispatchQueue = DispatchQueue.main,
                      flags: Observer.Flags = [.sendInitial],
                      changeHandler: @escaping () -> Void) -> Observer

Parameters

`dispatchQueue`	The dispatch queue on which you want your callback to be called.
`flags`	Flags to control behavior of the subscription
`changeHandler`	A closure to be called when a change occurs.

Return Value

An object representing your observer connection. As long as the Observer object exists, your callback will be called. If you no longer want to receive callbacks, let go of your reference to this object so it is deinited.


                    
                    
                    subscribe(dispatchQueue:flags:resultHandler:)

Receive a callback whenever an entity in this query is added/removed or modified. The callback receives the query result as a parameter, allowing you to e.g. feed it to Combine or an Rx subscriber.

Important

There may be spurious calls to your callback when your query results haven’t actually changed, but something else in this box has.

Declaration

Swift

public func subscribe(dispatchQueue: DispatchQueue = DispatchQueue.main,
                      flags: Observer.Flags = [.sendInitial],
                      resultHandler: @escaping ([EntityType], ObjectBoxError?) -> Void) -> Observer

Parameters

`dispatchQueue`	The dispatch queue on which you want your callback to be called.
`flags`	Flags to control behavior of the subscription
`resultHandler`	A closure that will be passed an array of the objects in this query whenever the query contents change.

Return Value


                    
                    
                    subscribeContiguous(dispatchQueue:flags:resultHandler:)

Variant of subscribe() that is faster due to using ContiguousArray.

Declaration

Swift

public func subscribeContiguous(dispatchQueue: DispatchQueue = DispatchQueue.main,
                                flags: Observer.Flags = [.sendInitial],
                                resultHandler:
    @escaping (ContiguousArray<EntityType>, ObjectBoxError?) -> Void) -> Observer

Integer types


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

This is the variant for conditions taking single parameter e.g. isEqual/== or isGreaterThan/>.

See setParameters(_:to:_:) for operators with 2 values.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter<T, V>(_ property: Property<EntityType, V, Void>, to value: T) where T : FixedWidthInteger, V : EntityPropertyTypeConvertible

Parameters

`property`	Entity property specification.
`value`	New value for the condition.


                    
                    
                    setParameter(_:to:)

Sets a parameter previously specified using a ParameterAlias to a new value.

This is the binary operator variant. See setParameters(_:to:_:) for operators with 2 values.

Declaration

Swift

public func setParameter<T>(_ alias: String, to value: T) where T : FixedWidthInteger

Parameters

`alias`	Condition’s alias.
`value`	New value.


                    
                    
                    setParameters(_:to:_:)

Sets a parameter of a condition previously specified during query construction to new values.

This is the variant with 2 values, e.g. for isBetween(_:and:) comparison.

See setParameter(_:to:) for operators with 1 value.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameters<T>(_ property: Property<EntityType, T, Void>, to value1: T, _ value2: T)
        where T: FixedWidthInteger

Parameters

`property`	Entity property specification.
`value1`	New first value for the condition.
`value2`	New second value for the condition.


                    
                    
                    setParameters(_:to:_:)

Sets a parameter previously specified using a ParameterAlias to new values.

This is the variant with 2 values, e.g. for isBetween(_:and:) comparison. See setParameter(_:to:) for operators with 1 value.

Declaration

Swift

public func setParameters<T>(_ alias: String, to value1: T, _ value2: T) where T : FixedWidthInteger

Parameters

`alias`	Condition’s alias.
`value1`	New first value for the condition.
`value2`	New second value for the condition.


                    
                    
                    setParameters(_:to:)

Sets a parameter previously specified using a ParameterAlias to a new collection value.

This is used to change the value of e.g. isContained(in:) and similar operations.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Note: While there is some flexibility for the passed type, you must ensure that the actual values are within the valid range. E.g. passing in a integer beyond 32 bit for a 32 bit parameter type is a usage error and will result in a fatal error.

Declaration

Swift

public func setParameters<T>(_ property: Property<EntityType, T, Void>, to collection: [T])
        where T: FixedWidthInteger

Parameters

`property`	Entity property specification.
`collection`	New collection of values for the condition.


                    
                    
                    setParameters(_:to:)

Sets a parameter previously specified during query construction to a new collection value.

This is used to change the value of e.g. isContained(in:) and similar operations.

Declaration

Swift

public func setParameters<T>(_ alias: String, to collection: [T]) where T : FixedWidthInteger

Parameters

`alias`	Condition’s alias.
`collection`	New collection of values for the condition.

Bool


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

This is the variant for conditions taking single parameter e.g. isEqual/==.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter(_ property: Property<EntityType, Bool, Void>, to value: Bool)

Parameters

`property`	Entity property specification.
`value`	New value for the condition.


                    
                    
                    setParameter(_:to:)

Sets a parameter previously specified using a ParameterAlias to a new value.

Declaration

Swift

public func setParameter(_ alias: String, to value: Bool)

Parameters

`alias`	Condition’s alias.
`value`	New value.

Floating point


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

This is the variant for conditions taking single parameter e.g. isEqual/== or isGreaterThan/>

See setParameters(_:to:_:) for operators with 2 values.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter<T>(_ property: Property<EntityType, T, Void>, to value: T) where T : EntityPropertyTypeConvertible, T : BinaryFloatingPoint

Parameters

`property`	Entity property specification.
`value`	New value for the condition.


                    
                    
                    setParameter(_:toEqual:tolerance:)

Convenience for setParameters(property:to:_:) that offers the same API as a floating point equality condition with a tolerance.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change and use `setParameter(_:toEqual:tolerance:).

Declaration

Swift

public func setParameter<T>(_ property: Property<EntityType, T, Void>, toEqual value: T, tolerance: T)
        where T: BinaryFloatingPoint

Parameters

`property`	Entity property specification.
`value`	Value to compare, ± `tolerance`.
`tolerance`	Tolerance around `value`.


                    
                    
                    setParameters(_:toEqual:tolerance:)

Convenience for setParameters(_:to:_:) that offers the same API as a floating point equality condition with a tolerance.

Declaration

Swift

public func setParameters<T>(_ alias: String, toEqual value: T, tolerance: T) where T : BinaryFloatingPoint

Parameters

`alias`	Condition’s alias.
`value`	Value to compare, ± `tolerance`.
`tolerance`	Tolerance around `value`.


                    
                    
                    setParameters(_:to:_:)

Sets a parameter of a condition previously specified during query construction to new values.

This is the variant with 2 values, e.g. for isBetween(_:and:) comparison.

See setParameter(_:to:) for operators with 1 value.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameters<T>(_ property: Property<EntityType, T, Void>, to value1: T, _ value2: T)
        where T: BinaryFloatingPoint

Parameters

`property`	Entity property specification.
`value1`	New first value for the condition.
`value2`	New second value for the condition.

Float array


                    
                    
                    setParameter(_:to:)

Changes the parameter of the query condition for the given property to a new value.

Declaration

Swift

public func setParameter<V>(_ property: Property<EntityType, V, Void>, to: [Float]) 
where V: FloatArrayPropertyType

setParameter(_:to:)
Changes the parameter of the query condition with the matching alias to a new value.
Declaration
Swift

public func setParameter(_ alias: String, to: [Float])

String


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

This is the variant for conditions taking single parameter e.g. isEqual/== or isGreaterThan/>

See setParameters(_:to:_:) for operators with 2 values.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter(_ property: Property<EntityType, String, Void>, to string: String)

Parameters

`property`	Entity property specification.
`value`	New value for the condition.


                    
                    
                    setParameters(_:to:)

Sets a parameter previously specified using a ParameterAlias to a new collection value.

This is used to change the value of e.g. isContained(in:) and similar operations.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameters(_ property: Property<EntityType, String, Void>, to collection: [String])

Parameters

`property`	Entity property specification.
`collection`	New collection of values for the condition.

Date


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

This is the variant for conditions taking single parameter e.g. isEqual/== or isGreaterThan/>

See setParameters(_:to:_:) for operators with 2 values.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter(_ property: Property<EntityType, Date, Void>, to value: Date)

Parameters

`property`	Entity property specification.
`value`	New value for the condition.


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

This is the variant for conditions taking single parameter e.g. isEqual/== or isGreaterThan/>

See setParameters(_:to:_:) for operators with 2 values.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter(_ alias: String, to value: Date)

Parameters

`alias`	Condition’s alias.
`value`	New value for the condition.


                    
                    
                    setParameters(_:to:)

Sets a parameter previously specified using a ParameterAlias to a new collection value.

This is used to change the value of e.g. isContained(in:) and similar operations.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameters(_ property: Property<EntityType, Date, Void>, to collection: [Date])

Parameters

`property`	Entity property specification.
`collection`	New collection of values for the condition.


                    
                    
                    setParameters(_:to:_:)

Sets a parameter of a condition previously specified during query construction to new values.

This is the variant with 2 values, e.g. for isBetween(_:and:) comparison.

See setParameter(_:to:) for operators with 1 value.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameters(_ property: Property<EntityType, Date, Void>, to value1: Date, _ value2: Date)

Parameters

`property`	Entity property specification.
`value1`	New first value for the condition.
`value2`	New second value for the condition.

Data


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter(_ property: Property<EntityType, Data, Void>, to value: Data)

Parameters

`property`	Entity property specification.
`value`	New value for the condition.


                    
                    
                    setParameter(_:to:)

Sets a parameter of a condition previously specified during query construction to a new value.

If you have multiple conditions on the same property, specify a PropertyAlias so you can choose which condition’s value to change.

Declaration

Swift

public func setParameter(_ alias: String, to value: Data)

Parameters

`alias`	Condition’s alias.
`value`	New value for the condition.