The nova.openstack.common.db.sqlalchemy.utils Module

Implementation of paginate query.

exception InvalidSortKey

Bases: exceptions.Exception

message = u'Sort key supplied was not valid.'

paginate_query(query, model, limit, sort_keys, marker=None, sort_dir=None, sort_dirs=None)

Returns a query with sorting / pagination criteria added.

Pagination works by requiring a unique sort_key, specified by sort_keys. (If sort_keys is not unique, then we risk looping through values.) We use the last row in the previous page as the ‘marker’ for pagination. So we must return values that follow the passed marker in the order. With a single-valued sort_key, this would be easy: sort_key > X. With a compound-values sort_key, (k1, k2, k3) we must do this to repeat the lexicographical ordering: (k1 > X1) or (k1 == X1 && k2 > X2) or (k1 == X1 && k2 == X2 && k3 > X3)

We also have to cope with different sort_directions.

Typically, the id of the last row is used as the client-facing pagination marker, then the actual marker object must be fetched from the db and passed in to us as marker.

Parameters:

• query – the query object to which we should add paging/sorting
• model – the ORM model class
• limit – maximum number of items to return
• sort_keys – array of attributes by which results should be sorted
• marker – the last item of the previous page; we returns the next results after this value.
• sort_dir – direction in which results should be sorted (asc, desc)
• sort_dirs – per-column array of sort_dirs, corresponding to sort_keys

Return type:

sqlalchemy.orm.query.Query

Returns:

The query with sorting/pagination added.