public interface ItemRecommender
Interface for recommending items. This interface provides APIs for both basic (recommend for a given user) and complex (recommend at most n items from a given set to the user) recommendation tasks.
The core idea of the recommend API is to recommend n items for a user, where the items recommended are taken from a set of candidate items and further constrained by an exclude set of forbidden items.
By default, the candidate set is the universe of all items the recommender knows about. The default exclude set is somewhat more subtle. Its exact definition varies across implementations, but will be the set of items the system believes the user will not be interested in by virtue of already having or knowing about them. For example, rating-based recommenders will exclude the items the user has rated, and purchase-based recommenders will typically exclude items the user has purchased. Some implementations may allow this to be configured. Client code always has the option of manually specifying the exclude set, however, so applications with particular needs in this respect can manually provide the sets they need respected.
If the recommender has an opinion about the order in which recommendations should be displayed, the result set will present items in that order. For many recommenders, this will be descending order by score; however, this interface does not guarantee a relationship between scores and ordering.
| Modifier and Type | Method and Description |
|---|---|
java.util.List<java.lang.Long> |
recommend(long user)
Recommend all possible items for a user using the default exclude set.
|
java.util.List<java.lang.Long> |
recommend(long user,
int n)
Recommend up to
n items for a user using the default exclude set. |
java.util.List<java.lang.Long> |
recommend(long user,
int n,
java.util.Set<java.lang.Long> candidates,
java.util.Set<java.lang.Long> exclude)
Produce a set of recommendations for the user.
|
ResultList |
recommendWithDetails(long user,
int n,
java.util.Set<java.lang.Long> candidates,
java.util.Set<java.lang.Long> exclude)
Produce a set of recommendations for the user with additional details.
|
java.util.List<java.lang.Long> recommend(long user)
Recommend all possible items for a user using the default exclude set.
user - The user ID.recommend(long, int, Set, Set)java.util.List<java.lang.Long> recommend(long user,
int n)
Recommend up to n items for a user using the default exclude set.
user - The user ID.n - The number of recommendations to return. Negative values request as many recommendations as possible.recommend(long, int, Set, Set)java.util.List<java.lang.Long> recommend(long user,
int n,
@Nullable
java.util.Set<java.lang.Long> candidates,
@Nullable
java.util.Set<java.lang.Long> exclude)
Produce a set of recommendations for the user. This is the most general recommendation method, allowing the recommendations to be constrained by both a candidate set \(\mathcal{C}\) and an exclude set \(\mathcal{E}\). The exclude set is applied to the candidate set, so the final effective candidate set is \(\mathcal{C} \backslash \mathcal{E}\).
The recommender is not guaranteed to return a full n recommendations. There are many reasons why it might return a shorter list, including lack of items, lack of coverage for items, or a predefined notion of a maximum recommendation list length. However, a negative value for n instructs the recommender to return as many as it can consistent with any limitations built in to its design and/or supporting algorithms.
user - The user’s IDn - The number of ratings to return. If negative, the recommender will return as many recommendations as possible.candidates - A set of candidate items which can be recommended. If null, all items are considered candidates.exclude - A set of items to be excluded. If null, a default exclude set is used.ResultList recommendWithDetails(long user, int n, @Nullable java.util.Set<java.lang.Long> candidates, @Nullable java.util.Set<java.lang.Long> exclude)
Produce a set of recommendations for the user with additional details. This method functions identically to recommend(long, int, Set, Set), except that it may produce more detailed results. Implementations may return subclasses of ResultList that provide access to additional details about each recommendation.
user - The user’s IDn - The number of ratings to return. If negative, then the recommender will return as many recommendations as possible.candidates - A set of candidate items which can be recommended. If null, all items are considered candidates.exclude - A set of items to be excluded. If null, a default exclude set is used.Double.NaN. For most scoring recommenders, the items will be ordered in decreasing order of score. This is not a hard requirement — e.g. set recommenders are allowed to be more flexible.