lenskit.data.RecQuery#

class lenskit.data.RecQuery(user_id=None, history_items=None, session_items=None, context_items=None, query_source=None, user_items=None, query_id=None)#

Bases: object

Representation of a the data available for a recommendation query. This is generally the available inputs for a recommendation request except the set of candidate items.

Todo

Document and test methods for extending the recommendation query with arbitrary data to be used by client-provided pipeline components.

Todo

When LensKit supports context-aware recommendation, this should be extended to include context cues.

Stability:
Caller (see Stability Levels).
Parameters:
__init__(user_id=None, history_items=None, session_items=None, context_items=None, query_source=None, user_items=None, query_id=None)#
Parameters:
Return type:

None

Methods

__init__([user_id, history_items, ...])

combined_items(*sources)

Obtain a combined list of items from one or more sources.

create(data)

Create a recommendation query from an input, filling in available components based on the data type.

Attributes

all_items

Get a single list of all items mentioned in the query.

context_items

Items that form a context for the requested recommendations.

history_items

The items from the user's interaction history, with ratings if available.

query_id

An identifier for this query.

query_items

Return the items the recommender should treat as a “query”.

query_source

The list of items to return from query_items().

session_items

Items the user has interacted with in the current session.

user_id

The user's identifier, if known.

user_items

Deprecated alias for history_items.
user_id: int | str | bytes | integer[Any] | str_ | bytes_ | object_ | None = None#

The user’s identifier, if known.

history_items: ItemList | None = None#

The items from the user’s interaction history, with ratings if available. This list is deduplicated, like interaction_matrix(), rather than a full interaction log. As with user_row(), the rating is expected to be on a rating field, not score.

session_items: ItemList | None = None#

Items the user has interacted with in the current session.

context_items: ItemList | None = None#

Items that form a context for the requested recommendations. For example:

  • To recommend products related to a product the user is viewing, the viewed product is a context item.

  • To recommend products to add to a shopping cart, the current cart contents are the context items.

query_source: Literal['history', 'session', 'context'] | set[Literal['history', 'session', 'context']] | None = None#

The list of items to return from query_items().

user_items: ItemList | None = None#

Deprecated alias for history_items.

Deprecated since version 2025.6: Use history_items instead. This property will be removed in LensKit 2026.1.

query_id: int | str | bytes | integer[Any] | str_ | bytes_ | object_ | None = None#

An identifier for this query.

Query identifiers are used for things like mapping batch recommendation outputs to their inputs.

classmethod create(data)#

Create a recommendation query from an input, filling in available components based on the data type.

Parameters:

data (RecQuery | int | str | bytes | integer[Any] | str_ | bytes_ | object_ | ItemList | None) – Input data to turn into a recommendation query. If the input is already a query, it is returned as-is (not copied).

Returns:

The recommendation query.

Return type:

RecQuery

property query_items: ItemList | None#

Return the items the recommender should treat as a “query”.

This property exists so that components can obtain a list of items to use for generating recommendations, regardless of the precise shape of recommendation problem being solved (e.g., user-personalized recommendation or session-based recommendation). This allows general models such as ItemKNNScorer to operate across recommendation tasks.

The query_source attribute determines which list(s) of items in this query are considered the “query items”. If unset, the first of the following that is available are used as the query items:

  1. context_items

  2. session_items

  3. history_items

property all_items: ItemList | None#

Get a single list of all items mentioned in the query.

combined_items(*sources)#

Obtain a combined list of items from one or more sources.

Parameters:

sources (Literal['history', 'session', 'context'])

Return type:

ItemList | None