kotlin-odata/com.sap.cloud.mobile.kotlin.odata/DataQuery

DataQuery

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 {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#expandItems DataQuery.expandItems} or {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#selectItems DataQuery.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 fun dataQueryExample(): kotlin.Unit
{
    val service = this.service;
    val query = DataQuery()
        .select(Customer.customerID, Customer.companyName, Customer.contactName)
        .filter(Customer.address.toLower().contains("king"))
        .orderBy(Customer.companyName);
    val customers = service.getCustomers(query);
    this.showCustomers(customers);
}

Example using dynamic API:

open fun dataQueryExample(): kotlin.Unit
{
    val service = this.service;
    val customersEntitySet = service.getEntitySet("Customers");
    val customerEntityType = customersEntitySet.entityType;
    val customerIDProperty = customerEntityType.getProperty("CustomerID");
    val companyNameProperty = customerEntityType.getProperty("CompanyName");
    val contactNameProperty = customerEntityType.getProperty("ContactName");
    val addressProperty = customerEntityType.getProperty("Address");
    val query = DataQuery()
        .select(customerIDProperty, companyNameProperty, contactNameProperty)
        .from(customersEntitySet).filter(addressProperty.toLower().contains("king"))
        .orderBy(companyNameProperty);
    val customers = service.executeQuery(query).getEntityList();
    this.showCustomers(customers);
}

Inheritors

FromJSON

Constructors

DataQuery

constructor()

Types

Companion

object Companion

Properties

aliasValues

var aliasValues: DataValueMap?

allSelected

var allSelected: Boolean

countInline

var countInline: Boolean

countMetric

var countMetric: DataMetric?

countOnly

var countOnly: Boolean

customOptions

var customOptions: StringMap?

dataFormat

var dataFormat: Int?

deltaResponse

var deltaResponse: Boolean

deltaTime

var deltaTime: GlobalDateTime?

deltaToken

var deltaToken: String?

derivedType

var derivedType: StructureType?

distinctItems

var distinctItems: Boolean

entityKey

open var entityKey: EntityKey?

entitySet

open var entitySet: EntitySet?

entityType

var entityType: EntityType?

expandItems

var expandItems: ExpandItemList?

expectedType

var expectedType: DataType?

expectSingle

var expectSingle: Boolean

groupTransform

var groupTransform: GroupTransform?

internalData

var internalData: Any?

keySelected

var keySelected: Boolean

methodCall

var methodCall: DataMethodCall?

pageSize

var pageSize: Int?

propertyPath

var propertyPath: DataPath?

queryFilter

var queryFilter: QueryFilter?

queryString

var queryString: String?

requestPath

var requestPath: String?

resourcePath

var resourcePath: ResourcePath?

searchExpression

var searchExpression: SearchExpression?

searchText

var searchText: String?

selectItems

var selectItems: SelectItemList?

skipCount

var skipCount: Int?

skipToken

var skipToken: String?

sortItems

var sortItems: SortItemList?

sparseArray

var sparseArray: Boolean

streamResponse

var streamResponse: Boolean

systemFlags

var systemFlags: Int

timeMetric

var timeMetric: DataMetric?

topCount

var topCount: Int?

trackChanges

var trackChanges: Boolean

transformValues

var transformValues: TransformValueList?

url

open var url: String?

Functions

aggregate

open fun aggregate(vararg items: AggregateValue): DataQuery

Adds aggregate items (to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#transformValues DataQuery.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 readability purposes.

bind

open fun bind(resource: BindingPath): DataQuery

Bind a resource as the binding parameter of a bound action/function. If resource is a {@link com.sap.cloud.mobile.kotlin.odata.DataPath}, then sets {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#resourcePath DataQuery.resourcePath}.{@link com.sap.cloud.mobile.kotlin.odata.ResourcePath#dataPath ResourcePath.dataPath}. If resource is an {@link com.sap.cloud.mobile.kotlin.odata.EntitySet}, then calls {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#from(com.sap.cloud.mobile.kotlin.odata.EntitySet) DataQuery.from} to set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#resourcePath DataQuery.resourcePath}.{@link com.sap.cloud.mobile.kotlin.odata.ResourcePath#entitySet ResourcePath.entitySet}. If resource is an {@link com.sap.cloud.mobile.kotlin.odata.EntityValue}, then calls {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#load(com.sap.cloud.mobile.kotlin.odata.EntityValue, com.sap.cloud.mobile.kotlin.odata.PropertyPath?) DataQuery.load} to set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#resourcePath DataQuery.resourcePath}.{@link com.sap.cloud.mobile.kotlin.odata.ResourcePath#entitySet ResourcePath.entitySet} and {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#resourcePath DataQuery.resourcePath}.{@link com.sap.cloud.mobile.kotlin.odata.ResourcePath#entityKey ResourcePath.entityKey}.

check

open fun check()

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:: {@link com.sap.cloud.mobile.kotlin.odata.DataQueryException} if the query is definitely not valid.

copy

open fun copy(): DataQuery

Return a copy of this data query which doesn't share mutable values with this query. The resulting query will not share mutable values with this query. The resulting query might share immutable values with this query. The resulting query might share mutable metadata with this query (but metadata is expected to be finalized before query construction).

count

open fun count(): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#countOnly DataQuery.countOnly} to true to request only the number of matching query results.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#inlineCount() DataQuery.inlineCount}, Requesting the Number of Items in a Collection.

currentOrDeleted

open fun currentOrDeleted(): DataQuery

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.

custom

open fun custom(name: String, value: String): DataQuery

Add a custom option to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#customOptions DataQuery.customOptions}.

deferExecution

open fun deferExecution(): DataQuery

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.

expand

open fun expand(vararg items: PropertyPath): DataQuery

Add properties (to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#expandItems DataQuery.expandItems}) for expanding from the target entity.

expandedProperties

open fun expandedProperties(): StringSet

Return the names of all properties expanded by this query.

expandsProperty

open fun expandsProperty(property: Property): Boolean

Return true if this query expands property from the target entity.

expandWithQuery

open fun expandWithQuery(item: PropertyPath, query: DataQuery): DataQuery

Add a property with a nested query to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#expandItems DataQuery.expandItems}. See the expandWithQueryExample2 below for an abbreviated syntax that implicitly creates the nested query.

expect

open fun expect(type: DataType): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#expectedType DataQuery.expectedType} and {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#expectSingle DataQuery.expectSingle}, depending on the type parameter.

filter

open fun filter(test: QueryFilter): DataQuery

Modify {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#queryFilter DataQuery.queryFilter} to be and'ed with test (or set to test if {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#queryFilter DataQuery.queryFilter} was null).

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.QueryFilter}, {@link com.sap.cloud.mobile.kotlin.odata.QueryFunction}, {@link com.sap.cloud.mobile.kotlin.odata.QueryOperator}, {@link com.sap.cloud.mobile.kotlin.odata.QueryValue}.

filteredProperties

open fun filteredProperties(): StringSet

Return the names of all properties filtered by this query.

filtersProperty

open fun filtersProperty(property: Property): Boolean

Return true if this query filters property from the target entity.

from

open fun from(entitySet: EntitySet): DataQuery

Set the {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entitySet DataQuery.entitySet} property to identify this query's target entity set.

fromDefault

open fun fromDefault(entitySet: EntitySet): DataQuery

Set the {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entitySet DataQuery.entitySet} property to identify this query's target entity set, but only if the {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entitySet DataQuery.entitySet} property wasn't previously set. This function is intended for use by generated proxy classes.

getSystemFlag

open fun getSystemFlag(flag: Int): Boolean

For internal use only.

groupBy

open fun groupBy(vararg items: PropertyPath): DataQuery

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.

hasPendingChanges

open fun hasPendingChanges(): DataQuery

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

ifOriginalEntity

open fun ifOriginalEntity(): DataQuery

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

inlineCount

open fun inlineCount(): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#countInline DataQuery.countInline} to true to request an inline count in the server's response.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#count() DataQuery.count}, System Query Option $count.

invoke

open fun invoke(method: DataMethod): DataQuery

See invoke(DataMethod, ParameterList).

open fun invoke(method: DataMethod, parameters: ParameterList): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#methodCall DataQuery.methodCall} to associate this query with an action/function invocation.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#bind(com.sap.cloud.mobile.kotlin.odata.BindingPath) DataQuery.bind}, for setting the binding parameter for a bound action/function.

join

open fun join(vararg entitySets: EntitySet): DataQuery

Set the {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#resourcePath DataQuery.resourcePath} property to identify this query's entity sets for a cross join.

load

open fun load(entity: EntityValue): DataQuery

See load(EntityValue, PropertyPath?).

open fun load(entity: EntityValue, path: PropertyPath?): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entitySet DataQuery.entitySet} and {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entityKey DataQuery.entityKey} to configure this query to load an existing entity. Equivalent to calling from(entity.entitySet).withKey(entity.entityKey).

orderBy

open fun orderBy(value: QueryValue): DataQuery

See orderBy(QueryValue, SortOrder).

open fun orderBy(value: QueryValue, order: SortOrder): DataQuery

Add to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#sortItems DataQuery.sortItems} a value for result ordering.

page

open fun page(size: Int): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#pageSize DataQuery.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.

path

open fun path(target: DataPath): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#propertyPath DataQuery.propertyPath} to identify this query's target path.

property

open fun property(target: Property): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#propertyPath DataQuery.propertyPath} to identify this query's target property.

resource

open fun resource(target: ResourcePath): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#resourcePath DataQuery.resourcePath} to identify this query's target resource.

open fun search(expression: SearchExpression): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#searchExpression DataQuery.searchExpression} for free-text searching.

select

open fun select(vararg items: PropertyPath): DataQuery

Add properties (to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#selectItems DataQuery.selectItems}) for selecting from the target entity.

selectAll

open fun selectAll(): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#allSelected DataQuery.allSelected} to true.

selectDistinct

open fun selectDistinct(vararg items: PropertyPath): DataQuery

Add properties (to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#selectItems DataQuery.selectItems}) for selecting from the target entity and set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#distinctItems DataQuery.distinctItems} to true. Note that this isn't a standard OData query option, so servers might ignore it.

selectedProperties

open fun selectedProperties(): StringSet

Return the names of all properties selected by this query. If {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#allSelected DataQuery.allSelected} or {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#keySelected DataQuery.keySelected} is set, then calling this function might result in additional items being added to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#selectItems DataQuery.selectItems} so that the resulting set of properties is consistent with the other configured query options.

selectKey

open fun selectKey(): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#keySelected DataQuery.keySelected} to true.

selectsProperty

open fun selectsProperty(property: Property): Boolean

Return true if this query selects property from the target entity.

setSystemFlag

open fun setSystemFlag(flag: Int, value: Boolean)

For internal use only.

skip

open fun skip(count: Int): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#skipCount DataQuery.skipCount} to specify the number of initial results to return.

sortedByProperties

open fun sortedByProperties(): StringSet

Return the names of all properties used for sorting by this query.

See Also:: {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#orderBy(com.sap.cloud.mobile.kotlin.odata.QueryValue, com.sap.cloud.mobile.kotlin.odata.SortOrder) DataQuery.orderBy}, {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#thenBy(com.sap.cloud.mobile.kotlin.odata.QueryValue, com.sap.cloud.mobile.kotlin.odata.SortOrder) DataQuery.thenBy}.

sparse

open fun sparse(): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#sparseArray DataQuery.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.

stream

open fun stream(): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#streamResponse DataQuery.streamResponse} to true to request streamed response processing.

thenBy

open fun thenBy(value: QueryValue): DataQuery

See thenBy(QueryValue, SortOrder).

open fun thenBy(value: QueryValue, order: SortOrder): DataQuery

Add to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#sortItems DataQuery.sortItems} a value for result ordering. This function is an alias for {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#orderBy(com.sap.cloud.mobile.kotlin.odata.QueryValue, com.sap.cloud.mobile.kotlin.odata.SortOrder) DataQuery.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.

top

open fun top(count: Int): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#topCount DataQuery.topCount} to specify the maximum number of results to return.

toString

open override fun toString(): String

{@inheritDoc}

transform

open fun transform(vararg items: TransformValue): DataQuery

Adds transform items (to {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#transformValues DataQuery.transformValues}) for transforming the result of a query sent to an entity set.

where

open fun where(test: QueryFilter): DataQuery

This function is an alias for {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#filter(com.sap.cloud.mobile.kotlin.odata.QueryFilter) DataQuery.filter}.

withChangeTracking

open fun withChangeTracking(): DataQuery

See withChangeTracking(String?).

open fun withChangeTracking(deltaLink: String?): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#url DataQuery.url} from deltaLink and set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#trackChanges DataQuery.trackChanges} to true. Also set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#deltaResponse DataQuery.deltaResponse} to true if deltaLink is non-null, otherwise false.

withKey

open fun withKey(key: EntityKey): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#entityKey DataQuery.entityKey} to locate an entity by its primary key.

withType

open fun withType(type: StructureType): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#derivedType DataQuery.derivedType} to limit results to a derived complex/entity type.

withURL

open fun withURL(url: String?): DataQuery

Set {@link com.sap.cloud.mobile.kotlin.odata.DataQuery#url DataQuery.url}. Note: It is not recommended for clients to explicitly set the URL, except by using a URL from {@link com.sap.cloud.mobile.kotlin.odata.EntityValueList#deltaLink EntityValueList.deltaLink} or {@link com.sap.cloud.mobile.kotlin.odata.EntityValueList#nextLink EntityValueList.nextLink}.