Reference: Paginated query syntax
Query pagination allows you to retrieve a portion of a records collection (a page) per query response, preserving system performance but enabling full record retrieval through multiple responses. You can adjust the number of records returned per page, and retrieve different pages in the collection.
For the best results, due to the variability in size of Tanium deployments, retrieve 100 records per page as an initial test of your paginated query, and adjust the number of records returned per page based on performance and response time.
When you submit a paginated query request, the API Gateway service assigns an opaque string that is valid for that query and collection (a cursor) to each record in the collection. Cursors generally persist for five minutes after the most recent use of any cursor in that collection.
For example, endpoints queries support pagination. If you submit an endpoints query request and receive a cursor in the response:
-
You can reference this cursor in a successive query of that records collection to retrieve pages of records before or after a given cursor. You can repeat this process to retrieve all pages in the collection.
-
You cannot reference this endpoints-associated cursor in a sensors query. The cursor is valid only for the endpoints collection.
- If you wait more than five minutes, then submit another endpoints query request referencing a cursor from the initial query request, the response returns an error because the cursors associated with your initial query are no longer valid.
Paginated queries generally support the following syntax:
-
<field>.edges - retrieve information about a record in the collection
-
<field>.pageInfo and <field>.totalRecords - retrieve information about pages and cursors in the collection, and collection total size
-
<field> (arguments) syntax to configure the number of records returned, and a cursor in the collection to determine which records to retrieve
A field might not support all of these fields and arguments. For more information on specific fields, see the Documentation Explorer pane of the query explorer.
Edges
Fields that support query pagination define an edge as a record within the collection. For each edge, you can retrieve the following fields:
Use the following syntax to retrieve records for a field that supports query pagination:
query {
<field> {
edges {
node {
<record-field-1>
<record-field-2>
<record-field-n>
}
cursor
}
}
}
For example, the following query retrieves endpoint edges; for each edge, the response returns the endpoint name and IP address, and the cursor associated with that edge. The request does not specify pagination arguments, so the response by default returns the first 20 records from the collection.
Copy
1
2
3
4
5
6
7
8
9
10
11
query endpointsQuery {
endpoints {
edges {
node {
name
ipAddress
}
cursor
}
}
}
Page information
Fields that support query pagination allow you to retrieve information about a page of records in the collection using the following fields:
Fields that support query pagination might also support the following fields:
Use the following syntax to retrieve page information for a field that supports query pagination:
query {
<field> {
edges {
node {
<record-field-1>
<record-field-2>
<record-field-n>
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
}
}
For example, the following query retrieves endpoints and also returns page information, including the first cursor, last cursor, and whether there are pages before and after the current page in the collection. The query also returns the total number of records in the collection. The request does not specify pagination arguments, so the response by default returns the first 20 records from the collection.
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query endpointsQueryPageInfo {
endpoints {
edges {
node {
name
ipAddress
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
}
}
Paginated collection traversal arguments
Fields that support query pagination have arguments that control the number of records returned per page and which page is returned. If a query does not specify these arguments, the default settings generally return 20 records forward from the first page at the start of the collection.
Use the following arguments to traverse forward in a records collection:
-
<field> (after) - retrieve records after the specified cursor
-
<field> (first) - retrieve the first number of records after a cursor, or at the beginning of the collection if no cursor is specified
Use the following arguments to traverse backward in a records collection:
In a single query request, you can retrieve results either forward from a cursor or backwards from a cursor. You cannot specify both before and after in a single query request.
Use the following syntax to retrieve the first number of results from the start of a paginated records collection:
<field>(first: <Int>)
Use the following syntax to retrieve the first number of results without specifying a cursor (null), such as when you first retrieve records and pages from a paginated records collection:
<field>(after: null, first: <Int>)
Use the following syntax to retrieve the first number of results after a specified cursor in a paginated records collection, such as when you retrieve <field>.pageInfo.endCursor in a prior query and want to traverse forward to retrieve the next page of records:
<field>(after: <Cursor>, first: <Int>)
For example, the following query retrieves the first 20 endpoint records from the beginning of the collection, and also returns cursor information for this first page, including endpoints.pageInfo.endCursor for the last cursor on the page:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query endpointsQueryNullCursor {
endpoints (after: null, first: 20){
edges {
node {
name
ipAddress
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
}
}
To retrieve the next page of 20 records in this collection, pass the endpoints.pageInfo.endCursor value from the prior query as the after argument value:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query endpointsQueryNextPage {
endpoints (after: <endpoints.pageInfo.endCursor-value>, first: 20){
edges {
node {
name
ipAddress
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
}
}
Continue submitting requests with the endpoints.pageInfo.endCursor value from the prior query response to retrieve successive pages in the collection. If a response includes endpoints.pageInfo.hasNextPage equals false, you retrieved the last page in the collection.
Use the following syntax to retrieve the prior number of results before a specified cursor in a paginated records collection, such as when you retrieve <field>.pageInfo.startCursor in the prior query and want to traverse backward to retrieve the prior page of records:
<field>(last: <Int>, before: <Cursor>)
For example, if you retrieve the endpoints.pageInfo.startCursor value from a query and endpoints.pageInfo.hasPreviousPage equals true, a page of results precedes the page in the response. To retrieve the prior page of 20 records in this collection, pass the endpoints.pageInfo.startCursor value from the prior query as the before argument value:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
query endpointsQueryPreviousPage {
endpoints (before: <endpoints.pageInfo.startCursor-value>, last: 20){
edges {
node {
name
ipAddress
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
}
}
Continue submitting requests with the endpoints.pageInfo.startCursor value from the prior query response to retrieve prior pages in the collection. If a response includes endpoints.pageInfo.hasPreviousPage equals false, you retrieved the first page in the collection.
Paginated endpoints collection refresh argument
If you want to obtain updated information from an endpoints collection, such as if you expect endpoints to respond several minutes after your initial query request, you can refresh the collection. If your query request refreshes the collection, the API Gateway service updates collection results with current information, invalidates the prior set of cursors, and assigns new cursors to the records. The endpoints.collectionInfo field returns additional information about endpoints in the collection, including information about endpoints that responded to the query, and an endpoints.collectionInfo.startCursor cursor value. This value always points to the first cursor in the collection; you can reference this cursor value to refresh a collection.
Use the endpoints (refresh) argument to refresh an endpoints collection and the associated cursors.
Use the following syntax to refresh a paginated endpoint records collection and the associated cursors, such as when you expect the set of endpoints to update after your initial query, and you retrieved endpoints.collectionInfo.startCursor in a prior query:
endpoints (refresh: <Cursor>)
The following example returns the startCursor value and additional endpoint information:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query endpointsQueryCollectionInfo {
endpoints {
edges {
node {
name
id
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
collectionInfo {
active
contributedTotal
expectedTotal
respondedPercentage
respondedTotal
startCursor
success
}
}
}
After you obtain the endpoints.collectionInfo.startCursor value, and more endpoints respond to the query, you can refresh the collection of endpoints by passing endpoints.collectionInfo.startCursor as the refresh argument value:
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
query endpointsQueryRefresh {
endpoints (refresh: <endpoints.collectionInfo.startCursor-value>){
edges {
node {
name
id
}
cursor
}
pageInfo {
startCursor
endCursor
hasPreviousPage
hasNextPage
}
totalRecords
collectionInfo {
active
contributedTotal
expectedTotal
respondedPercentage
respondedTotal
startCursor
success
}
}
}
Because the collection refresh also refreshes the collection's cursors, you must pass updated cursors the next time you want to query this updated collection.
Edge query syntax