Configuring Unblu full-text search

Supported search engines

Unblu supports Elasticsearch 8.15.0 and OpenSearch 2.19.1.

Configuring the search engine

The discussion below only mentions the configuration properties for Elasticsearch. For the OpenSearch configuration properties, replace .es. in the properties' keys with .os..

Unblu relies on Elasticsearch or OpenSearch to provide full-text search.

Specify which search engine you use with Unblu in com.unblu.search.engine.type.
Provide Unblu with information about the search engine host. In most cases, that simply means setting com.unblu.search.engine.es.host to point to the search engine’s API endpoint. Unblu uses the value of this setting to access the search engine via HTTP(S).

You may need to specify a path prefix to the URL of the search engine’s API endpoint. This could be a requirement for the authentication mechanism you have in place, for example. You can do so with the configuration property com.unblu.search.engine.es.httpRequestPathPrefix.
Specify how Unblu should behave when trying to connect to the search engine during startup:
com.unblu.search.itemSearchLimit determines the number of items requested for each search request. If there are more results, Unblu triggers a new search once it reaches the end of the search results in the UI.

Authentication

Specify the authentication type in com.unblu.search.engine.es.authType or com.unblu.search.engine.os.authType.

For Elasticsearch, you can choose between the following types:
- API key (API_KEY)
- Basic authentication (BASIC), the default
- No authentication (NO_AUTH)
- TLS client certificate (TLS_CLIENT_CERTIFICATE)
- Token (TOKEN)
For OpenSearch, you can choose between the following types:
- Basic authentication (BASIC), the default
- No authentication (NO_AUTH)
- TLS client certificate (TLS_CLIENT_CERTIFICATE)

Each authentication type (except "no authentication") is discussed below.

If you run Unblu Spark on-premises and use self-signed certificates with your own certificate authority (CA), you can override the default CA for authenticating against the search engine with the following configuration properties:

com.unblu.search.engine.es.pathToTrustedCertsKeyStoreFile
com.unblu.search.engine.es.trustedCertsKeyStoreType
com.unblu.search.engine.es.trustedCertsKeyStorePassword

Authentication using an API key (Elasticsearch only)

If the authentication type is API_KEY, set the following configuration properties:

com.unblu.search.engine.es.apikeyId
com.unblu.search.engine.es.apikeySecret

Authentication with basic authentication

If Unblu should use basic authentication to access the search engine, set the following configuration properties:

com.unblu.search.engine.es.username
com.unblu.search.engine.es.password

Authentication with a TLS certificate (mTLS)

If Unblu should use mutual TLS authentication (mTLS, also referred to as PKI authentication) with the search engine, set the following configuration properties:

com.unblu.search.engine.es.pathToTLSClientCertificateKeyStoreFile
com.unblu.search.engine.es.tlsClientCertificateKeyStoreType
com.unblu.search.engine.es.tlsClientCertificateKeyStorePassword

Ensure that the certificate is in the PEM format and includes both the header and footer markers.

Unblu imports the certificate automatically.

Authentication with a token (Elasticsearch only)

If Unblu uses an authentication token to access the search engine, you must set com.unblu.search.engine.es.token.

Indexing

Before you can search through conversation messages in an Unblu account, you have to enable the message index Unblu created on startup. To do so, set com.unblu.conversation.index.enableIndexing to true. This tells Unblu Spark to send new messages to the search engine and to make it possible to search for messages.

The following configuration properties let you fine-tune the indexing operation:

Specify the number of shards for new indices in com.unblu.conversation.index.msg.numberOfShards. The default value is zero, which results in the index using the default number of shards configured in the search engine.

How many shards you should allocate to the message index will vary from one installation to the next. As a rule of thumb, however, the size of indices produced by Unblu is fairly small compared to most use cases.
Specify the number of replicas for new indices in com.unblu.conversation.index.msg.numberOfReplicas. The default value is zero, which results in the index using the default number of replicas configured in the search engine.
You can specify a prefix for the name of the message index in com.unblu.conversation.index.msg.indexNamePrefix. If you change this configuration property, you must reindex the documents.
com.unblu.search.engine.indexingLanguages defines the list of languages for which content are indexed using language-specific analyzers. If you change this configuration property, you must reindex the documents.
The configuration property com.unblu.search.engine.index.mappings.onInvalidMappings defines how Unblu should behave when comparing the index mapping versions on startup.
- If the mapping versions differ in the major or minor version number, Unblu marks the index for reindexing.
- If the mapping versions are the same or only differ in the patch version number, Unblu runs further low-level checks to make sure the mappings weren’t changed manually in the search index. If these checks turn up any discrepancies, Unblu uses this configuration property to determine what it should do:
  - LOG_WARN: Unblu logs a warning message
  - LOG_ERROR: Unblu logs an error message
  - MARK_FOR_REINDEX: Unblu marks the index for reindexing. This disables indexing and full-text search.
You can automatically trigger a reindex operation when the mappings of an index are out of date or incompatible with the current schema. To do so, set com.unblu.search.engine.index.mappings.autoReindexOnOutdatedMappings to true.