Direct Integration

Requirements

  • Java with version >=1.8
  • around 200MB to 500MB additional Java Heapspace (depending on the amount of data it has to manage)
  • If a firewall is used, it needs to be configured to allow connections to the HTTPS Endpoints https://query.searchhub.io/ and https://import.searchhub.io/

Maven Dependency

The SmartQuery library can be pulled as a maven dependency from our private repository https://nexus.commerce-experts.com/content/repositories/searchhub-external/ [2].

[2]Access credentials to the private repository are provided separately.
<dependency>
    <groupId>io.searchhub</groupId>
    <artifactId>smartquery</artifactId>
    <version>0.11.0</version>
</dependency>

<!-- ... -->

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

Essential Usage

The library contains the following three central types:

Tenant
Simple POJO that represents a single data domain. See the glossary about what a Tenant is.
QueryMapper

The central component provided by the SmartQuery library is the QueryMapper. It provides a single and simple method mapQuery.

String mapQuery(String input):
 This method returns a mapped string, if the mapping process was successful and null if not. In such case the input String should be used.
QueryMapperManager

This class is responsible to initialize and manage the QueryMappers for the required Tenants. It needs to be instantiated with the provided API key [3]. It’s necessary to use a single QueryMapperManager object and keep the reference to it, since it will internally spawn and manage several threads to update the QueryMapper instances asynchronously.

QueryMapper getQueryMapper(Tenant t):
 

The getQueryMapper method will always return the same instance of QueryMapper for the same given Tenant, so it’s not necessary to keep a reference of the QueryMapper. Keeping a reference of a QueryMapper instance isn’t a problem though, since each QueryMapper will be updated in the background.

A non existing tenant won’t cause an error but simply return a QueryMapper that always returns null.

[3]You’ll receive your personal API Key directly from us.

Usage Example

private QueryMapperManager qmManager = QueryMapperManager.builder()
                                         .apiToken("YourApiKey")
                                         .updateRate(360)               // optional
                                         .preloadTenants("example.com") // optional
                                         .build();

public String getSearchQuery(String userQuery)
{
    Tenant tenant = new Tenant("example", "com");
    QueryMapper qm = qmManager.getQueryMapper(tenant);

    String mappedQuery = qm.mapQuery(userQuery);
    return mappedQuery != null ? mappedQuery : userQuery;
}

// It's recommended to 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();
}

The javadoc of the QueryMapperManager.builder() methods, tell you more about the possible settings.

Monitoring

SmartQuery optionally exposes internal metrics using the Micrometer framework. If you’d like to get those metrics, add the wanted Micrometer connector to your dependencies and add the according MeterRegistry.

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

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

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

// ...

You will be able to track the following metrics:

smartquery.statsCollector.queue.size
Current number of items inside the transmission queue of the stats-collector. Since the queue size is limited to 500 entries per default, a higher value should never appear. Hitting that limits is an indicator for a broken connection to the stats API.
smartquery.statsCollector.bulk.size.count
smartquery.statsCollector.bulk.size.sum
smartquery.statsCollector.bulk.size.max
The stats-collector’s bulk size metrics describe, how big the bulks are that were sent to the search|hub stats API. With sum/count the average size can be calculated. Max is the biggest bulk since application start.
smartquery.statsCollector.fail.count.total
Total amount of failed transmissions, that were reported to the stats API.
smartquery.update.fail.count
Number of failed mapping update attempts for a certain tenant in a row. If an update succeeds, this value will be reset to “0”. If this value reaches “5”, the according update process will be stopped and only started again, if mappings for the according tenant are requested again. This metric is tagged with the according tenant_name and tenant_channel.
smartquery.update.success.count.total
Total number of successful data updates per tenant. This metric is tagged with the according tenant_name and tenant_channel.
smartquery.mappings.size
Current number of raw mapping pairs per tenant. This metric is tagged with the according tenant_name and tenant_channel.
smartquery.mappings.age.seconds
That is the passed time, since the last successful mapping update. This metric is tagged with the according tenant_name and tenant_channel.