Sorting and Pagination

EOSC Performance database expects to include hundreds of results from multiple providers. Therefore, every query into the database has to be optimized to what it is really required by the user.

In addition, multiple list methods are public and available to the internet. Therefore, it is required for security reasons and performance that most responses from the API are paginated and limited.

Pagination response

API responses for list methods (called by GET) are limited by default to a maximum of 100 items per page. In order to provide the user with enough information about the omitted items (if any) on the search, a paginated body has always the following fields:

  • has_next: True if a next page exists.

  • has_prev: True if a previous page exists

  • items: The items for the current page

  • next_num: Number of the next page

  • prev_num: Number of the previous page.

  • page: The current page number (1 indexed)

  • pages: The total number of pages

  • per_page: The number of items to displayed on the page.

  • total: The total number of items matching the query

To control the returned page, you can configure the following arguments on the request query:

  • per_page: The number of items to be displayed on a page.

  • page: The page index to return.

Default query argument values (when not included) are per_page=100 and page=1. The maximum value for per_page is 100.

Note

Note that modifying the argument per_page might shift the items returned on previous pages therefore not matching with the expected page items. The number of global pages depends on the per_page assigned value.

Sorting response items

It is possible to sort the response items including sorting fields into the the sort_by argument. This argument is available on every list method for the main endpoints (/benchmark, /results, /sites and /flavors).

All sorting fields are composed by a sorting operator which defines the order of the sorting and a field id which indicates the field to use. In addition, it is possible to include more than one sorting requirement into the argument by separating them using commas , without spaces. Note the following available sorting operators and equivalent order:

  • +: Sorts the results in ascendant order. For example sort=+name
    ["item_1", "item_2", "item_3"]
    
  • -: Sorts the results in descendant order. For example sort=-name
    ["item_3", "item_2", "item_1"]
    

In the case of results, you might be interested into sorting by an specific result field inside the json attribute. This behavior is similar to the already explained into JSON Filters.

When sorting by a json field use a path separated by dots to indicate where to find the value you desire to use to sort. In addition, remember that in general it is a good idea to apply take a look into the benchmark schema related to the search you want to perform in order to ensure your filter applies. Sorting fields that are not available on the result are ignored.