Cache, count, and index

For example, consider an application that provides a user interface in which you show a subset of the returned data but do not want to cache the entire result set in a browser. Your application's first API call specifies a requestTag which becomes the cacheKey, defines a count value equal to the number of elements returned in each set, and begins with index 0. For this example, assume a count of 25.

Your application then displays the first set of data as rows 0 through 24 and provides a link to the next page, which in turn displays the next set. Selecting that link calls the API with the same call, but increments the index by one. On the next page, your application displays the next 25 results, 25 through 49, and so on.

Prerequisites

Understand the concepts covered in the following topics:

1. The Data Dictionary
2. Employee-based queries
3. Location-based queries

Pagination from cache

• First request
• Subsequent requests
• Understanding index and count

First request

For this exercise, the initial API call builds on the employee-based query example by:

• adding options and specifying a requestTag within options
  • requestTag defines the cacheKey associated with the cached results
• including index, which always begins with 0
• defining a count value equal to the number of elements returned in each set (in this example, the count is 25)

Note: If you do not specify a requestTag in your initial request, the system generates a cacheKey for you. You can access the cached results of your query in subsequent requests by providing the system-generated cacheKey value as the requestTag.

Example request

{
  "select": [
    {
      "key": "EMP_COMMON_FULL_NAME"
    },
    {
      "key": "PEOPLE_MANAGER_NAME"
    }
  ],
  "from": {
    "view": "EMP",
    "employeeSet": {
      "hyperfind": {
        "id": 1
      },
      "dateRange": {
        "symbolicPeriod": {
          "qualifier": "Current_Payperiod"
        }
      }
    }
  },
  "options": {
    "requestTag": "myCache"
  },
  "index": 0,
  "count": 25
}

Example response

Note that the response:

• includes the requestTag you defined as cacheKey
• specifies the total number of elements in the results in totalElements

{
  "metadata": {
    "lastRefreshed": "2019-02-05T11:25:45.555802902",
    "cacheExpirationTime": "2019-02-05T16:30:45",
    "numNodes": "25",
    "metadataKey": "6abb090e-2148-445f-b3b5-35b57bc5692d",
    "cacheKey": "myCache",
    "totalNodes": "52",
    "totalElements": "52"
  },
  "data": {
    "key": {
      "ROOT": "-1"
    },
    "coreEntityKey": {},
    "attributes": [],
    "children": [
      {
        "key": {
          "PEOPLE": "403"
        },
        "coreEntityKey": {
          "EMP": {
            "id": "403"
          }
        },
        "attributes": [
          {
            "key": "PEOPLE_MANAGER_NAME",
            "rawValue": "Maynard, Doris",
            "value": "Maynard, Doris"
          },
          {
            "key": "EMP_COMMON_FULL_NAME",
            "rawValue": "Armstrong-Collins, Heven",
            "value": "Armstrong-Collins, Heven"
          }
        ],
        "children": [],
        "summaryListDisplay": [],
        "rootEntity": "PEOPLE",
        "customProperties": {}
      },
      ...
    ],
    "summaryListDisplay": [],
    "rootEntity": "ROOT",
    "customProperties": {}
  }
}

Subsequent requests

For all subsequent calls, send an identical request body with one exception: increment the index by one each time. The API associates each additional call with the cache key you defined, which is "myCache" in this example.

You can verify that each call is associating itself with the original cached data set by means of lastRefreshed, which should remain the same for all "myCache" requests. If at any time you wish to refresh the data set, include "refresh": true within options.

Note: In subsequent requests, do not change the count specified in the initial request body without considering the consequences and the additional logic required. Refer to Understanding index and count for more information.

Example request

{
  "select": [
    {
      "key": "EMP_COMMON_FULL_NAME"
    },
    {
      "key": "PEOPLE_MANAGER_NAME"
    }
  ],
  "from": {
    "view": "EMP",
    "employeeSet": {
      "hyperfind": {
        "id": 1
      },
      "dateRange": {
        "symbolicPeriod": {
          "qualifier": "Current_Payperiod"
        }
      }
    }
  },
  "options": {
    "requestTag": "myCache"
  },
  "index": 1,
  "count": 25
}

Understanding index and count

There is a direct relationship between index, count, and totalElements. In this example, the response set includes 52 elements and a count of 25. As a result, index can be 0, 1, or 2. The first response with an index of 0 contains the first 25 results, the second with an index of 1 contains the next 25 results, and the final response with an index of 2 contains the last 2 results.

If you change the count, the results returned by each index (and the number of valid indexes) changes appropriately.