Fetch Items-for-User Recommendations

The _items_for_user_recommendations query pipeline is created by default and configured to fetch items-for-user recommendations. It is similar to the default query pipeline that fetches content from your main collection, but it has an additional Recommend Items for User stage.

This pipeline is a template that you can use two different ways:

  • Use only the Recommend Items for User stage

    This method returns the set of recommended items for the specified user.

  • Query Solr directly

    This method returns complete documents about the recommended items from the _items_for_user_recommendations collection. The fields that are included in these recommender documents are configured in the recommender job’s itemMetadataJoinField/Item Metadata Join Field and itemMetadataFields/Item Metadata Fields fields; see Item metadata settings above.

Fetching recommendations from App Studio

App Studio can only access user-created collections; it cannot access system collections such as the default collections that Fusion creates for recommendations. If you are using App Studio to create your front-end search application, you must:

  • Create a new collection for item-for-item recommendations

  • Configure the recommender job to send output to the user-created collection instead of the system collection

  • Direct your queries to the user-created collection

Once this is done, you can fetch recommendations as usual, using either of the methods explained below.

Fetching with the Recommend Items for User stage

With this method, we use only one query pipeline stage: the Recommend Items for User query stage.

This method returns only the document IDs of the recommended items. Your search application must perform additional queries to retrieve the desired fields for those items, such as their names, images, categories, and so on.

How to fetch recommendations using the Recommend Items for User stage
  1. From your _items_for_user_recommendations collection, navigate to Querying > Query Workbench.

  2. Click Load…​ and open the _items_for_user_recommendations query pipeline, if it isn’t open already.

  3. Disable all of the pipeline stages except Recommend Items for User.

  4. Verify that the following fields are correctly configured in the Recommend Items for User query stage:

    • numRecommendations/Number of Recommendations

      This is the number of recommendations to return. It should be less than or equal to the value of the numSims/Number of Item Similarites to Compute parameter in the model tuning parameters of the <collection>_item_recommendations job configuration.

    • modelID/Model ID

      This must match the modelId/Recommender Model ID value in the recommender job’s model settings.

    • collection/Recommendation Collection

      This should be the collection specified in the outputItemSimCollection/Item-to-item Similarity Collection parameter of the recommender job’s Input/output settings.

    • resultsLocation/Results Location

      Select the As Response value for this field.

    • There are several fields that specify the names of fields that should be present in the documents in the _items_for_user_recommendations collection. Verify that these values match the field names in that collection.

    Be sure to click Apply after changing any of the stage configuration parameters.

  5. Click Save.

    Tip
    Save the modified pipeline as a new pipeline with a different name, to distinguish it from the default pipeline.
  6. Test the pipeline configuration:

    1. Select a user ID for testing by clicking show fields on any result in the _items_for_user_recommendations collection and copying the value of its userId field.

    2. In the search field, enter the parameter name userId and the value that you copied.

      For example, enter userId:5049 (substituting the value from your collection) and click the Search button.

      The number of results should be the same as the numRecs/Number of User Recommendations to Compute value in the _item_recommendations job (the default is 10).

    3. In the lower right, select View As: JSON:

      View as JSON

    4. Expand the items field and any of its Object fields:

      Recommend Items for User query stage

      Notice these important fields:

      • userId is the user to whom the recommendation pertains.

      • itemId is the recommended item.

      • weight is the estimated likelihood that the recommended item is of interest to the specified user.

  7. Get the query URI that your search application can use to retrieve recommendations from your modified pipeline:

    1. Click URI.

      The Query Workbench displays a Working URI and a Published URI.

      Query URI

    2. Click the Published URI to copy it to your clipboard.

      This is the URI and parameters that your search application should use to query for additional recommendations.

Tips:
  • Each time you query for recommendations, replace the userId parameter value with the ID of the user for whom you want recommendations.

  • Replace the Fusion hostname as needed, depending on your production environment.

  • As shown above, Fusion returns an array of item IDs and weights. Your search application must then query the main collection to retrieve the details about each of the recommended items.

    That is, for each itemId value returned from the recommendations collection, query for the corresponding id value in the main collection, and order the set of results according to the weight value from the recommendations collection.

    Tip
    You can eliminate these additional queries by configuring the join field and item metadata fields in the _item_recommendations job’s Item metadata settings. This copies the specified metadata fields from the main collection into the recommendations collection so that they can be retrieved in a single query. For example, if you specify name, url, category, image, or similar fields in the job configuration, then those are returned in the recommender results without the need for additional queries.

Querying Solr directly

With this method, we use only the Solr Query pipeline stage.

This method returns only the document IDs of the recommended items. Your search application must perform additional queries to retrieve the desired fields for those items, such as their names, images, categories, and so on.

How to fetch recommendations using the Solr Query stage
  1. From your _items_for_user_recommendations collection, navigate to Querying > Query Workbench.

  2. Click Load.

  3. Select the _items_for_user_recommendations query pipeline.

  4. Disable all stages in the pipeline except the Solr Query stage.

  5. Click Save.

    Tip
    Save the modified pipeline as a new pipeline with a different name, to distinguish it from the default pipeline.
  6. Test the pipeline configuration:

    1. Select a user ID for testing by clicking show fields on any result in the _items_for_user_recommendations collection and copying the value of its userId field.

    2. In the search field, enter the parameter name userId and the value that you copied.

      For example, enter userId:5049 (substituting the value from your collection) and click the Search button.

      The number of results should be the same as the numRecs/Number of User Recommendations to Compute value in the _item_recommendations job (the default is 10).

    3. In any of the search results, click show fields.

      Notice these important fields:

      • userId is the user to whom the recommendation pertains.

      • itemId is the recommended item.

      • weight is the estimated likelihood that the recommended item is of interest to the specified user.

  7. Get the query URI that your search application can use to retrieve recommendations from your modified pipeline:

    1. Click URI.

      The Query Workbench displays a Working URI and a Published URI.

      Query URI

    2. Click the Published URI to copy it to your clipboard.

      This is the URI and parameters that your search application should use to query for additional recommendations.

Tips:
  • Each time you query for recommendations, replace the userId parameter value with the ID of the user for whom you want recommendations.

  • Replace the Fusion hostname as needed, depending on your production environment.

  • As shown above, Fusion returns a set of results that each include an itemId and a weight. Your search application must then query the main collection to retrieve the details about each of the recommended items.

    That is, for each itemId value returned from the recommendations collection, query for the corresponding id value in the main collection, and order the set of results according to the weight value from the recommendations collection.

    Tip
    You can eliminate these additional queries by configuring the join field and item metadata fields in the _item_recommendations job’s Item metadata settings. This copies the specified metadata fields from the main collection into the recommendations collection so that they can be retrieved in a single query. For example, if you specify name, url, category, image, or similar fields in the job configuration, then those are returned in the recommender results without the need for additional queries.