1. Docs
  2. Cloaked Search
  3. Usage
  4. Querying
  5. Query String
  1. Docs
  2. Cloaked Search
  3. Usage
  4. Querying
  5. Query String

Query String Query

Cloaked Search supports a strict syntax that is a subset of the search service’s query string query.

This syntax allows you to search across both protected and non-protected fields using familiar search concepts such as exact phrase matches, substring searches, and more.

Adding tenant_id to queries

In most contexts, searches will probably yield the best results if the rest of the query is AND‘d with the +tenant_id.keyword:<id> clause.

Esquery
title:"War of 1812" AND title:"USS Francis" AND +tenant_id.keyword:someid

A similar idea would be to encapsulate the rest of the query as a subquery with a + modifier.

Esquery
+(title:"War of 1812" AND title:"USS Francis") +tenant_id.keyword:someid

WARNING: Without one of these options, search results are only guaranteed to match the specified tenant and may not match any other parts of the overall search. This would result in seemingly random documents for a tenant to be returned.

Fields

Data stored in protected fields must be identified by field when querying. You can search over a protected field by typing the field’s name followed by a colon and then the search term. If you want to specify multiple terms, you will need to need to use a subquery and boolean operators.

Note: standard Elasticsearch and OpenSearch allow queries which don’t specify a field, causing the search to be over the default field(s). Because Cloaked Search applies a different transformation to terms in each protected field, you must specify the field whenever you search over protected fields. While it is still possible to search over non-protected default fields without specifying the field name, we recommend always specifying field names in the queries for clarity.

Sub-queries

Cloaked Search supports using parentheses to group clauses to form subqueries. This is especially useful for controlling the logic when using Boolean Operators.

To find documents relating to tuna fish sandwiches or tuna fish salad:

Esquery
body:((tuna AND fish) AND (salad OR sandwich)) AND +tenant_id.keyword:someid

Boolean Operators

Cloaked Search supports several boolean operators that allow you to combine various terms and fields. By default, all terms in the query are optional. Using these operators can help refine searches by requiring or excluding terms from the result.

Note: Precedence rules are not the same with all of these operators. When using traditional boolean operators (OR, AND and NOT), it is recommended to use subqueries to ensure the operators are applied in the expected order.

+ (Must)

+ is the “must” operator. Putting it before a term will ensure that the term exists in the result. Terms without the + remain optional and will help increase the relevance of the result.

To search for documents about foxes that may be quick or brown, use the query:

Esquery
(body:quick body:brown +body:fox) AND +tenant_id.keyword:someid

- (Must not)

- is the “must not” operator. Putting it before a term will exclude results that contain that term.

To search for documents about the Amazon rainforest, use the query:

Esquery
(title:Amazon body:rainforest -body:shopping -body:Bezos) AND +tenant_id.keyword:someid

OR

The OR operator matches documents where either term exists anywhere in the given field. This is equivalent to a union of sets of documents that contain one of the terms.

The OR operator is the default operator for multiple terms. This means that if there is no operator between two terms, and an alternative default operator has not been set for the search service, the OR operator will be used automatically.

To search for documents about different forms of transportation, use the query:

Esquery
(title:planes OR title:trains OR title:automobiles) AND +tenant_id.keyword:someid

AND

The AND operator matches documents where both terms exist anywhere in the given fields. This is equivalent to an intersection of sets of documents that contain one of the fields.

To search for documents about monkeys in space, use the query:

Esquery
(title:space AND title:monkey) AND +tenant_id.keyword:someid

Cloaked Search supports prefix queries only when the index_prefixes field mapping option is enabled.

The following would match documents with either “italian” or “italics” in the body field.

Esquery
body:ita* AND +tenant_id.keyword:someid

Cloaked Search supports phrase queries only when the index_phrases field mapping option is enabled.

The following would match documents with the phrase “billy goat” in the body field. Note that you may need to escape the quotation marks around the phrase.

Esquery
body:"billy goat" AND +tenant_id.keyword:someid

Unsupported

The following types of queries are not currently supported:

  • Fields other than strings, numbers, or booleans
  • Range queries
  • Regex matches
  • Mid-word wildcards
  • Suffix searches
  • Aggregations
  • Proximity requirements
  • Synonym expansions
  • Searches across multiple tenants