Recommendation Queries

Overview

Recommendation queries enable the configuration of product recommendations in a variety of ways. Here are a few examples:

  • Create a recommendation query that returns similar products based solely on their attributes.
  • Implement a recommendation query that recommends products based on user actions within a single search session.
  • Use a recommendation query to suggest products based on their frequent occurrence together in the same order.

Sources

A recommendation query can utilize one or multiple sources. LupaSearch supports the following sources:

Similar attributes

This source recommends other products based on their static attribute similarity. It uses configured query fields and facets, derived from a related documentQueryKey. It does not have additional options.

Same session clicks

This source recommends products based on user behavior within a single search session. If a pair of products is frequently clicked by multiple users within the same search session, these products will be considered related. This source requires the implementation of the Events API.

Available options include:

  • 'Weight' (weighted importance of this source for recommender);

  • 'Max Age Days' (maximum session occurrence age in days to be included in recommender);

  • 'Min. Occurrences' (minimum number of co-occurrences of two item clicks in the same search session for the items to be related);

  • 'Top session count' (how many top sessions with given product id to include in calculations. Note: Larger values might affect performance).

Clicks by the same user

Recommends products based on user behavior in multiple search session. If the same pair of products is frequently clicked by multiple users, they will be considered related. Requires Events API API implementation.

Available options include:

  • 'Weight' (weighted importance of this source for recommender);

  • 'Max Age Days' (maximum item click age in days to be included in recommender);

  • 'Min. Occurrences' (minimum number of co-occurrences of two item clicks by different users for the items to be related);

  • 'Top session count' (how many top sessions with given product id to include in calculations. Note: Larger values might affect performance).

Bought together recommendations

Recommends products based on product pair occurences in a single order (user cart). Requires Events API API implementation with conversion events.

Available options include:

  • 'Weight' (weighted importance of this source for recommender);

  • 'Max Age Days' (maximum conversion age in days to be included in recommender);

  • 'Min. Occurrences' (minimum number of co-occurrences of two items in a cart for the items to be related).

Different sources can be combined in a single query by assigning each source a desired weight.

Filters

Similar to regular search queries, you can pre-configure various filters for your recommendations. For instance, it is straightforward to recommend only the products that are in stock:

{
  // ... Other configuration options,
  "filters": {
    "in_stock": [true]
  }
}

Recommendation filters can be overridden with a public recommendation query.

List recommendation queries using API

Use the following endpoint to fetch a list of recommendation queries for a given search index:

GET /indices/{indexId}/recommendationQueries

The successful response returns a list of recommendation queries in the index:

[
  {
    "id": "b5d54736-0f2d-4e5d-a362-3bc7bcfd46d2",
    "description": "Recommendation query description",
    "configuration": {
      "documentQueryKey": "doc-query-key",
      "sources": [
        {
          "type": "moreLikeThis",
          "weight": 100
        }
      ]
    },
    "queryKey": "r-xxxxxxxxxxxx",
    "createdAt": "2023-07-14",
    "updatedAt": "2023-07-15"
  }
]

Creating new recommendation query using API

Use the following endpoint to add a new recommendation query to a search index:

POST /indices/{indexId}/recommendationQueries

The body of the request should include a description and a configuration for the new query:

{
  "description": "Recommendation query description",
  "configuration": {
    "documentQueryKey": "<relatedDocumentQueryKey>",
    "filters": {
      "stock_status": ["IN_STOCK"],
      "price": {
        "gt": 10,
        "lt": 20
      }
    },
    "selectFields": ["id", "title", "description"],
    "limit": 10,
    "sources": [
      {
        "type": "moreLikeThis",
        "weight": 30
      },
      {
        "type": "boughtTogether",
        "weight": 40,
        "maxAgeDays": 365,
        "minOccurrences": 2
      },
      {
        "type": "session",
        "weight": 50,
        "maxAgeDays": 365,
        "topSessionCount": 200,
        "minOccurrences": 2
      },
      {
        "type": "user",
        "weight": 20,
        "maxAgeDays": 365,
        "topSessionCount": 200,
        "minOccurrences": 2
      }
    ]
  }
}

Configuration must include documentQueryKey. It will be used to retrieve default selectFields and filterableFields configuration, and relevant session and user behavior statistics.

A successful response returns the added recommendation query with created recommendation query key.

You can use the returned query key in public recommendation requests: Recommendations.

Updating recommendation query using API

Use the following endpoint to update a recommendation query:

PUT /indices/{indexId}/recommendationQueries/{recommendationQueryId}

The body of the request should include the updated configuration for the query:

{
  "description": "Updated query description",
  "configuration": {
    "documentQueryKey": "<relatedDocumentQueryKey>",
    "filters": {
      "stock_status": ["IN_STOCK"],
      "price": {
        "gt": 10,
        "lt": 20
      }
    },
    "selectFields": ["id", "title", "description"],
    "limit": 10,
    "sources": [
      {
        "type": "moreLikeThis",
        "weight": 30
      },
      {
        "type": "boughtTogether",
        "weight": 40,
        "maxAgeDays": 365,
        "minOccurrences": 2
      },
      {
        "type": "session",
        "weight": 50,
        "maxAgeDays": 365,
        "topSessionCount": 200,
        "minOccurrences": 2
      },
      {
        "type": "user",
        "weight": 20,
        "maxAgeDays": 365,
        "topSessionCount": 200,
        "minOccurrences": 2
      }
    ]
  }
}

Deleting recommendation query using API

Use the following endpoint to delete a recommendation query:

DELETE /indices/{indexId}/recommendationQueries/{recommendationQueryId}

A successful response indicates the successful deletion of the recommendation query.

Recommendation queries in LupaSearch Console

Recommendation queries can be configured in LupaSearch Console. To access configuration configuration, select desired index and chose "Recommendation Queries" in the main menu: Recommendation Queries.

When creating/editing a query you will have the ability to test your recommendation configuration without publishing it - in the same way as with regular search queries.