Setup
=====

smartSuggest is a library built on top of Apache Lucene that provides high-quality query and product suggestion capabilities. The Java library can be integrated directly into applications to build a custom suggestion service. Alternatively, it is also available as a ready-to-use HTTP service packaged as a container image.

Requirements
------------

- **Network Access:** The application must be able to connect to https://query.searchhub.io/, which is used to fetch the SearchHub suggestion data.
- **Temporary directory access:** The embedded Apache Lucene library creates several indexes in the system's temporary directory. Ensure the application has permission to write to the OS temp directory. The indexed data is volatile and does not require permanent persistence. When running inside the container image, this should work without additional configuration.
- **Memory requirements:** The service is designed to minimize memory usage. In typical setups, it requires approximately 100 MB to 500 MB of Java heap memory. The exact memory requirement may increase depending on the volume of data managed by the service.
- **Java Version:** For Java integration, JDK 17 or newer is required.


Installation
------------

Our continuous integration pipeline publishes the library to our internal Maven repository and subsequently builds the corresponding Docker image.

.. tabs::

    .. tab:: HTTP Service (docker)

      The docker image is available on docker hub with the name `commerceexperts/searchhub-smartsuggest-service <https://hub.docker.com/r/commerceexperts/searchhub-smartsuggest-service/tags>`_

      .. code-block:: bash

        docker run -d --name=smartsuggest-service -e SH_API_KEY=<YourS3cr3tAPIkey> -P commerceexperts/searchhub-smartsuggest-service:2.6.3

      The container must be initiated with your API key set to the environment variable `SH_API_KEY`.
      The container exposes port 8081 which can be mapped to any port.

    .. tab:: Java Integration

        The smartSuggest library comes as a single dependency from `our repository <https://nexus.commerce-experts.com/content/repositories/searchhub-external/>`_
        It contains several transitive dependencies that can all be loaded from the same repository, most also from public repositories like maven-central.

        .. code-block:: XML

            <dependency>
                <groupId>io.searchhub</groupId>
                <artifactId>smartsuggest</artifactId>
                <version>2.6.3</version>
            </dependency>

            <!-- ... -->

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

        The full embedded integration is described at the `Java Integration`_ section.


Client Setup
------------

.. tabs::

    .. tab:: HTTP Service (curl)

      For a pure Suggest integration, we recommend to use endpoint v3. But there are more different ones that might fit better to your needs. Continue reading the `Service Integration`_ for all according details.

      .. code-block:: bash

        $> port=38081
        $> tenant_name="example"
        $> tenant_channel="com"
        $> curl -s "http://localhost:$port/smartsuggest/v3/$tenant_name/$tenant_channel?userQuery=jea" -o - | jq .

    .. tab:: Java

        This is a quick start for setting up a minimal ``QuerySuggester``. Read the full `Java Integration`_ for all details.

        .. code-block:: java

            static QuerySuggestManager qsm;
            static {
                try {
                    qsm = io.searchhub.smartsuggest.SearchhubSuggestInitializer.getQuerySuggestManager(apiKey)

                            // optionally define where lucene should store the index files
                            .indexFolder(Files.createTempDirectory("smartsuggest"))

                            // optionally define which indexes/tenants should be loaded immediately
                            // Attention: This will cause synchronous loading, which is desired to block for a readiness probe
                            .preloadIndexes("example.com")

                            // the builder also has other options; finally build the QSM:
                            .build();
                }
                catch (IOException e) {
                    throw new UncheckedIOException(e);
                }
            }

            private List<String> suggestQueries(String userQuery, int maxSuggestions) throws IOException {
                return qsm.getQuerySuggester("example.com")
                        .suggest(userQuery, maxSuggestions, Collections.emptySet())
                        .stream()
                        .map(suggestion -> suggestion.getLabel())
                        .collect(Collectors.toList());
            }

    .. tab:: JS Client

      The JS Client comes only with the ability to connect to a SaaS Service so far. Therefor only tenant name is required for initialization.
      However additional it comes with the ability to do the splitting for an A/B test that can be evaluated by searchHub. Set this value to `false` unless other communicated.

      .. code-block:: javascript

        import {BrowserClientFactory} from "searchhub-js-client";

        const {smartSuggestClient, smartQueryClient, abTestManager} = BrowserClientFactory({
            tenant: "example.com",
            abTestActive: false
        });

        const suggestions = await smartSuggestClient.getSuggestions("jea");

      More code examples are available in the `clients repository <https://github.com/CommerceExperts/searchhub-js-client>`_.


Troubleshooting
----------------

  - Missing API Key: If no API key is specified, the container will terminate with the following log message:
    `"IllegalArgumentException: no searchHub API key provided! Either specify ENV var 'SH_API_KEY' or system property 'searchhub.apikey'"`
  - If the service attempts to access a tenant or channel that is not permitted (for example, due to an incorrect API key), the following message may appear in the logs:
    `Unauthorized while fetching data for tenant 'foo.bar': [401 Unauthorized]`
  - Enabling Debug Logging: To obtain more detailed information about internal processes, enable debug logging. When running the container, use the following Docker startup parameter: :code:`-e JAVA_TOOL_OPTIONS="-Dlog.searchhub.level=DEBUG"` For even more verbose logging, you can also enable root-level debug logging :code:`-Dlog.root.level=DEBUG`.


.. _tenant: ../glossary.html#tenant
.. _Micrometer: https://micrometer.io/docs
.. _Java Integration: java-integration.html
.. _Service Integration: service-integration.html