lenskit.data.RecQuery

class lenskit.data.RecQuery

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.

Changed in version 2026.1: Made arguments keyword-only, and removed the historical user_items attribute.

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).

query_id: lenskit.data.types.ID | tuple[lenskit.data.types.ID, Ellipsis] | None = None

An identifier for this query.

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

query_time: datetime.datetime | None = None

The time at which the query is issued.

Note

No LensKit models or data processing code currently makes use of this, but it is included for to support future time-aware modeling and replays of historical data.

user_id: lenskit.data.types.ID | None = None

The user’s identifier, if known.

history_items: lenskit.data._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: lenskit.data._items.ItemList | None = None

Items the user has interacted with in the current session.

context_items: lenskit.data._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: QueryItemSource | set[QueryItemSource] | None = None

The list of items to return from query_items().

classmethod create(data)

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

Parameters:

data (QueryInput) – 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: lenskit.data._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

Return type:

lenskit.data._items.ItemList | None

property all_items: lenskit.data._items.ItemList | None

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

Return type:

lenskit.data._items.ItemList | None

combined_items(*sources)

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

Parameters:

sources (QueryItemSource)

Return type:

lenskit.data._items.ItemList | None