Pagination API

This section of the documentation describes the Pagination API for the QueryJobs endpoint. The API enables clients to request and view pages of the query result instead of being sent the full query result.

The Pagination API is a typical limit and offset pagination API controlled using URI query parameters. The parameters are as follows:

Parameter Type Valid values Description
paginationLimit Integer 0 - 2,147,483,647 The number of results to include in a page of results - it defines the page size.
paginationOffset Integer 0 - 2,147,483,647 The offset into the result from which to fetch paginationLimit results.
sortBy String Any string The field or column by which to sort the result.
sortOrder String asc, desc The order in which to sort the result. "asc" defines an ascending order and "desc" defines a descending order.
onlyHeartbeat Boolean true, false Set to true if this request is a heartbeat. A heartbeat keeps the result alive, without returning any results on this request.

Requests are made using GET requests to the following endpoint:

HTTP
GET /api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID

You specify the repository name, and the ID for the query job you are polling for results as part of the URL. You also specify query parameters as described in the previous table.

Using the Pagination API

A minimal example for using the API is to provide a limit parameter with a value. In this case, the offset is assumed to be 0, which corresponds to the very first page and a result consisting of the first paginationLimit rows is returned. If there are fewer than paginationLimit rows, then the entire result is returned.

In the following example, the first ten results of the query are returned, provided that there are ten results to return:

Mac OS or Linux (curl)
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Mac OS or Linux (curl) One-line
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Windows Cmd and curl
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10 ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json"
Windows Powershell and curl
powershell
curl.exe -X GET 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    "https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10';

my $req = HTTP::Request->new("GET", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");


my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10'

resp = requests.get(url,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

let request = https.get('https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10', (res) => {
  if (res.statusCode !== 200) {
    console.error(`Error from server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Response:');
    console.log(JSON.parse(data));
  });
});

    return(undef,undef);
}

To view additional results the paginationOffset parameter and arguments must be provided. The unit of the offset is that of number of rows in the results and not pages. To request the next or former full page, the difference between the current offset and the newly provided one must be paginationLimit. For example, if the paginationLimit is set to 10 and there are 200 events (rows), then the page layout of the query result becomes:

Page paginationOffset paginationLimit
1 0 10
2 10 10
3 10 10
... ... ...
20 resultBufferSize - paginationLimit = 200 - 10 = 190 10

An example request for page 3 of the above scenario, with a paginationOffset of 20, is as follows:

Mac OS or Linux (curl)
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Mac OS or Linux (curl) One-line
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20 \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Windows Cmd and curl
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20 ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json"
Windows Powershell and curl
powershell
curl.exe -X GET 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    "https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20';

my $req = HTTP::Request->new("GET", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");


my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20'

resp = requests.get(url,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

let request = https.get('https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20', (res) => {
  if (res.statusCode !== 200) {
    console.error(`Error from server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Response:');
    console.log(JSON.parse(data));
  });
});

    return(undef,undef);
}

Note

Requesting an offset that is not at least paginationLimit larger or smaller than the current offset gives an overlap in the returned results.

Sorting

The Pagination API enables sorting the result by a column (field) in the result. Query results sorted using the Pagination API are sorted in accordance with the numerical order of the sort() function, which sorts numbers numerically, and sorts anything that cannot be understood as a number lexicographically as being greater values than numbers. That is, if the result contains a mix of numbers and non-numbers, all non-numbers will be considered to be of greater value than any number, and in a descending order non-numbers will therefore show at the top of the result set. This sorting overrides any ordering imposed by the query itself.

Note

Polling without the sorting parameters gives the original order as defined by the query.

Sorting is not possible when not using the Pagination API. The Pagination API is considered in use if at least the paginationLimit is present. To sort by a certain column (field) of the result, you need to provide the sortBy parameter and the field name as an argument.

In order to sort the results in ascending order, you provide the sortOrder=asc parameter and argument pair, and for descending order, you provide sortOrder=desc. If no sortOrder is given, but sortBy is, then the sorting defaults to a descending order.

Similar to the previous example, but also includes sorting by the class field in ascending order:

Mac OS or Linux (curl)
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Mac OS or Linux (curl) One-line
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Windows Cmd and curl
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json"
Windows Powershell and curl
powershell
curl.exe -X GET 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    "https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc';

my $req = HTTP::Request->new("GET", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");


my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc'

resp = requests.get(url,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

let request = https.get('https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?paginationLimit=10&paginationOffset=20&sortBy=class&sortOrder=asc', (res) => {
  if (res.statusCode !== 200) {
    console.error(`Error from server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Response:');
    console.log(JSON.parse(data));
  });
});

    return(undef,undef);
}

Heartbeats

The Pagination API also includes the onlyHeartbeat query parameter. This is a special parameter that when set to true ensures that the query is kept alive without requiring a new poll request and transfer of the results.

Static queries and their results are removed 90 seconds after the last poll or heartbeat, meaning that heartbeats or polls are necessary to ensure that further pages are available, if, for example, a client inspects a particular page of results for longer than that.

If given the onlyHeartbeat parameter and true argument, the query is updated to stay alive for another 90 seconds. Unlike polls the rows (events) of the result are not returned when this option is present, regardless of other parameters and arguments. The query metadata is still returned.

The following example demonstrates applying a heartbeat to a query:

Mac OS or Linux (curl)
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Mac OS or Linux (curl) One-line
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json"
Windows Cmd and curl
shell
curl -v -X GET https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true ^
    -H "Authorization: Bearer $TOKEN" ^
    -H "Content-Type: application/json"
Windows Powershell and curl
powershell
curl.exe -X GET 
    -H "Authorization: Bearer $TOKEN"
    -H "Content-Type: application/json"
    "https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true"
Perl
perl
#!/usr/bin/perl

use HTTP::Request;
use LWP;

my $TOKEN = "TOKEN";

my $uri = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true';

my $req = HTTP::Request->new("GET", $uri );

$req->header("Authorization" => "Bearer $TOKEN");
$req->header("Content-Type" => "application/json");


my $lwp = LWP::UserAgent->new;

my $result = $lwp->request( $req );

print $result->{"_content"},"\n";
Python
python
#! /usr/local/bin/python3

import requests

url = 'https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true'

resp = requests.get(url,
                     headers = {
   "Authorization" : "Bearer $TOKEN",
   "Content-Type" : "application/json"
}
)

print(resp.text)
Node.js
javascript
const https = require('https');

let request = https.get('https://$YOUR_LOGSCALE_URL/api/v1/repositories/$REPOSITORY_NAME/queryjobs/$QUERY_JOB_ID?onlyHeartbeat=true', (res) => {
  if (res.statusCode !== 200) {
    console.error(`Error from server. Code: ${res.statusCode}`);
    res.resume();
    return;
  }

  let data = '';

  res.on('data', (chunk) => {
    data += chunk;
  });

  res.on('close', () => {
    console.log('Response:');
    console.log(JSON.parse(data));
  });
});

    return(undef,undef);
}

Note

If no heartbeat parameter is given, the request is assumed to not be a heartbeat.