The ResultSet class which is returned as result of an rql query

class cubicweb.rset.ResultSet(results, rql, args=None, description=None, rqlst=None)[source]

A result set wraps a RQL query result. This object implements partially the list protocol to allow direct use as a list of result rows.

  • rowcount (int) – number of rows in the result
  • rows (list) – list of rows of result
  • description (list) – result’s description, using the same structure as the result itself
  • rql (str or unicode) – the original RQL query string
column_types(*args, **kwargs)

return the list of different types in the column with the given col

Parameters:col (int) – the index of the desired column
Return type:list
Returns:the different entities type found in the column
complete_entity(row, col=0, skip_bytes=True)[source]

short cut to get an completed entity instance for a particular row (all instance’s attributes have been fetched)

description_struct(*args, **kwargs)

return a list describing sequence of results with the same description, e.g. : [[0, 4, (‘Bug’,)] [[0, 4, (‘Bug’,), [5, 8, (‘Story’,)] [[0, 3, (‘Project’, ‘Version’,)]]


iter on entities with eid in the col column of the result set

filtered_rset(filtercb, col=0)[source]

filter the result set according to a given filtercb

  • filtercb (callable(entity)) – a callable which should take an entity as argument and return False if it should be skipped, else True
  • col (int) – the column index
Return type:


get_entity(*args, **kwargs)

convenience method for query retrieving a single entity, returns a partially initialized Entity instance.


Due to the cache wrapping this function, you should NEVER give row as a named parameter (i.e. rset.get_entity(0, 1) is OK but rset.get_entity(row=0, col=1) isn’t)

Parameters:row,col (int, int) – row and col numbers localizing the entity among the result’s table
Returns:the partially initialized Entity instance

iterates over rows, and for each row eids are converted to plain entities

limit(limit, offset=0, inplace=False)[source]

limit the result set to the given number of rows optionally starting from an index different than 0

  • limit (int) – the maximum number of results
  • offset (int) – the offset index
  • inplace (bool) – if true, the result set is modified in place, else a new result set is returned and the original is left unmodified
Return type:



returns a printable rql for the result set associated to the object, with limit/offset correctly set according to maximum page size and currently displayed page when necessary


Retrieve exactly one entity from the query.

If the result set is empty, raises NoResultError. If the result set has more than one row, raises MultipleResultsError.

Parameters:col (int) – The column localising the entity in the unique row
Returns:the partially initialized Entity instance

return the result set’s origin rql as a string, with arguments substitued

related_entity(*args, **kwargs)

given an cell of the result set, try to return a (entity, relation name) tuple to which this cell is linked.

This is especially useful when the cell is an attribute of an entity, to get the entity to which this attribute belongs to.

searched_text(*args, **kwargs)

returns the searched text in case of full-text search

Returns:searched text or None if the query is not a full-text query
sorted_rset(keyfunc, reverse=False, col=0)[source]

sorts the result set according to a given keyfunc

  • keyfunc (callable(entity)) – a callable which should take an entity as argument and return the value used to compare and sort
  • reverse (bool) – if the result should be reversed
  • col (int) – the column index. if col = -1, the whole row are used
Return type:


split_rset(keyfunc=None, col=0, return_dict=False)[source]

splits the result set in multiple result sets according to a given key

  • keyfunc (callable(entity or FinalType)) – a callable which should take a value of the rset in argument and return the value used to group the value. If not define, raw value of the specified columns is used.
  • col (int) – the column index. if col = -1, the whole row are used
  • return_dict (Boolean) – If true, the function return a mapping (key -> rset) instead of a list of rset
Return type:

List of ResultSet or mapping of ResultSet

syntax_tree(*args, **kwargs)

return the syntax tree (rql.stmts.Union) for the originating query. You can expect it to have solutions computed and it will be properly annotated.


the result set according to a given column types

  • transformcb – a callable which should take a row and its type description as parameters, and return the transformed row and type description.
  • col (int) – the column index
Return type: