Direct Integration

Requirements

  • Java version >= 11

  • around 100MB to 500MB additional Java Heapspace (depending on the amount of data to be managed by the service)

  • If using a firewall, please adjust the configuration to allow connections to the following HTTPS Endpoints https://query.searchhub.io/ and https://import.searchhub.io/

Maven Dependency

The basic SmartSuggest library is part of the Open-Commerce-Search stack. In order to load the search|hub data, our searchhub-suggest-data-provider must be added to the classpath. All related components can be pulled as a maven dependency from our repository https://nexus.commerce-experts.com/content/repositories/searchhub-external/

<dependency>
    <groupId>de.cxp.ocs</groupId>
    <artifactId>smartsuggest-lib</artifactId>
    <version>0.19.0</version>
</dependency>
<dependency>
    <groupId>io.searchhub</groupId>
    <artifactId>searchhub-suggest-data-provider</artifactId>
    <version>1.1.1</version>
</dependency>

<!-- ... -->

<repository>
    <id>external-releases</id>
    <url>https://nexus.commerce-experts.com/content/repositories/searchhub-external/</url>
</repository>

Essential Usage

The QuerySuggester is the central object of the smartsuggest library. It is used to fetch the matching suggestions based on the (partial) user input. To get access to a QuerySuggester object, a single QuerySuggestManager must be built and maintained as a central reference. This is important as the QuerySuggestManager instance takes care of updating the suggest data should the data change. It can also be used to shutdown any QuerySuggesters and therefore free related resources.

A QuerySuggester instance can be accessed from the QuerySuggestManager using an “index name” as a parameter. The index name is the full tenant name used at search|hub. For example: “myshop.com”.

Alternatively you can specify index name to tenant mappings via ENV variable “SH_TENANT_MAPPINGS” or system property “searchhub.tenant_mappings”. Their value should be a comma separated list of key value pairs. Example: SH_TENANT_MAPPINGS=”indexname=tenant.name,myshop=myshop.com”

To load the correct data, the update process must get your searchHub API key, which you will receive during search|hub onboarding. This API key must be set either, as environment variable “SH_API_KEY” or, as system property “searchhub.apikey” within the Java environment.

Usage Example

The javadoc of the QuerySuggestManager.builder() methods tell you more about the available settings.

The last parameter of type ‘Set’ (where at this example simply ‘Collections.emptySet()’ is passed) is there for filtering suggestions according to their tags. However the data from SearchHub is not tagged yet, so any non-empty parameter will lead to 0 result. This feature is for later usage.

Options for QueryMapperManagerBuilder

When building a QuerySuggestManager - the central object that build and holds the QuerySuggest instances for all indexes, there are several options that can be set to change the default behaviour:

Adding Custom Data

The Suggest Library is build as service that takes care of updates on its own. So no external process is necessary to send data to the Suggest Library. Instead a SuggestDataProvider implementation is required, that encapsulates all the data loading.

Assume you have a database where your required data is managed and updated every now and then. Your SuggestDataProvider implementation needs to provide two pieces of information in advance:

  • Is there data for a given index?

  • What is the last time, this data was modified?

The modification time of your data is important, because the Suggest Library will only request the data itself, if it is not indexed yet or if the indexed data is older than the indexed data. The check for new data is done every minute by default and can be changed with the updateRate setting. If there is no modification timestamp in your database, you can either increase the updateRate or manage a custom modification time inside your SuggestDataProvider implementation that might only be incremented every N hours.

When loading data, the SuggestDataProvider implementation needs to produce all suggest records at once and provide a single big SuggestData object. Here an example what goes into that DTO:

Monitoring

SmartSuggest, optionally, provides internal metrics using the Micrometer framework. If you’d like to tap into those metrics, simply add the necessary Micrometer connector to your dependencies followed by, your desired MeterRegistry.

 // ...
 MeterRegistry meterRegistry = getYourMeterRegistryInstance();

 // example: to reveal metrics over JMX create a JmxMeterRegistry
 meterRegistry = new JmxMeterRegistry(JmxConfig.DEFAULT, Clock.SYSTEM);

 // and add it to the QueryMapperManager.builder afterwards
QuerySuggestManager.builder()
   // ...
   .addMetricsRegistryAdapter(MeterRegistryAdapter.of(meterRegistry));
   // ...

You will be able to track the following metrics:

smartsuggest.update.success.count.total

Total number of successful data updates per tenant. This metric is tagged with the corresponding tenant_name and tenant_channel.

smartsuggest.update.fail.count

Number of successive failed update attempts for a certain tenant. If an update succeeds, this value will be reset to “0”. If this value reaches “5”, the respective update process will be stopped and only restarted, if suggestions for the related tenant are requested again. This metric is tagged with the corresponding tenant_name and tenant_channel.

smartsuggest.suggestions.size

Current number of raw suggestion records per tenant. This metric is tagged with the corresponding tenant_name and tenant_channel.

smartsuggest.suggestions.age.seconds

That is the amount of time passed, since the last successful update took place. This metric is tagged with the corresponding tenant_name and tenant_channel.