1. Home
  2. Filtering & Paging

Filtering & Paging

All APIs which return potentially a lot of records offer the possibility to page and filter the data. For big result sets paging is essential since the server disconnects long running calls after 3 minutes for the sake of system stability.

Filtering

A filter consists of the following components:

Conjunction

  • And
  • Or

Since the filter doesn’t support brackets, repeat all And filters after an Or filter.

ConditionType

  • Question
  • CustomVariable
  • UrlVariable
  • Panel (Also used for Sample)
  • SQL

ConditionOperator

  • IsLessThan
  • IsLessThanOrEqualTo
  • IsGreaterThan
  • IsGreaterThanOrEqualTo
  • IsEqualTo
  • IsNotEqualTo
  • IsEmpty
  • IsNotEmpty
  • Contains
  • DoesNotContain
  • MatchRegex
  • DoesNotMatchRegex
  • AnyIsEqual
  • AnyIsNotEqual
  • AnyIsEmpty
  • AnyIsNotEmpty
  • AnyMatchRegex
  • AnyDoesNotMatchRegex

Identifier

  • For member variables uses member. as prefix
  • For custom variables use custom. as prefix
  • In conjunction with SQL the following identifiers could be used
    • Id
    • DistributorId
    • SamplingProjectId
    • PanelId
    • PanelMemberId
    • Language
    • StartDate
    • EndDate
    • Link
    • State
    • Mode
    • ExpiryDate
    • CreatedAt
    • CreatedBy
    • UpdatedAt
    • UpdatedBy

Value

  • Provide the value of the filter
  • In case of date use “yyyy-mm-dd”
  • In case of a timestamp use “yyyy-mm-dd hh:mm:ss”
  • All timestamps need to be UTC
  • For all “Any” ConditionOperators use , to separate multiple values

The following examples show common use cases.

Case 1: Receive Completes since last request (simply delta load of new completes)

"conditions": [{
    "conjunction": "And",
    "identifier": "State",
    "conditionOperator": "IsEqualTo",
    "value": "Completed",
    "conditionType": "SQL"
},{
    "conjunction": "And",
    "identifier": "EndDate",
    "conditionOperator": "IsGreaterThanOrEqualTo",
    "value": "2022-01-01", //value of the last day
    "conditionType": "SQL",
},{
    "conjunction": "And",
    "identifier": "EndDate",
    "conditionOperator": "IsLessThan",
    "value": "2022-01-02", //value of the current day
    "conditionType": "SQL",
}]

Case 2: Receive all changes since last request (advanced delta load of all changes)

"conditions": [{
    "conjunction": "And",
    "identifier": "CreatedAt",
    "conditionOperator": "IsGreaterThanOrEqualTo",
    "value": "2022-01-01 16:00:00", //Value of last call
    "conditionType": "SQL"
},{
    "conjunction": "And",
    "identifier": "CreatedAt",
    "conditionOperator": "IsLessThan",
    "value": "2022-01-01 17:00:00", //value of current call 
    "conditionType": "SQL",
},{
    "conjunction": "Or",
    "identifier": "UpdatedAt",
    "conditionOperator": "IsGreaterThanOrEqualTo",
    "value": "2022-01-01 16:00:00", //Value of last call
    "conditionType": "SQL"
},{
    "conjunction": "And",
    "identifier": "UpdatedAt",
    "conditionOperator": "IsLessThan",
    "value": "2022-01-01 17:00:00", //value of current call 
    "conditionType": "SQL",
}]

For large scale surveys it’s essential to not load each time the full set of data but get only the delta since the last call. Generally the received data should never exceed 10k records. If more is expected the usage of paging is mandatory. If more than 20k records are requested, the request returns an error message.

Paging

The paging object consists of 4 properties:

  • PageSize
  • Page
  • OrderField
  • OrderDirection (Ascending, Descending)

Example

"paging": {
    "pageSize": 10000,
    "page": 1,
    "orderField": "Id",
    "orderDirection": "Ascending"
}

The result collection always has a property totalCount in version 3 and totalRows in older versions, which allows to calculate the amount of pages. If paging is not used this property is returned with 0.

var pages = Math.ceil(TotalRows / PageSize);
Updated on March 7, 2024

Was this article helpful?

Need Support?
Can't find the answer you're looking for?
Contact Support