Skip to main content
All CollectionsAPI DocumentationHow Tos
Search, pagination, and sorting
Search, pagination, and sorting
Updated over a week ago

While pulling in data from SuperOps.ai, you’ll need features to manage it, especially if you’re retrieving multiple records. In SuperOps.ai’s GraphQL API, you can filter, sort, and paginate the records you pull in by using the ‘ListInfo’ object while making an API request.

In this section, you’ll find information about the features we support, what each feature does, and how you can use them.

When you need to fetch multiple records of an entity in a single request, you’ll need the following functionalities to execute your request:

  • Attribute Selection

  • Filter Condition

  • Sorting

  • Pagination or Lazy loading

Attribute selection

GraphQL already has the functionality to specify the attributes you need while making a request. This means that the option to select the attributes you want is readily available in our APIs.

Filter conditions

These conditions help you narrow down your search and find the exact records you want from a list of records. You can define a filter condition by specifying 3 elements:

  • attribute: The attributes that you’ll use in sorting and criteria are specified here. You can specify them in the form of an attribute path. The attribute path is a sequence of attributes used to point to the attribute you need. These attributes are connected using a .(dot) delimiter to form the attribute path. For example, if you’d like to generate a query for a technician’s email, then the corresponding attribute path would be "technician.email".

technician email.jpeg

  • value: This denotes the value of the specified condition.

  • operator: The operator helps you execute the filter request by using the attributes in a specific manner. These operators are considered requisite conditions and are based on the data type of the attribute.

String-type operators

is: If the attribute is single valued, the operator will check whether the attribute value is equal to the value specified in the condition. If the attribute is multi valued, the operator will check whether the value specified in the condition is equal to any one of the attribute values.

isNot: Opposite to the 'is' operator.

isEmpty: The operator will check whether the attribute doesn't have value.

isNotEmpty: Opposite to the 'isEmpty' operator.

startsWith: If the attribute is single valued, the operator will check whether the attribute value starts with the value specified in the condition. If the attribute is multi valued, the operator will check whether any one of the attribute value starts with the value specified in the condition.

endsWith: Opposite to the 'startsWith' operator.

contains: If the attribute is single valued, the operator will check whether the attribute value contains the value specified in the condition. If the attribute is multi valued, the operator will check whether any one of the attribute value contains the value specified in the condition.

notContains: Opposite to the 'contains' operator.

includes: The condition value would be an array of values. If the attribute is single valued, the operator will check whether the attribute value is present in the values specified in the condition. If the attribute is multi valued, the operator will check whether any one of the attribute value present in the values specified in the condition.

notIncludes: Opposite to the 'includes' operator.

Number type operators

These operators function the same way as their string type counterparts:

  • is

  • isNot

  • isEmpty

  • isNotEmpty

These operators will compare the attribute value to the value specified in the condition:

  • greaterThan

  • greaterThanOrEqual

  • lessThan

  • lessThanOrEqual

Date/date time operators

These operators use date/date time as the requisite condition, and are used to filter results based on the time period.

on: This operator checks whether the attribute value falls within the time period specified in the condition. This condition value can either be static date/datetime or dynamic. The dynamic values that can be used are:

  • placeholder.today

  • placeholder.tomorrow

  • placeholder.yesterday

  • placeholder.last.week

  • placeholder.this.week

  • placeholder.next.week

  • placeholder.last.month

  • placeholder.this.month

  • placeholder.next.month

  • placeholder.last.quarter

  • placeholder.this.quarter

  • placeholder.next.quarter

between: The condition value will be a list with two elements. The operator will check whether the attribute value falls in between the value range specified in the condition.

inNext: The operator will check whether the attribute value falls on the next specified duration. This is the format of the condition value:

{ "unit": "", "quantity": "" }

The supported units are YEAR, MONTH, WEEK, DAY, HOUR, MINUTE, and SECOND.

inLast: The operator will check whether the attribute value falls on the last specified duration. The format of the condition value is the same the 'inNext' operator.

after: The operator will check whether the attribute value falls after the value specified in the condition.

before: The operator will check whether the attribute value falls before the value specified in the condition.

Boolean type operators

is: The condition value could be true or false. The operator checks whether the attribute value is equal to the value specified in the condition.

While making a filter request with multiple conditions, you can use condition groups to specify them by using the AND and OR operators together. This condition group may also contain another group as an operand.

Here’s an example of a filter request made with multiple conditions. In this case, the request is to fetch the closed or resolved tickets for this week, raised by the requester with the email address ‘john@acme.com’, or the first name of the requester starts with ‘john’.

{ "joinOperator": "AND", "operands": [ { "joinOperator": "OR", "operands": [ { "attribute": "requester.email", "operator": "is", "value": "john@acme.com" }, { "attribute": "requester.firstName", "operator": "startsWith", "value": "john" } ] }, { "attribute": "status", "operator": "includes", "value": [ "Resolved", "Closed" ] }, { "attribute": "createdTime", "operator": "on", "value": "placeholder.this.week" } ] }

Sorting

To sort between multiple records, you’ll need to provide the criteria to sort them with—the sort attribute and the sort order. If you make multiple sort attributes, the order of the sort will be based on the order you provide.

Pagination

For our APIs, we support offset-based pagination. Here, we use three attributes to execute the pagination process:

  • page: specifies the page number

  • pageSize: specifies the number of records per page

  • totalCount: fetches the total number of records available in the current request

Lazy loading

You can also use the ‘hasMore’ attribute in conjunction with the page and pageSize attributes if you’d like to have an endless, scrollable list of records. Here, you can use the ‘hasMore’ attribute to indicate whether there are any remaining records to display. If yes, then the next set of records is retrieved and displayed.

Did this answer your question?