lenskit.data.RecQuery
=====================

.. py:class:: lenskit.data.RecQuery
   :canonical: lenskit.data._query.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.

   .. versionchanged:: 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


   .. py:attribute:: query_id
      :type:  lenskit.data.types.ID | tuple[lenskit.data.types.ID, Ellipsis] | None
      :value: None


      An identifier for this query.

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


   .. py:attribute:: query_time
      :type:  datetime.datetime | None
      :value: 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.


   .. py:attribute:: user_id
      :type:  lenskit.data.types.ID | None
      :value: None


      The user's identifier, if known.


   .. py:attribute:: history_items
      :type:  lenskit.data._items.ItemList | None
      :value: None


      The items from the user's interaction history, with ratings if available.  This
      list is *deduplicated*, like :meth:`~lenskit.data.Dataset.interaction_matrix`,
      rather than a full interaction log.  As with :meth:`~lenskit.data.Dataset.user_row`,
      the rating is expected to be on a ``rating`` field, not ``score``.


   .. py:attribute:: session_items
      :type:  lenskit.data._items.ItemList | None
      :value: None


      Items the user has interacted with in the current session.


   .. py:attribute:: context_items
      :type:  lenskit.data._items.ItemList | None
      :value: 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.


   .. py:attribute:: query_source
      :type:  QueryItemSource | set[QueryItemSource] | None
      :value: None


      The list of items to return from :meth:`query_items`.


   .. py:method:: create(data)
      :classmethod:


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

      :param data: 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.



   .. py:property:: query_items
      :type: 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 :class:`~lenskit.knn.ItemKNNScorer` to operate across
      recommendation tasks.

      The :attr:`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. :attr:`context_items`
      2. :attr:`session_items`
      3. :attr:`history_items`


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


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


   .. py:method:: combined_items(*sources)

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