Setup

smartQuery module is delivered as a Java Library. If you’re running on Java, it is recommended to integrate it directly into your search infrastructure.

The HTTP/REST headless service is available for all other platforms or when external proprietary code is restricted. Delivered as public Docker image, it can be deployed on-premise or hosted by searchHub as a service. For optimal performance, we recommend running the service on-premise to minimize latency. The simple JSON API can be easily integrated using a generated OpenAPI client, a custom-built HTTP client, or one of our in-house clients.

Requirements

• Be sure the application is allowed to connect to the following HTTPS endpoints: https://query.searchhub.io/ and https://import.searchhub.io/

• In case fuzzy mapping is activated (true by default), running the library/service on better CPU is recommended. We are able to enable/disable fuzziness from our end during runtime, in case there should be any performance issues.

• The amount of memory heavily relies on the amount of data we get and preprocess for you. However due to the high efficient data structure, even a model with over 500k entries only needs around 300MB memory. The easiest way to find out the required memory for your system is to measure the initialized footprint.

Depending on the chosen integration type, these are additional requirements:

Java IntegrationHTTP Service

• The runtime environment must be able to verify Let’s Encrypt certificates

• Java version >= 17

• Memory: at least 100MB additional Java Heap space + more space depending on the amount of data to manage

Installation

Our continuous implementation build pushes the library into our own Maven repository and builds the according docker image right afterwards.

Java IntegrationHTTP Service (docker)PHP ClientJS Client

Add smartQuery as dependency to your project.

<dependency>
    <groupId>io.searchhub</groupId>
    <artifactId>smartquery</artifactId>
    <version>2.3.3</version>
</dependency>

<!-- ... -->

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

Client Setup

What you need for the first code to work:

• Your API Key

• The tenant name and channels that you can use (here we use “example.com”)

• some sample queries that lead to different outcomes. You might get some from us, otherwise look up some common misspellings with your account at my.searchhub.io. (In the examples here we assume “jeanss” to be mapped to “jeans”.)

Next you have to choose where to use smartQuery inside your application. Somewhere in your (backend) architecture there is place where the users query is either directly forwarded to a search engine endpoint or transformed into a technical query for your search engine (e.g. Elasticsearch, Solr). You should request smartQuery for a QueryMapping before that processing starts, so that the user query can be replaced or other instructions can be processed.

Keep in mind that after initializing smartQuery, there is an asynchronous process running in the background that fetches the first data. It needs several seconds until the data actually responds. For testing you can make this process blocking, but for production it should stay exactly like that.

Java IntegrationHTTP Service (curl)PHP ClientJS Client

The key class at the Java integration is the QueryMapperManager. It is responsible for initializing and managing the QueryMappers for one or more Tenants. It needs to be instantiated with the provided API key. It’s important to use a single QueryMapperManager object since it will internally spawn and manage several threads to update the QueryMapper instances asynchronously, and retain a reference to it.

// should be centrally managed, e.g. a singleton bean in application context
private final static QueryMapperManager qmManager;
static {
    qmManager = QueryMapperManager.builder()
                                  .apiToken("YourS3cr3tAPIkey")
    // preload will make the 'build' call to block until the data is loaded
                                  .preloadTenants("example.com")
                                  .build();
    // The Javadoc of the QueryMapperManager::builder methods
    // tell you more about the available settings.
}

public void searchProcess(HttpServletRequest req, HttpServletResponse resp)
{
    // init search process...
    Tenant tenant = new Tenant("example", "com");
    QueryMapper qm = qmManager.getQueryMapper(tenant);

    String searchQuery = req.getParameter("q");

    // in case the session-id of the searchHub collector is given, it should be used here.
    // If not, stick with 'null' because a different session leads to unwanted results!
    String shCookie = req.getCookieValue("SearchCollectorSession");
    QueryMapping mapping = qm.mapQuery(searchQuery, shCookie);
    if (mapping.hasRedirect()) {
        resp.setHeader("Location", mapping.getRedirect());
        resp.setStatus(302);
        return;
    } else {
        searchQuery = mapping.getSearchQuery();
    }

    // continue with search process...
}

// Optionally bind the qmManager instance to your JVM's lifecycle
// and close the QueryMapperManager during shutdown.
// Internally a ScheduledExecutorService is used, that will be stopped then.
@PreDestroy
public void onJvmShutdown() {
    qmManager.close();
}

Note

The API Key and the preload tenants are automatically populated with the same environment variables as the HTTP service: If the environment variable SH_API_KEY is available, the API Key is set to it. Same for SH_INIT_TENANTS that adds tenants to the list of preloaded tenants. In that case you can simple use QueryMapperManager.builder().build()

Now that you can fetch a QueryMapping, head over to the integration section to learn what to do with the different data retrievable by smartQuery.