Querying documents

Querying Cloaked Search is very similar to querying Elasticsearch or OpenSearch. In fact, many of your existing queries may require only minimal changes. The most important requirement of querying Cloaked Search is that each query must specify the tenant ID of the documents you wish to search over (unless configured in fixed tenant mode). This can be done in one of two ways: with a bool query or a query_string query.

The field that specifies the tenant ID for search is configurable in the Cloaked Search Config, but for the examples here, we will assume it is tenant_id.keyword.

Bool query

The most common way to specify a tenant ID when querying is with a bool query. This requires you to add a top-level bool query where the filter clause specifies a term query with the tenant ID of the documents. The rest of your query will likely go into the bool query’s must clause.

With default configuration, this will look something like this:

JSON

{
  "query": {
    "bool": {
      "filter": {
        "term": {
          "tenant_id.keyword": "someid"
        }
      },
      "must": {
        (<...rest of the query...>)
      }
    }
  }
}

Query string query

If your query only contains a query_string query, then you can specify the tenant ID in it directly.

The rules for a valid tenant ID are:

1. The tenant ID field must be at the top-level of the query (not in a subquery).
2. Only one tenant ID field can be present at the top level.
3. The tenant ID field must be preceded by a +.
4. Tenant IDs themselves are not restricted to any specific characters. If non-alphanumeric characters are used, the ID must be quoted (e.g. +tenant_id:"an-id-with-dashes").

JSON

{
  "query": {
    "query_string": {
      "query": "+tenant_id.keyword:someid +(<...rest of the query...>)"
    }
  }
}

Debugging a Query

You can use the following flowchart to help debug a query that is erroring.