cubicweb.rset
¶
The ResultSet class which is returned as result of an rql query
- class cubicweb.rset.ResultSet(results, rql, args=None, description=None, variables=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.
- Parameters
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
- all(col=0)¶
iter on entities with eid in the col column of the result set
- column_types(**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(**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’,)]]
- filtered_rset(filtercb, col=0)[source]¶
filter the result set according to a given filtercb
- Parameters
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
ResultSet
- first(col=0)[source]¶
Retrieve the first entity from the query.
If the result set is empty, raises
NoResultError
.- Parameters
col (int) – The column localising the entity in the unique row
- Returns
the partially initialized Entity instance
- get_entity(**kwargs)¶
convenience method for query retrieving a single entity, returns a partially initialized Entity instance.
Warning
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
- iter_rows_with_entities()[source]¶
iterates over rows, and for each row eids are converted to plain entities
- last(col=0)[source]¶
Retrieve the last entity from the query.
If the result set is empty, raises
NoResultError
.- Parameters
col (int) – The column localising the entity in the unique row
- Returns
the partially initialized Entity instance
- 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
- Parameters
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
ResultSet
- limited_rql()[source]¶
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
- one(col=0)[source]¶
Retrieve exactly one entity from the query.
If the result set is empty, raises
NoResultError
. If the result set has more than one row, raisesMultipleResultsError
.- Parameters
col (int) – The column localising the entity in the unique row
- Returns
the partially initialized Entity instance
- possible_actions(**kwargs)[source]¶
Return possible actions on this result set. Should always be called with the same arguments so it may be computed only once.
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(**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
- Parameters
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
ResultSet
- split_rset(keyfunc=None, col=0, return_dict=False)[source]¶
splits the result set in multiple result sets according to a given key
- Parameters
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(**kwargs)¶
Return the cached syntax tree (
rql.stmts.Union
) for the originating query.You can expect it to have solutions computed and it will be properly annotated. Since this is a cached shared object, you must not modify it.