DataQuery

open class DataQuery : ObjectBase

Encapsulates an OData query request. A query can be defined by setting query properties, or by calling query functions which provide a fluent interface. Execution of a query may result in some query properties being changed (e.g. the addition of expandItems or selectItems that are required for correct execution). Thus for thread safety, a query should be used only by a single thread at a time. Preferably a new query should be created before each query execution.

See also

DataService.executeQuery.

Example using proxy classes

open func dataQueryExample() throws -> Void {
    let service = self.service
    let query = DataQuery()
        .select(Customer.customerID, Customer.companyName, Customer.contactName)
        .filter(Customer.address.toLower().contains("king"))
        .orderBy(Customer.companyName)
    let customers = try service.fetchCustomers(matching: query)
    self.showCustomers(customers)
}

Example using dynamic API

open func dataQueryExample() throws -> Void {
    let service = self.service
    let customersEntitySet = service.entitySet(withName: "Customers")
    let customerEntityType = customersEntitySet.entityType
    let customerIDProperty = customerEntityType.property(withName: "CustomerID")
    let companyNameProperty = customerEntityType.property(withName: "CompanyName")
    let contactNameProperty = customerEntityType.property(withName: "ContactName")
    let addressProperty = customerEntityType.property(withName: "Address")
    let query = DataQuery()
        .select(customerIDProperty, companyNameProperty, contactNameProperty)
        .from(customersEntitySet).filter(addressProperty.toLower().contains("king"))
        .orderBy(companyNameProperty)
    let customers = try service.executeQuery(query).entityList()
    self.showCustomers(customers)
}
  • The request path for this query. Intended for use by servers. Clients should use API calls (e.g. from) to create request paths.

    Declaration

    Swift

    final public var requestPath: String?
  • The query string for this query. Intended for use by servers. Clients should use API calls (e.g. select, expand, filter, orderBy) to create query strings.

    Declaration

    Swift

    final public var queryString: String?
  • The data format for this query’s result.

    See also

    DataFormat.

    Declaration

    Swift

    final public var dataFormat: Int?
  • The entity type expected for the result of this query. Can be used for inference of entitySet, if only one entity set in the data model uses this type.

    Declaration

    Swift

    final public var entityType: EntityType?
  • Derived type for limiting query results.

    See also

    withType, Addressing Derived Types.

    Declaration

    Swift

    final public var derivedType: StructureType?
  • The method call for this query. To execute a query, either this must be non-nil, or entitySet must be non-nil.

    See also

    invoke.

    Declaration

    Swift

    final public var methodCall: DataMethodCall?
  • Resource path indicating the target resource for this query.

    See also

    entitySet, entityKey.

    Declaration

    Swift

    final public var resourcePath: ResourcePath?
  • Property path for accessing individual properties of an entity.

    See also

    load.

    Declaration

    Swift

    final public var propertyPath: DataPath?
  • Set to true if a single result is expected. This may be required if url has been explicitly set.

    Declaration

    Swift

    final public var expectSingle: Bool
  • The properties to select from target entities.

    See also

    select.

    Declaration

    Swift

    final public var selectItems: SelectItemList?
  • Whether to select only distinct items.

    See also

    selectDistinct.

    Declaration

    Swift

    final public var distinctItems: Bool
  • true if all properties are selected (using “*”).

    See also

    selectAll.

    Declaration

    Swift

    final public var allSelected: Bool
  • true if all key properties should be selected.

    See also

    selectKey.

    Declaration

    Swift

    final public var keySelected: Bool
  • The properties to expand from target entities.

    See also

    expand.

    Declaration

    Swift

    final public var expandItems: ExpandItemList?
  • The OData transformation items as described in OData Data Aggregation.

    Declaration

    Swift

    final public var transformValues: TransformValueList?
  • A group transformation item set through groupBy method

    Declaration

    Swift

    final public var groupTransform: GroupTransform?
  • The search text to locate in the target entities.

    See also

    search.

    Declaration

    Swift

    final public var searchText: String?
  • The filter criteria for the target entities.

    See also

    filter.

    Declaration

    Swift

    final public var queryFilter: QueryFilter?
  • The sort criteria for the target entities.

    See also

    orderBy, thenBy.

    Declaration

    Swift

    final public var sortItems: SortItemList?
  • If true, the service should return only the number of available results matching the query.

    See also

    count.

    Declaration

    Swift

    final public var countOnly: Bool
  • If true, the service should return the total number of available results as an inline count in the result list.

    See also

    inlineCount.

    Declaration

    Swift

    final public var countInline: Bool
  • If true, the query result entities will use sparse array storage of properties, to conserve memory. This is only applicable to queries whose result entities will not be updated.

    See also

    sparse.

    Declaration

    Swift

    final public var sparseArray: Bool
  • If true, the client should use streamed parsing of the response.

    See also

    stream.

    Declaration

    Swift

    final public var streamResponse: Bool
  • If true, the client should use delta parsing of the response.

    See also

    withChangeTracking.

    Declaration

    Swift

    final public var deltaResponse: Bool
  • The delta time (deltaToken as UTC date/time).

    Declaration

    Swift

    final public var deltaTime: GlobalDateTime?
  • The delta token for use in change tracking.

    Declaration

    Swift

    final public var deltaToken: String?
  • Does the client want the server to track changes?

    See also

    withChangeTracking.

    Declaration

    Swift

    final public var trackChanges: Bool
  • The skip token for use in server-driven paging.

    Declaration

    Swift

    final public var skipToken: String?
  • The number of initial results to skip.

    See also

    skip.

    Declaration

    Swift

    final public var skipCount: Int?
  • The maximum number of results per page. Note that this is just a hint to the service. The service is permitted to ignore the client-requested page size. Use skipCount and topCount for predictable paging.

    Declaration

    Swift

    final public var pageSize: Int?
  • The number of initial results to return.

    See also

    top.

    Declaration

    Swift

    final public var topCount: Int?
  • Parameter alias values.

    Declaration

    Swift

    final public var aliasValues: DataValueMap?
  • Custom query options.

    Declaration

    Swift

    final public var customOptions: StringMap?
  • Elapsed time metric (unit: “MICROSECOND”) to be used for execution of this query.

    Declaration

    Swift

    final public var timeMetric: DataMetric?
  • Result count metric to be used for execution of this query.

    Declaration

    Swift

    final public var countMetric: DataMetric?
  • Default initializer.

    Declaration

    Swift

    override public init()
  • This function is an alias for filter.

    Declaration

    Swift

    open func `where`(_ test: QueryFilter) -> DataQuery

    Parameters

    test

    The query filter.

    Return Value

    This query.

  • Adds aggregate transformation items (to transformValues) for transforming the result of a query sent to an entity set. This method is only for adding aggregate transformation items (in contrast to ‘transform’ method) for readibility purposes.

    Example for aggregations

    open func aggregationExample() throws -> Void {
        let service = self.service
        let employeeEntitySet = service.entitySet(withName: "Employees")
        let employeeEntityType = employeeEntitySet.entityType
        let ordersProperty = employeeEntityType.property(withName: "Orders")
        let orderDetails = ordersProperty.entityType.property(withName: "Order_Details")
        let ordersQuantity = orderDetails.entityType.property(withName: "Quantity")
        let query = DataQuery()
        let aggregateTransform = ordersProperty.path(ordersQuantity).sum(as: "SumQuantity")
        _ = query.aggregate(aggregateTransform)
        try self.testApplyQueryResult(query: query, expectedDynamicPropertyName: "SumQuantity")
        let queryCount = DataQuery()
        let countAggregate = AggregateValue.count(as: "AllEmployees")
        _ = queryCount.aggregate(countAggregate)
        try self.testApplyQueryResult(query: queryCount,
            expectedDynamicPropertyName: nil)
    }
    

    Example for aggregations

    open func aggregationExample() throws -> Void {
        let query = DataQuery()
        let aggregateTransform = Employee.orders.path(Order.orderDetails)
            .path(OrderDetail.quantity).sum(as: "SumQuantity")
        _ = query.aggregate(aggregateTransform)
        try self.testApplyQueryResult(query: query, expectedDynamicPropertyName: "SumQuantity")
        let queryCount = DataQuery()
        let countAggregate = AggregateValue.count(as: "AllEmployees")
        _ = queryCount.aggregate(countAggregate)
        try self.testApplyQueryResult(query: queryCount,
            expectedDynamicPropertyName: nil)
    }
    

    Declaration

    Swift

    open func aggregate(_ items: AggregateValue...) -> DataQuery

    Parameters

    rest_items

    The items to be added.

    Return Value

    This query.

  • Bind a resource as the binding parameter of a bound action/function. If resource is a DataPath, then sets resourcePath.ResourcePath.dataPath. If resource is an EntitySet, then calls from to set resourcePath.ResourcePath.entitySet. If resource is an EntityValue, then calls load to set resourcePath.ResourcePath.entitySet and resourcePath.ResourcePath.entityKey.

    Declaration

    Swift

    open func bind(_ resource: BindingPath) -> DataQuery

    Parameters

    resource

    The resource to be bound.

    Return Value

    This query.

  • Check if this query is properly configured from the client’s perspective. Note: This does not guarantee that the server will be able to execute it.

    Throws

    DataQueryException if the query is definitely not valid.

    Declaration

    Swift

    open func check() throws
  • Set countOnly to true to request only the number of matching query results.

    Example using proxy classes

    open func navigationCountExample() throws -> Void {
        let service = self.service
        let customer = try service.fetchCustomer(matching: DataQuery()
            .expand(Customer.orders).top(1))
        let orders = customer.orders
        let query = DataQuery().load(customer, Customer.orders).count()
        let count = try service.executeQuery(query).count()
        assert(count == Int64(orders.count))
    }
    

    Example using proxy classes

    open func collectionCountExample() throws -> Void {
        let service = self.service
        let customers = try service.fetchCustomers()
        let query = DataQuery().from(NorthwindServiceMetadata.EntitySets.customers)
            .count()
        let count = try service.executeQuery(query).count()
        assert(count == Int64(customers.count))
    }
    

    Example using dynamic API

    open func collectionCountExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customers = try service.executeQuery(DataQuery().from(customersEntitySet))
            .entityList()
        let query = DataQuery().from(customersEntitySet).count()
        let count = try service.executeQuery(query).count()
        assert(count == Int64(customers.length))
    }
    

    Example using dynamic API

    open func navigationCountExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let ordersProperty = customerEntityType.property(withName: "Orders")
        let customer = try service.executeQuery(DataQuery().from(customersEntitySet)
            .expand(ordersProperty).top(1))
            .entityList().first()
        let orders = ordersProperty.entityList(from: customer)
        let query = DataQuery().load(customer, ordersProperty).count()
        let count = try service.executeQuery(query).count()
        assert(count == Int64(orders.length))
    }
    

    Declaration

    Swift

    open func count() -> DataQuery

    Return Value

    This query.

  • Alter this query to include all current entities (non-pending, or with pending create/update requests) as well as deleted entities (pending deletion). This is relevant in offline scenarios.

    Declaration

    Swift

    open func currentOrDeleted() -> DataQuery

    Return Value

    This query.

  • Add a custom option to customOptions.

    Declaration

    Swift

    open func custom(_ name: String, _ value: String) -> DataQuery

    Parameters

    name

    Option name.

    value

    Option value.

    Return Value

    This query.

  • Alter this query to defer its execution. This is particular useful when using actions/functions with proxy classes. It allows the use of deferred proxy method calls together with request batches.

    Example using proxy classes

    open func invokeActionsInBatch() throws -> Void {
        let service = self.service
        let batch = RequestBatch()
        let action1 = DataQuery()
        let action2 = DataQuery()
        try service.deleteVideosInCategory("Romance", query: action1.deferExecution())
        try service.deleteVideosInCategory("Suspense", query: action2.deferExecution())
        batch.addAction(call: action1)
        batch.addAction(call: action2)
        try service.processBatch(batch)
        batch.checkActionResult(for: action1)
        batch.checkActionResult(for: action2)
    }
    

    Example using proxy classes

    open func invokeFunctionsInBatch() throws -> Void {
        let service = self.service
        let batch = RequestBatch()
        let query1 = DataQuery()
        let query2 = DataQuery()
        _ = try service.videosInCategory("Romance", query: query1.deferExecution())
        _ = try service.videosInCategory("Suspense", query: query2.deferExecution())
        batch.addFunction(call: query1)
        batch.addFunction(call: query2)
        try service.processBatch(batch)
        let videos1 = try Video.array(from: batch.functionResult(for: query1)
            .entityList())
        let videos2 = try Video.array(from: batch.functionResult(for: query2)
            .entityList())
        self.showVideos(videos1)
        self.showVideos(videos2)
    }
    

    Declaration

    Swift

    open func deferExecution() -> DataQuery

    Return Value

    This query.

  • The entity key for this query. If specified, then entitySet should also be specified.

    See also

    resourcePath, withKey.

    Declaration

    Swift

    open var entityKey: EntityKey? { get set }
  • The entity set expected for the result of this query. To execute a query, either this must be non-nil, or methodCall must be non-nil.

    See also

    resourcePath, from.

    Declaration

    Swift

    open var entitySet: EntitySet? { get set }
  • Add properties (to expandItems) for expanding from the target entity.

    Example using proxy classes

    open func expandExample() throws -> Void {
        let service = self.service
        let query = DataQuery()
            .select(Customer.customerID, Customer.companyName, Customer.contactName)
            .filter(Customer.customerID.equal("ALFKI").or(Customer.customerID.equal("ANATR")))
            .expand(Customer.orders).orderBy(Customer.companyName)
        let customers = try service.fetchCustomers(matching: query)
        var countOrders = 0
        for customer in customers {
            self.showCustomer(customer)
            let orders = customer.orders
            for order in orders {
                let orderID = order.orderID
                try Example.show("  Order ", Example.formatInt(orderID))
                countOrders = countOrders + 1
            }
        }
        assert(countOrders > 0)
    }
    

    Example using dynamic API

    open func expandExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let customerIDProperty = customerEntityType.property(withName: "CustomerID")
        let companyNameProperty = customerEntityType.property(withName: "CompanyName")
        let contactNameProperty = customerEntityType.property(withName: "ContactName")
        let ordersProperty = customerEntityType.property(withName: "Orders")
        let orderIDProperty = ordersProperty.itemEntityType.property(withName: "OrderID")
        let query = DataQuery()
            .select(customerIDProperty, companyNameProperty, contactNameProperty)
            .from(customersEntitySet).expand(ordersProperty)
            .filter(customerIDProperty.equal("ALFKI").or(customerIDProperty.equal("ANATR")))
            .orderBy(companyNameProperty)
        let customers = try service.executeQuery(query).entityList()
        var countOrders = 0
        for customer in customers {
            self.showCustomer(customer)
            let orders = ordersProperty.entityList(from: customer)
            for order in orders {
                let orderID = orderIDProperty.intValue(from: order)
                try Example.show("  Order ", Example.formatInt(orderID))
                countOrders = countOrders + 1
            }
        }
        assert(countOrders > 0)
    }
    

    Declaration

    Swift

    open func expand(_ items: PropertyPath...) -> DataQuery

    Parameters

    rest_items

    The items to be expanded.

    Return Value

    This query.

  • Add a property with a nested query to expandItems.

    Example using proxy classes

    open func expandWithQueryExample() throws -> Void {
        let service = self.service
        let query = DataQuery()
            .select(Customer.customerID, Customer.companyName, Customer.contactName)
            .filter(Customer.customerID.equal("ALFKI").or(Customer.customerID.equal("ANATR")))
            .expand(Customer.orders, withQuery: DataQuery().select(Order.orderID)
                .expand(Order.orderDetails,
                    withQuery: DataQuery().select(OrderDetail.quantity, OrderDetail.unitPrice)))
            .orderBy(Customer.companyName)
        let customers = try service.fetchCustomers(matching: query)
        var countDetails = 0
        for customer in customers {
            self.showCustomer(customer)
            let orders = customer.orders
            for order in orders {
                let orderID = order.orderID
                var totalPrice = BigDecimal(0)
                for orderDetail in order.orderDetails {
                    totalPrice = totalPrice.add(DecimalFunction.fromShort(orderDetail.quantity)
                        .multiply(orderDetail.unitPrice))
                    countDetails = countDetails + 1
                }
                try Example.show("Order ", Example.formatInt(orderID), ": total price ",
                    Example.formatDecimal(totalPrice))
            }
        }
        assert(countDetails > 0)
    }
    

    Example using dynamic API

    open func expandWithQueryExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let customerIDProperty = customerEntityType.property(withName: "CustomerID")
        let companyNameProperty = customerEntityType.property(withName: "CompanyName")
        let contactNameProperty = customerEntityType.property(withName: "ContactName")
        let ordersProperty = customerEntityType.property(withName: "Orders")
        let orderIDProperty = ordersProperty.itemEntityType.property(withName: "OrderID")
        let orderDetailsProperty = ordersProperty.itemEntityType.property(withName: "Order_Details")
        let quantityProperty = orderDetailsProperty.itemEntityType.property(withName: "Quantity")
        let unitPriceProperty = orderDetailsProperty.itemEntityType.property(withName: "UnitPrice")
        let query = DataQuery()
            .select(customerIDProperty, companyNameProperty, contactNameProperty)
            .from(customersEntitySet)
            .filter(customerIDProperty.equal("ALFKI").or(customerIDProperty.equal("ANATR")))
            .expand(ordersProperty, withQuery: DataQuery().select(orderIDProperty)
                .expand(orderDetailsProperty,
                    withQuery: DataQuery().select(quantityProperty, unitPriceProperty)))
            .orderBy(companyNameProperty)
        let customers = try service.executeQuery(query).entityList()
        for customer in customers {
            self.showCustomer(customer)
            let orders = ordersProperty.entityList(from: customer)
            for order in orders {
                let orderID = orderIDProperty.intValue(from: order)
                var totalPrice = BigDecimal(0)
                for orderDetail in orderDetailsProperty.entityList(from: order) {
                    let quantity = quantityProperty.shortValue(from: orderDetail)
                    let unitPrice = unitPriceProperty.decimalValue(from: orderDetail)
                    totalPrice = totalPrice.add(DecimalFunction.fromShort(quantity)
                        .multiply(unitPrice))
                }
                try Example.show("Order ", Example.formatInt(orderID), ": total price ",
                    Example.formatDecimal(totalPrice))
            }
        }
    }
    

    Declaration

    Swift

    open func expand(_ item: PropertyPath, withQuery query: DataQuery) -> DataQuery

    Parameters

    item

    Item to be expanded.

    query

    Query to control expansion.

    Return Value

    This query.

  • Declaration

    Swift

    open func expandedProperties() -> StringSet

    Return Value

    The names of all properties expanded by this query.

  • Declaration

    Swift

    open func expandsProperty(_ property: Property) -> Bool

    Parameters

    property

    Property to check for.

    Return Value

    true if this query expands property from the target entity.

  • Modify queryFilter to be and'ed with test (or set to test if queryFilter was nil).

    Example using proxy classes

    open func queryWithFilterExample() throws -> Void {
        let service = self.service
        let query = DataQuery()
            .select(Customer.customerID, Customer.companyName, Customer.contactName)
            .filter(Customer.country.equal("Germany")
                .and(Customer.contactName.greaterEqual("N")))
        // Alternate syntax using convenience operators:
        // let query = DataQuery()
        //     .select(Customer.customerID, Customer.companyName, Customer.contactName)
        //     .filter(Customer.country == "Germany" && Customer.contactName >= "N")
        let customers = try service.fetchCustomers(matching: query)
        self.showCustomers(customers)
    }
    

    Example using proxy classes

    open func filterByDateExample() throws -> Void {
        let service = self.service
        let oneWeekAgo = GlobalDateTime.now().plusDays(-7)
        let query = DataQuery().filter(Order.orderDate.greaterThan(oneWeekAgo))
        // Alternate syntax using convenience operators:
        // let query = DataQuery().filter(Order.orderDate >= oneWeekAgo)
        let orders = try service.fetchOrders(matching: query)
        self.showOrders(orders)
    }
    

    Example using proxy classes

    open func filterByEnumExample() throws -> Void {
        let service = self.service
        let query = DataQuery()
            .filter(TrippinPerson.gender.equal(TrippinServiceMetadata.EnumValues.TrippinPersonGender.female))
        // Alternate syntax using convenience operators:
        // let query = DataQuery().filter(TrippinPerson.gender == TrippinPersonGender.female.enumValue)
        let people = try service.fetchPeople(matching: query)
        try self.showPeople(people)
    }
    

    Example using dynamic API

    open func queryWithFilterExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let customerIDProperty = customerEntityType.property(withName: "CustomerID")
        let companyNameProperty = customerEntityType.property(withName: "CompanyName")
        let contactNameProperty = customerEntityType.property(withName: "ContactName")
        let countryProperty = customerEntityType.property(withName: "Country")
        let query = DataQuery()
            .select(customerIDProperty, companyNameProperty, contactNameProperty)
            .from(customersEntitySet)
            .filter(countryProperty.equal("Germany")
                .and(contactNameProperty.greaterEqual("N")))
        // Alternate syntax using convenience operators:
        // let query = DataQuery()
        //     .select(customerIDProperty, companyNameProperty, contactNameProperty)
        //     .from(customersEntitySet)
        //     .filter(countryProperty == "Germany" && contactNameProperty >= "N")
        let customers = try service.executeQuery(query).entityList()
        self.showCustomers(customers)
    }
    

    Example using dynamic API

    open func filterByDateExample() throws -> Void {
        let service = self.service
        let ordersEntitySet = service.entitySet(withName: "Orders")
        let orderEntityType = ordersEntitySet.entityType
        let orderDateProperty = orderEntityType.property(withName: "OrderDate")
        let oneWeekAgo = GlobalDateTime.now().plusDays(-7)
        let query = DataQuery().from(ordersEntitySet)
            .filter(orderDateProperty.greaterThan(oneWeekAgo))
        // Alternate syntax using convenience operators:
        // let query = DataQuery().filter(orderDateProperty >= oneWeekAgo)
        let orders = try service.executeQuery(query).entityList()
        self.showOrders(orders)
    }
    

    Example using dynamic API

    open func filterByEnumExample() throws -> Void {
        let service = self.service
        let peopleEntitySet = service.entitySet(withName: "People")
        let personEntityType = peopleEntitySet.entityType
        let genderProperty = personEntityType.property(withName: "Gender")
        let genderEnumType = service.metadata.enumType(withName: "Microsoft.OData.Service.Sample.TrippinInMemory.Models.PersonGender")
        let female = genderEnumType.member(name: "Female")
        let query = DataQuery().from(peopleEntitySet)
            .filter(genderProperty.equal(female))
        // Alternate syntax using convenience operators:
        // let query = DataQuery().filter(genderProperty == genderFemale)
        let people = try service.executeQuery(query).entityList()
        try self.showPeople(people)
    }
    

    Declaration

    Swift

    open func filter(_ test: QueryFilter) -> DataQuery

    Parameters

    test

    The query filter.

    Return Value

    This query.

  • Declaration

    Swift

    open func filteredProperties() -> StringSet

    Return Value

    The names of all properties filtered by this query.

  • Declaration

    Swift

    open func filtersProperty(_ property: Property) -> Bool

    Parameters

    property

    Property to check for.

    Return Value

    true if this query filters property from the target entity.

  • Set the entitySet property to identify this query’s target entity set.

    Example using proxy classes

    open func fromExample() throws -> Void {
        let service = self.service
        let customers = try service.fetchCustomers()
        for customer in customers {
            self.showCustomer(customer)
        }
    }
    

    Example using dynamic API

    open func fromExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let query = DataQuery().from(customersEntitySet)
        let customers = try service.executeQuery(query).entityList()
        for customer in customers {
            self.showCustomer(customer)
        }
    }
    

    Declaration

    Swift

    open func from(_ entitySet: EntitySet) -> DataQuery

    Parameters

    entitySet

    The target entity set.

    Return Value

    This query.

  • Set the entitySet property to identify this query’s target entity set, but only if the entitySet property wasn’t previously set. This function is intended for use by generated proxy classes.

    Declaration

    Swift

    open func fromDefault(_ entitySet: EntitySet) -> DataQuery

    Parameters

    entitySet

    The target entity set.

    Return Value

    This query.

  • Adds a group transformation item to the DataQuery with the property paths given in the parameter list. Note: If this method is called then all the transformation and aggregation items added to the query will be applied to the group transformation in the query.

    Example for transformations

    open func transformationExample() throws -> Void {
        let service = self.service
        let employeeEntitySet = service.entitySet(withName: "Employees")
        let employeeEntityType = employeeEntitySet.entityType
        let employeeReportsToProperty = employeeEntityType.property(withName: "ReportsTo")
        let employee1Property = employeeEntityType.property(withName: "Employee1")
        let ordersProperty = employeeEntityType.property(withName: "Orders")
        let ordersQuantity = ordersProperty.entityType.property(withName: "Quantity")
        let countryProperty = employeeEntityType.property(withName: "Country")
        let queryGroup = DataQuery()
        let filterGroupTransform = FilterTransform.of(QueryOperator.equal(countryProperty,
            StringValue.of("Budapest")))
        let groupTransform = GroupTransform.groupBy(employeeReportsToProperty)
            .aggregate(ordersProperty.path(ordersQuantity).sum(as: "SumQuantity"))
        _ = queryGroup.transform(groupTransform)
        try self.testApplyQueryResult(query: queryGroup,
            expectedDynamicPropertyName: "SumQuantity")
        let groupTransformForQuery = DataQuery().groupBy(employeeReportsToProperty)
            .aggregate(ordersProperty.path(ordersQuantity).sum(as: "SumQuantity"))
            .transform(filterGroupTransform)
        try self.testApplyQueryResult(query: groupTransformForQuery,
            expectedDynamicPropertyName: "SumQuantity")
        let queryTopPercent = DataQuery()
        let topPercentTransform = try TopTransform.percent(amount: Double(50),
            value: employeeReportsToProperty)
        _ = queryTopPercent.transform(topPercentTransform)
        try self.testApplyQueryResult(query: queryTopPercent,
            expectedDynamicPropertyName: nil)
        let queryExpand = DataQuery()
        let expandTransform = ExpandTransform.withFilter(ordersProperty,
            filter: FilterTransform.of(QueryOperator.equal(employeeReportsToProperty,
                IntValue.of(1000))))
        _ = queryExpand.transform(expandTransform)
        try self.testApplyQueryResult(query: queryExpand,
            expectedDynamicPropertyName: nil)
        let expandWithExpandTransform = ExpandTransform.withExpand(employee1Property,
            expandItem: expandTransform)
        let queryExpand1 = DataQuery()
        _ = queryExpand1.transform(expandWithExpandTransform)
        try self.testApplyQueryResult(query: queryExpand1,
            expectedDynamicPropertyName: nil)
    }
    

    Example for transformations

    open func transformationExample() throws -> Void {
        let queryGroup = DataQuery()
        let groupTransform = GroupTransform.groupBy(Employee.reportsTo)
            .aggregate(Employee.orders.path(Order.orderDetails)
                .path(OrderDetail.quantity).sum(as: "SumQuantity"))
        _ = queryGroup.transform(groupTransform)
        try self.testApplyQueryResult(query: queryGroup,
            expectedDynamicPropertyName: "SumQuantity")
        let filterGroupTransform = FilterTransform.of(QueryOperator.equal(Employee.country,
            StringValue.of("Budapest")))
        let groupTransformForQuery = DataQuery().groupBy(Employee.reportsTo)
            .aggregate(Employee.orders.path(Order.orderDetails)
                .path(OrderDetail.quantity).sum(as: "SumQuantity"))
            .transform(filterGroupTransform)
        try self.testApplyQueryResult(query: groupTransformForQuery,
            expectedDynamicPropertyName: "SumQuantity")
        let queryTopPercent = DataQuery()
        let topPercentTransform = try TopTransform.percent(amount: Double(50),
            value: Employee.reportsTo)
        _ = queryTopPercent.transform(topPercentTransform)
        try self.testApplyQueryResult(query: queryTopPercent,
            expectedDynamicPropertyName: nil)
        let queryExpand = DataQuery()
        let expandTransform = ExpandTransform.withFilter(Employee.orders,
            filter: FilterTransform.of(QueryOperator.equal(Employee.reportsTo,
                IntValue.of(1000))))
        _ = queryExpand.transform(expandTransform)
        try self.testApplyQueryResult(query: queryExpand,
            expectedDynamicPropertyName: nil)
        let expandWithExpandTransform = ExpandTransform.withExpand(Employee.employee1,
            expandItem: expandTransform)
        let queryExpand1 = DataQuery()
        _ = queryExpand1.transform(expandWithExpandTransform)
        try self.testApplyQueryResult(query: queryExpand1,
            expectedDynamicPropertyName: nil)
    }
    

    Declaration

    Swift

    open func groupBy(_ items: PropertyPath...) -> DataQuery

    Parameters

    rest_items

    The property paths to be added to the group transformation.

    Return Value

    This query.

  • Alter this query to apply to all entities with pending changes.

    Declaration

    Swift

    open func hasPendingChanges() -> DataQuery

    Return Value

    This query.

  • Alter this query to apply to all entities with original state.

    Declaration

    Swift

    open func ifOriginalEntity() -> DataQuery

    Return Value

    This query.

  • Set countInline to true to request an inline count in the server’s response.

    See also

    count, System Query Option $count.

    Example using proxy classes

    open func inlineCountExample() throws -> Void {
        let service = self.service
        let query = DataQuery().from(NorthwindServiceMetadata.EntitySets.customers)
            .skip(20).top(10).inlineCount()
        let result = try service.executeQuery(query)
        let customers = try Customer.array(from: result.entityList())
        let count = try result.inlineCount()
        assert(customers.count == 10)
        assert(count > Int64(10))
    }
    

    Example using dynamic API

    open func inlineCountExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let query = DataQuery().from(customersEntitySet).skip(20).top(10)
            .inlineCount()
        let result = try service.executeQuery(query)
        let customers = try result.entityList()
        let count = try result.inlineCount()
        assert(customers.length == 10)
        assert(count > Int64(10))
    }
    

    Declaration

    Swift

    open func inlineCount() -> DataQuery

    Return Value

    This query.

  • Set methodCall to associate this query with an action/function invocation.

    See also

    bind, for setting the binding parameter for a bound action/function.

    Example using proxy classes

    open func invokeExample() throws -> Void {
        let service = self.service
        let person = try service.personWithMostFriends()
        try self.showPerson(person)
    }
    

    Example using dynamic API

    open func invokeExample() throws -> Void {
        let service = self.service
        let functionImport = service.dataMethod(withName: "GetPersonWithMostFriends")
        let query = DataQuery().invoke(functionImport)
        let person = try service.executeQuery(query).requiredEntity()
        try self.showPerson(person)
    }
    

    Declaration

    Swift

    open func invoke(_ method: DataMethod, _ parameters: ParameterList = ParameterList.empty) -> DataQuery

    Parameters

    method

    Data method to be called (action or function).

    parameters

    Method parameters.

    Return Value

    This query.

  • Set entitySet and entityKey to configure this query to load an existing entity. Equivalent to calling from(entity.entitySet).withKey(entity.entityKey).

    Declaration

    Swift

    open func load(_ entity: EntityValue, _ path: PropertyPath? = nil) -> DataQuery

    Parameters

    entity

    The entity to be loaded.

    path

    Optionally specify propertyPath.

    Return Value

    This query.

  • Construct a new DataQuery if the query parameter is nil.

    Declaration

    Swift

    open class func newIfNull(query: DataQuery?) -> DataQuery

    Parameters

    query

    Query to be checked.

    Return Value

    The query parameter, if non-nil. Otherwise a new DataQuery.

  • Add to sortItems a value for result ordering.

    Example using proxy classes

    open func orderByExample() throws -> Void {
        let service = self.service
        let avila = GeographyPoint.with(latitude: 40.6567, longitude: -4.6812)
        let query = DataQuery().top(3).orderBy(Artist.placeOfBirth.geoDistance(avila))
        let artists = try service.fetchArtists(matching: query)
        self.showArtists(artists)
    }
    

    Example using dynamic API

    open func orderByExample() throws -> Void {
        let service = self.service
        let artistsEntitySet = service.entitySet(withName: "Artists")
        let artistEntityType = artistsEntitySet.entityType
        let placeOfBirthProperty = artistEntityType.property(withName: "placeOfBirth")
        let avila = GeographyPoint.with(latitude: 40.6567, longitude: -4.6812)
        let query = DataQuery().top(3).from(artistsEntitySet)
            .orderBy(placeOfBirthProperty.geoDistance(avila))
        let artists = try service.executeQuery(query).entityList()
        self.showArtists(artists)
    }
    

    Declaration

    Swift

    open func orderBy(_ value: QueryValue, _ order: SortOrder = SortOrder.ascending) -> DataQuery

    Parameters

    value

    Value for ordering.

    order

    The sort order (defaults to ascending).

    Return Value

    This query.

  • Set pageSize to specify the page-size for server-driven paging of results. Note: the server is not required to respect this setting. But if this setting is used, the client should expect to have to follow next-links.

    Example using proxy classes

    open func queryWithPageExample() throws -> Void {
        let service = self.service
        let expected = try service.executeQuery(DataQuery()
            .from(NorthwindServiceMetadata.EntitySets.customers).count())
            .count()
        var found = 0
        var query = DataQuery().from(NorthwindServiceMetadata.EntitySets.customers)
            .page(5)
        repeat {
            let result = try service.executeQuery(query)
            let customers = try Customer.array(from: result.entityList())
            self.showCustomers(customers)
            found = found &+ customers.count
            query = try result.nextQuery()
        }
        while query.url != nil
        assert(Int64(found) == expected)
    }
    

    Example using dynamic API

    open func queryWithPageExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        var query = DataQuery().from(customersEntitySet).page(5)
        repeat {
            let result = try service.executeQuery(query)
            let customers = try result.entityList()
            self.showCustomers(customers)
            query = try result.nextQuery()
        }
        while query.url != nil
    }
    

    Declaration

    Swift

    open func page(_ size: Int) -> DataQuery

    Parameters

    size

    Client-requested page size for use by server-driven paging.

    Return Value

    This query.

  • Set propertyPath to identify this query’s target path.

    Declaration

    Swift

    open func path(_ target: DataPath) -> DataQuery

    Parameters

    target

    The target path.

    Return Value

    This query.

  • Set propertyPath to identify this query’s target property.

    Declaration

    Swift

    open func property(_ target: Property) -> DataQuery

    Parameters

    target

    The target property.

    Return Value

    This query.

  • Set resourcePath to identify this query’s target resource.

    Declaration

    Swift

    open func resource(_ target: ResourcePath) -> DataQuery

    Parameters

    target

    The target resource.

    Return Value

    This query.

  • Set searchText for free-text searching.

    Example using proxy classes

    open func searchExample() throws -> Void {
        let service = self.service
        let query = DataQuery().search("Juice")
        let products = try service.fetchProducts(matching: query)
        self.showProducts(products)
    }
    

    Example using dynamic API

    open func searchExample() throws -> Void {
        let service = self.service
        let productsEntitySet = service.entitySet(withName: "Products")
        let query = DataQuery().from(productsEntitySet).search("Juice")
        let products = try service.executeQuery(query).entityList()
        self.showProducts(products)
    }
    

    Declaration

    Swift

    open func search(_ text: String) -> DataQuery

    Parameters

    text

    The search expression.

    Return Value

    This query.

  • Add properties (to selectItems) for selecting from the target entity.

    Example using proxy classes

    open func selectExample() throws -> Void {
        let service = self.service
        let query = DataQuery()
            .select(Customer.customerID, Customer.companyName, Customer.contactName)
        let customers = try service.fetchCustomers(matching: query)
        for customer in customers {
            self.showCustomer(customer)
        }
    }
    

    Example using dynamic API

    open func selectExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let customerIDProperty = customerEntityType.property(withName: "CustomerID")
        let companyNameProperty = customerEntityType.property(withName: "CompanyName")
        let contactNameProperty = customerEntityType.property(withName: "ContactName")
        let query = DataQuery()
            .select(customerIDProperty, companyNameProperty, contactNameProperty)
            .from(customersEntitySet)
        let customers = try service.executeQuery(query).entityList()
        for customer in customers {
            self.showCustomer(customer)
        }
    }
    

    Declaration

    Swift

    open func select(_ items: PropertyPath...) -> DataQuery

    Parameters

    rest_items

    The items to be selected.

    Return Value

    This query.

  • Set allSelected to true.

    Declaration

    Swift

    open func selectAll() -> DataQuery

    Return Value

    This query.

  • Add properties (to selectItems) for selecting from the target entity and set distinctItems to true. Note that this isn’t a standard OData query option, so servers might ignore it.

    Declaration

    Swift

    open func selectDistinct(_ items: PropertyPath...) -> DataQuery

    Parameters

    rest_items

    The items to be selected.

    Return Value

    This query.

  • Set keySelected to true.

    Declaration

    Swift

    open func selectKey() -> DataQuery

    Return Value

    This query.

  • Declaration

    Swift

    open func selectedProperties() -> StringSet

    Return Value

    The names of all properties selected by this query. If allSelected or keySelected is set, then calling this function might result in additional items being added to selectItems so that the resulting set of properties is consistent with the other configured query options.

  • Declaration

    Swift

    open func selectsProperty(_ property: Property) -> Bool

    Parameters

    property

    Property to check for.

    Return Value

    true if this query selects property from the target entity.

  • Set skipCount to specify the number of initial results to return.

    Example using proxy classes

    open func queryWithSkipExample() throws -> Void {
        let service = self.service
        let query = DataQuery().skip(20).top(10)
        let customers = try service.fetchCustomers(matching: query)
        self.showCustomers(customers)
        assert(customers.count == 10)
    }
    

    Example using dynamic API

    open func queryWithSkipExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let query = DataQuery().from(customersEntitySet).skip(20).top(10)
        let customers = try service.executeQuery(query).entityList()
        self.showCustomers(customers)
        assert(customers.length == 10)
    }
    

    Declaration

    Swift

    open func skip(_ count: Int) -> DataQuery

    Parameters

    count

    Number of initial results for query execution to skip.

    Return Value

    This query.

  • See also

    orderBy, thenBy.

    Declaration

    Swift

    open func sortedByProperties() -> StringSet

    Return Value

    The names of all properties used for sorting by this query.

  • Set sparseArray to true, so that query result entities will use sparse array storage of properties, to conserve memory. This is only applicable to queries whose result entities will not be updated.

    Declaration

    Swift

    open func sparse() -> DataQuery

    Return Value

    This query.

  • Set streamResponse to true to request streamed response processing.

    Declaration

    Swift

    open func stream() -> DataQuery

    Return Value

    This query.

  • Add to sortItems a value for result ordering. This function is an alias for orderBy. By convention to improve readability when multiple ordering values are required, the first ordering value is added using orderBy, and subsequent ordering values are added using thenBy.

    Example using proxy classes

    open func thenByExample() throws -> Void {
        let service = self.service
        let query = DataQuery().orderBy(Artist.lastName).thenBy(Artist.firstName)
        let artists = try service.fetchArtists(matching: query)
        self.showArtists(artists)
    }
    

    Example using dynamic API

    open func thenByExample() throws -> Void {
        let service = self.service
        let artistsEntitySet = service.entitySet(withName: "Artists")
        let artistEntityType = artistsEntitySet.entityType
        let lastNameProperty = artistEntityType.property(withName: "lastName")
        let firstNameProperty = artistEntityType.property(withName: "firstName")
        let query = DataQuery().from(artistsEntitySet).orderBy(lastNameProperty)
            .thenBy(firstNameProperty)
        let artists = try service.executeQuery(query).entityList()
        self.showArtists(artists)
    }
    

    Declaration

    Swift

    open func thenBy(_ value: QueryValue, _ order: SortOrder = SortOrder.ascending) -> DataQuery

    Parameters

    value

    Value for ordering.

    order

    The sort order (defaults to ascending).

    Return Value

    This query.

  • Declaration

    Swift

    override open func toString() -> String

    Return Value

    A string representation of this object.

  • Set topCount to specify the maximum number of results to return.

    Example using proxy classes

    open func queryWithTopExample() throws -> Void {
        let service = self.service
        let query = DataQuery().top(10)
        let customers = try service.fetchCustomers(matching: query)
        self.showCustomers(customers)
        assert(customers.count == 10)
    }
    

    Example using dynamic API

    open func queryWithTopExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let query = DataQuery().from(customersEntitySet).top(10)
        let customers = try service.executeQuery(query).entityList()
        self.showCustomers(customers)
        assert(customers.length == 10)
    }
    

    Declaration

    Swift

    open func top(_ count: Int) -> DataQuery

    Parameters

    count

    Maximum number of results for query execution to return.

    Return Value

    This query.

  • Adds transformation items (to transformValues) for transforming the result of a query sent to an entity set.

    Example for transformations

    open func transformationExample() throws -> Void {
        let service = self.service
        let employeeEntitySet = service.entitySet(withName: "Employees")
        let employeeEntityType = employeeEntitySet.entityType
        let employeeReportsToProperty = employeeEntityType.property(withName: "ReportsTo")
        let employee1Property = employeeEntityType.property(withName: "Employee1")
        let ordersProperty = employeeEntityType.property(withName: "Orders")
        let ordersQuantity = ordersProperty.entityType.property(withName: "Quantity")
        let countryProperty = employeeEntityType.property(withName: "Country")
        let queryGroup = DataQuery()
        let filterGroupTransform = FilterTransform.of(QueryOperator.equal(countryProperty,
            StringValue.of("Budapest")))
        let groupTransform = GroupTransform.groupBy(employeeReportsToProperty)
            .aggregate(ordersProperty.path(ordersQuantity).sum(as: "SumQuantity"))
        _ = queryGroup.transform(groupTransform)
        try self.testApplyQueryResult(query: queryGroup,
            expectedDynamicPropertyName: "SumQuantity")
        let groupTransformForQuery = DataQuery().groupBy(employeeReportsToProperty)
            .aggregate(ordersProperty.path(ordersQuantity).sum(as: "SumQuantity"))
            .transform(filterGroupTransform)
        try self.testApplyQueryResult(query: groupTransformForQuery,
            expectedDynamicPropertyName: "SumQuantity")
        let queryTopPercent = DataQuery()
        let topPercentTransform = try TopTransform.percent(amount: Double(50),
            value: employeeReportsToProperty)
        _ = queryTopPercent.transform(topPercentTransform)
        try self.testApplyQueryResult(query: queryTopPercent,
            expectedDynamicPropertyName: nil)
        let queryExpand = DataQuery()
        let expandTransform = ExpandTransform.withFilter(ordersProperty,
            filter: FilterTransform.of(QueryOperator.equal(employeeReportsToProperty,
                IntValue.of(1000))))
        _ = queryExpand.transform(expandTransform)
        try self.testApplyQueryResult(query: queryExpand,
            expectedDynamicPropertyName: nil)
        let expandWithExpandTransform = ExpandTransform.withExpand(employee1Property,
            expandItem: expandTransform)
        let queryExpand1 = DataQuery()
        _ = queryExpand1.transform(expandWithExpandTransform)
        try self.testApplyQueryResult(query: queryExpand1,
            expectedDynamicPropertyName: nil)
    }
    

    Example for transformations

    open func transformationExample() throws -> Void {
        let queryGroup = DataQuery()
        let groupTransform = GroupTransform.groupBy(Employee.reportsTo)
            .aggregate(Employee.orders.path(Order.orderDetails)
                .path(OrderDetail.quantity).sum(as: "SumQuantity"))
        _ = queryGroup.transform(groupTransform)
        try self.testApplyQueryResult(query: queryGroup,
            expectedDynamicPropertyName: "SumQuantity")
        let filterGroupTransform = FilterTransform.of(QueryOperator.equal(Employee.country,
            StringValue.of("Budapest")))
        let groupTransformForQuery = DataQuery().groupBy(Employee.reportsTo)
            .aggregate(Employee.orders.path(Order.orderDetails)
                .path(OrderDetail.quantity).sum(as: "SumQuantity"))
            .transform(filterGroupTransform)
        try self.testApplyQueryResult(query: groupTransformForQuery,
            expectedDynamicPropertyName: "SumQuantity")
        let queryTopPercent = DataQuery()
        let topPercentTransform = try TopTransform.percent(amount: Double(50),
            value: Employee.reportsTo)
        _ = queryTopPercent.transform(topPercentTransform)
        try self.testApplyQueryResult(query: queryTopPercent,
            expectedDynamicPropertyName: nil)
        let queryExpand = DataQuery()
        let expandTransform = ExpandTransform.withFilter(Employee.orders,
            filter: FilterTransform.of(QueryOperator.equal(Employee.reportsTo,
                IntValue.of(1000))))
        _ = queryExpand.transform(expandTransform)
        try self.testApplyQueryResult(query: queryExpand,
            expectedDynamicPropertyName: nil)
        let expandWithExpandTransform = ExpandTransform.withExpand(Employee.employee1,
            expandItem: expandTransform)
        let queryExpand1 = DataQuery()
        _ = queryExpand1.transform(expandWithExpandTransform)
        try self.testApplyQueryResult(query: queryExpand1,
            expectedDynamicPropertyName: nil)
    }
    

    Declaration

    Swift

    open func transform(_ items: TransformValue...) -> DataQuery

    Parameters

    rest_items

    The items to be added.

    Return Value

    This query.

  • url

    The relative URL for this query; a combination of requestPath and queryString if either is non-nil, or nil if the URL is intended to be derived from other properties. Note: It is not recommended for clients to explicitly set the URL, except by using a URL from EntityValueList.deltaLink or EntityValueList.nextLink.

    See also

    from, select, expand, filter, orderBy.

    Declaration

    Swift

    open var url: String? { get set }
  • Set url from deltaLink and set trackChanges to true. Also set deltaResponse to true if deltaLink is non-null, otherwise false.

    Declaration

    Swift

    open func withChangeTracking(deltaLink: String? = nil) -> DataQuery

    Parameters

    deltaLink

    Delta link (absolute or, preferably, relative to the service root URL).

    Return Value

    This query.

  • Set entityKey to locate an entity by its primary key.

    Example using proxy classes

    open func queryWithKeyExample() throws -> Void {
        let service = self.service
        let query = DataQuery()
            .select(Customer.customerID, Customer.companyName, Customer.contactName)
            .withKey(Customer.key(customerID: "QUEEN"))
        let customer = try service.fetchCustomer(matching: query)
        self.showCustomer(customer)
    }
    

    Example using dynamic API

    open func queryWithKeyExample() throws -> Void {
        let service = self.service
        let customersEntitySet = service.entitySet(withName: "Customers")
        let customerEntityType = customersEntitySet.entityType
        let customerIDProperty = customerEntityType.property(withName: "CustomerID")
        let companyNameProperty = customerEntityType.property(withName: "CompanyName")
        let contactNameProperty = customerEntityType.property(withName: "ContactName")
        let query = DataQuery()
            .select(customerIDProperty, companyNameProperty, contactNameProperty)
            .from(customersEntitySet)
            .withKey(EntityKey()
                .withProperty(customerIDProperty, value: StringValue.of("QUEEN")))
        let customer = try service.executeQuery(query).requiredEntity()
        self.showCustomer(customer)
    }
    

    Declaration

    Swift

    open func withKey(_ key: EntityKey) -> DataQuery

    Parameters

    key

    Entity key.

    Return Value

    This query.

  • Set derivedType to limit results to a derived complex/entity type.

    Declaration

    Swift

    open func withType(_ type: StructureType) -> DataQuery

    Parameters

    type

    Complex/entity type.

    Return Value

    This query.

  • Set url. Note: It is not recommended for clients to explicitly set the URL, except by using a URL from EntityValueList.deltaLink or EntityValueList.nextLink.

    Declaration

    Swift

    open func withURL(_ url: String?) -> DataQuery

    Parameters

    url

    Query URL (absolute or, preferably, relative to the service root URL).

    Return Value

    This query.