Query Parameters

It is not always desired to retrieve all possible data at once. Downsides of doing so are, for example, longer waiting times for all data to be retrieved, increased memory usage when caching all results and longer processing time sorting these results. This is especially the case in devices with a slow data connection or limited resources.

To overcome these problems, it is possible to specify query parameters upon data retrieval. Examples of these parameters are: limiting the total number or results, retrieving specified fields, sorting and pagination. A combination of query parameters enables fine-grained retrieval of data, enabling all scenarios you need for your device or application. We also impose the restriction of a maximum of 10,000 results for queries; retrieving more results requires you to use scrolling.

You can use query parameters in several functions of the SDK, for example when retrieving a list of idents:

var param = new QueryParams {Count = 10};
var idents = Client.Smart.Idents.GetList(param);

Count

Limit the number of results by using the count query parameter:

var param = new QueryParams {Count = 10};

This results in a maximum of 10 results for your query.

Offset

Retrieve results starting at index offset:

var param = new QueryParams {Offset = 10};

This results in an implied maximum of 10,000 results, starting at result index 10, effectively returning results 10-10,009.

var param = new QueryParams {Count = 10};
var idents01_10 = Client.Smart.Idents.GetList(param);

param.Offset = 10;
var idents11_20 = Client.Smart.Idents.GetList(param);

Note that the param object is reused, and therefore Count is still set to 10. This returns results 1-10 and results 11-20.

Fields

Retrieve only the specified fields:

var param = new QueryParams {Fields = {"Name", "Prefix", "Valid"}};
var idents = Client.Smart.Idents.GetList(param);

This still gives you a list of the complete object type as defined in the model, although only the specified fields Name, Prefix and Valid have been transfered, thereby limiting the amount of data transfered.

Sort

Sort the results server-side, defining which fields are to be sorted in ascending order, and which in descending order:

var param = new QueryParams {SortOrder = {{"Name", "asc"}, {"Prefix", "desc"}}};
var idents = Client.Smart.Idents.GetList(param);

This results in a complete list of idents, where the field Name has been sorted in ascending order and the respective Prefix field is sorted in descending order. An example result would be:

Result # Name Prefix
1 Customer card 9999
2 Customer card 8000
3 Customer card 1000
4 X-Mas card 7000

Scrolling

For retrieving more than 10,000 results, you need to resort to scrolling. To scroll through results, you first obtain a scroll identifier by setting scroll_expire. This value is expressed as NT, where N is an integer number and T is the textual abbreviation for a time unit, like m for minute. For example: scroll_expire=5m indicates an expiry time of 5 minutes starting now. During this expiry time, you can subsequently get more results by requesting the scroll identifier. Scrolling does not work in combination with sort, count and offset.

Scrolling

Querying

Limit the results by querying for specific data. A query is a string field, which can be set as parameter. Information about these query strings can be found in the API: where? description.

var onlyValid = new QueryParams {Query = "valid:true"};

Preset

Presets are filters to be used when retrieving data, and will be explained in more detail later. These presets are identified by a name, which can be used as a query parameter:

var preset = new QueryParams {Preset = "PresetName"};

Expand

A query does not necessarily return all (related) fields of objects. If it is desired to obtain the complete objects, instruct the query to expand the results:

var expandResults = new QueryParams {Expand = true};