Signed search keys give you more control over a user's search experience. You can tailor the experience to show results you know are more relevant to the specific user while also letting you control what data the user can see and search over.

Signed search keys in <a href="https://www.elastic.co/app-search/">Elastic App Search</a> give you more control over a user's search experience. You can tailor the experience to show results you know are more relevant to the specific user while also controlling what data the user can see and search over.
 <h2>API keys in App Search</h2>Elastic App Search has the concept of <a href="https://www.elastic.co/guide/en/app-search/7.10/authentication.html#authentication-key-types">search keys and private keys</a>:
<ul>
	<li>A search key is prefixed with <code>search-</code> and can only be used to search over your engines.</li>
	<li>A private key is prefixed with <code>private-</code> and can create, update, and delete documents if the write-flag is enabled. It can also perform searches and reads if the read-flag is enabled.</li>
</ul>With both search keys and private keys, you can grant access to all engines or limit to specific ones.
Elastic App Search also has the concept of <a href="https://www.elastic.co/guide/en/app-search/7.10/authentication.html#authentication-signed">signed search keys</a>, which, as the name implies, you can only use to search. A signed search key is a JSON Web Token and is signed with an API key, ideally a read-only private key, using the HMAC with SHA-256 (HS256) algorithm.
If you have Node.js on your back end, this is how simple it is to generate a signed search key using the <a href="https://github.com/elastic/app-search-node">Elastic App Search Node.js client</a>:
<pre class="prettyprint">const AppSearchClient = require('@elastic/app-search-node');
const apiKey = 'private-xxxxxxxxxxxxxxxxxxxxxxxx';
const apiKeyName = 'key-for-signed-search';
const enforcedOptions = {
 result_fields: { title: { raw: {} } },
 filters: { world_heritage_site: 'true' }
};
const signedSearchKey = AppSearchClient.createSignedSearchKey(
 apiKey,
 apiKeyName,
 enforcedOptions
);
console.log(signedSearchKey);
</pre>Run the above code and you will generate a signed search key that looks something like this:
<pre class="prettyprint">eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXN1bHRfZmllbGRzIjp7InRpdGxlIjp7InJhdyI6e319fSwiZmlsdGVycyI6eyJ3b3JsZF9oZXJpdGFnZV9zaXRlIjoidHJ1ZSJ9LCJhcGlfa2V5X25hbWUiOiJrZXktZm9yLXNpZ25lZC1zZWFyY2giLCJpYXQiOjE2MDc1MzczOTB9.b_stzPl5uUfr_c5eAFDKSY-Lm5oH3M7lDDFGsnofL4k
</pre>Clients can use this signed search key just like they would any App Search search key.
What makes the signed search key special and quite powerful is that you can enforce search options and perform searches against the App Search API directly from your front end. The alternative is to have each search request go through your own back end, so you can enforce certain options yourself.
We can actually inspect the generated signed search key with the neat debugger on <a href="https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWx0ZXJzIjp7ImlzX2RyYWZ0IjoiZmFsc2UifSwiYXBpX2tleV9uYW1lIjoiY29kZXNhbmRib3gtZDg3YjdkNjZhOTcyNDIzZGFmMGViN2U5ZWExZTIxNmIiLCJpYXQiOjE2MDc0NzQyMTJ9.KMoex6mul699ry7qypIDlCFG1rMTdE-o5ahsLwyHSuk">jwt.io</a>. We can see that the example search filter we used, <code>world_heritage_site: true</code>, is embedded directly in this search key:
<pre class="prettyprint">{ 
 "result_fields": { 
 "title": { 
 "raw": {} 
 } 
 }, 
 "filters": { 
 "world_heritage_site": "true" 
 }, 
 "api_key_name": "key-for-signed-search", 
 "iat": 1607537390 
}
</pre> <h2>Marketplace example</h2>To explain and highlight specific use cases for signed search keys, we'll look at a marketplace where users can put items up for sale and purchase things from other sellers.
 <h3>User-scoped search</h3>Items in the marketplace can be in draft mode, meaning the user is not ready to make the item public just yet. So when the user performs a search, we can exclude the draft items by enforcing a filter:
<pre class="prettyprint">{ 
 "filters": { "is_draft": "false" } 
}
</pre>Apply this filter and regenerate a signed search key with it. We can inspect the generated signed search key with <a href="https://jwt.io/#debugger-io?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmaWx0ZXJzIjp7ImlzX2RyYWZ0IjoiZmFsc2UifSwiYXBpX2tleV9uYW1lIjoiY29kZXNhbmRib3gtZDg3YjdkNjZhOTcyNDIzZGFmMGViN2U5ZWExZTIxNmIiLCJpYXQiOjE2MDc0NzQyMTJ9.KMoex6mul699ry7qypIDlCFG1rMTdE-o5ahsLwyHSuk">jwt.io</a> again and see that the new filter is embedded within it.&nbsp;
You might wonder why we're indexing draft items into the App Search engine and then filtering the draft items out. By doing so, we’re able to create a "My Items" page. On that page, we want to show the authenticated user’s
<ul>
	<li>draft items</li>
	<li>current items</li>
	<li>sold items</li>
</ul>For that occasion, we would generate a separate signed search key and enforce a filter on the user ID:
<pre class="prettyprint">{ 
 "filters": { "user_id": user.id } 
}
</pre>As long as the item belongs to the current user, we don't need to filter out the draft items.
Again, by embedding filters into the user’s signed search key, we’re restricting the user’s searches to always apply those filters.
 <h3>User-relevant search</h3>If we know that the currently authenticated user is interested in specific categories, we could boost items from those categories. You could, for instance, derive this data from the user's purchase history. In addition to the draft filter, we can now enforce boosts in the generated signed search key:
<pre class="prettyprint">{ 
 "filters": { "is_draft": "false" }, 
 "boosts": { 
 "categories": [ 
 { 
 "type": "value", 
 "value": user.categories_of_interest, 
 "operation": "multiply", 
 "factor": 3 
 } 
 ] 
 } 
}
</pre> <h3>Anonymous search</h3>We should still enforce the draft filter for unauthenticated users, but we would also like to exclude specific fields from the results. The reasoning is that we include both <code>first_name</code> and <code>full_name</code> in the App Search document but only authenticated users should see <code>full_name</code>. The same applies to the <code>email</code> field.
The enforced options would, therefore, look like this:
<pre class="prettyprint">{ 
 "filters": { is_draft: "false" }, 
 "result_fields": { 
 "title": { raw: { } }, 
 "description": { raw: { } }, 
 "categories": { raw: { } }, 
 "image_url": { raw: { } }, 
 "published_at": { raw: { } }, 
 "country_code": { raw: { } }, 
 "country_name": { raw: { } }, 
 "first_name": { raw: { } } 
 } 
}
</pre> <h2>Demo</h2>You can check out a <a href="https://codesandbox.io/s/eas-signed-search-key-marketplace-tscle">CodeSandbox demo with the marketplace example</a>.
Please note that the demo has no back end to generate the signed search keys, but rather a Mirage JS mock server.
 <h2>Next steps</h2>We’ve seen how we can embed filters and boosts into signed search keys, and even exclude specific fields from the results. When a client searches using a generated signed search key, we can effectively create a personalized search experience.
If you’d like, check out <a href="https://www.elastic.co/elasticon/archive/2020/global/making-it-personal-tailoring-content-with-signed-search-keys">Making it personal: Tailoring content with signed search keys</a>, a presentation from our recent ElasticON Global virtual event (along with <a href="https://www.elastic.co/elasticon/global/agenda">dozens of other presentations</a> across all Elastic solutions). And, as always, you can try out Elastic App Search, and all of the Elastic Stack, with a <a href="http://cloud.elastic.co/registration">free 14-day trial of Elastic Cloud</a> (or a free <a href="https://www.elastic.co/downloads/enterprise-search">download</a>).

blog-banner-release-app-search.png

blog-thumb-release-app-search.png

Personalizing content with signed search keys in Elastic App Search

Elastic App Search beta5 has arrived! Take it for a free test drive.

Elastic App Search Beta 5 released

Elastic App Search has been upgraded to beta4. Come try it out for free while the beta is still open!

Elastic App Search Beta 4 released

Elastic App Search now has a slick Query Suggestions API. Its function is known by many names, but whatever you call it, it helps make great search experiences.

The&nbsp;Query Suggestion API&nbsp;is now available within&nbsp;<a href="https://www.elastic.co/app-search/service">Elastic App Search</a>. "Did you mean autocomplete?"Ah, yes, thanks — we can call it that, or typeahead, or autosuggest. While the name of the technique might differ, the constant is that query suggestions can greatly improve a search experience. Read along to learn more, or&nbsp;<a href="https://swiftype.com/documentation/app-search/api/query-suggestion">visit the documentation</a>&nbsp;to get building.<img src="https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blta58798bd58c17fb0/5c98d7ce55e02a1e5a5e9b1e/query-suggestions.gif" data-sys-asset-uid="blta58798bd58c17fb0" alt="query-suggestions.gif"><h2>Suggestive!</h2>As a user types a query, the&nbsp;Query Suggestion API&nbsp;looks for strong queries to suggest. Herein lies the key: the endpoint does not suggest results.&nbsp;A quality search experience, by its nature, will provide the most relevant results.&nbsp;But sometimes users have trouble finding the right words to use when searching, and this endpoint can help them.Imagine we have a search engine full of outdoor parks;&nbsp;we indexed all of our park objects into an Elastic App Search Engine, and they are ready to be searched upon. &nbsp;A document might look like this:<pre class="”prettyprint”" style="font-size: 12.600000381469727px;"> {
 "nps_link": "https://www.nps.gov/zion/index.htm",
 "title": "Zion",
 "date_established": "1919-11-19T06:00:00+00:00",
 "world_heritage_site": "false",
 "states": [ "Utah"],
 "description": "Located at the junction of the Colorado Plateau, Great Basin, and Mojave Desert, this park contains sandstone features such as mesas, rock towers, and canyons, including the Virgin River Narrows. The various sandstone formations and the forks of the Virgin River create a wilderness divided into four ecosystems: desert, riparian, woodland, and coniferous forest.",
 "visitors": 4295127,
 "id": "park_zion",
 "location": "37.3,-113.05",
 "square_km": 595.8,
 "acres": 147237.02
 }
</pre>When a user conducts a search within our application, we have decided to match results based on the&nbsp;state&nbsp;and&nbsp;title&nbsp;fields of the park documents. That way, someone can type the name of the park they want to visit or the state that it is located, and receive relevant results.Now let us put ourselves in the shoes of a searcher...A friend told them about a beautiful park, but they cannot quite remember its name. It's Zion National Park, but they don't know that yet.They want to search for it and book a ticket to visit it.“It started with a Z… Zeyeon, maybe?… Hmm…”And so they attempt a search for “zeyeon”, first without query suggestions:<pre class="”prettyprint”" style="font-size: 12.600000381469727px;"> {
 "meta": {
 "warnings": [],
 "page": {
 "current": 1,
 "total_pages": 0,
 "total_results": 0,
 "size": 10
 },
 "request_id": "85b78b8f32ac81253cc1654e540e0625"
 },
 "results": []
 }
</pre>No surprise, the query returns zero results.Even with accurate relevance, that query is not even close to the&nbsp;matching "Zion"&nbsp;document.&nbsp;We don't want the user to get discouraged and end their search.&nbsp;When using&nbsp;query suggestions,&nbsp;their search experience might go like this:”Hmmm… There was a z”…<pre class="”prettyprint”" style="font-size: 12.600000381469727px;"> curl -X POST 'https://host-2376rb.api.swiftype.com/api/as/v1/engines/sample-engine/query_suggestion' \
 -H 'Content-Type: application/json' \
 -H 'Authorization: Bearer search-7eud55t7ecdmqzcanjsc9cqu' \
 -d '{
 "query": "z",
 "types": {
 "documents": {
 "fields": [
 "title",
 "states"
 ]
 }
 },
 "size": 4
 }'
</pre>”That’s right! Zion National Park! Time to book a ticket!”<pre class="”prettyprint”" style="font-size: 12.600000381469727px;"> {
 "results": {
 "documents": [
 {
 "suggestion": "zion"
 }
 ]
 },
 "meta": {
 "request_id": "8d37831753eb9d5636a761f5fb3d6767"
 }
 }
</pre>The right&nbsp;title&nbsp;value, “zion”, returned as a suggestion. The suggestion can then be used to fuel their actual search.&nbsp;By guiding the searcher through the querying process, we help them assemble the most effective searches.<h2>May We Also Suggest...</h2>The&nbsp;Query Suggestion API&nbsp;is but one tool in a robust, relevance improving search toolbox.Other valuable tools include&nbsp;<a href="https://swiftype.com/documentation/app-search/guides/synonyms">Synonyms</a>, which build groupings of similar search terms.A search for any synonym will return results relevant to the entire set.The prototypical example of a synonym set is for car: car, automobile, vehicle. &nbsp;Or, in the park, consider mountains: mountain, cliff, peak, summit:<img src="https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt56e26c8d50b0a8c1/5c57d3cbc545afde0bc7082c/synonym.png" data-sys-asset-uid="blt56e26c8d50b0a8c1" alt="synonym.png">Another tool is&nbsp;<a href="https://swiftype.com/documentation/app-search/guides/relevance-tuning">Relevance Tuning</a>, which can boost the relevance of documents given certain field values, and tune the baseline scoring weight attributed to each field.You can boost results given their proximity to a location coordinate provided by the user:&nbsp;“Find the park nearest to me!”&nbsp;Or tune your&nbsp;title&nbsp;field so its matches reward&nbsp;greater than those of other fields:<img src="https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/bltf5eb29dbd2c87a0a/5c57d3c54c9f4feb0b4c581f/relevence-tuning.png" data-sys-asset-uid="bltf5eb29dbd2c87a0a" alt="relevence-tuning.png">Finally, there are curations: curate the results of certain queries.Perhaps you sell “tea” and you want a certain seasonal tea ranked first &nbsp;for “green tea” queries. Or if something is out of stock or season, and you want to hide it from your result sets.With outdoor parks, we want to promote Rocky Mountain Park for those who query “mountains”:<img src="https://images.contentstack.io/v3/assets/bltefdd0b53724fa2ce/blt6e57cd17d7347368/5c57d3c0eab90dd80b53ee7e/curations.png" data-sys-asset-uid="blt6e57cd17d7347368" alt="curations.png">All of these tools have refined APIs and matching dashboard UIs, and are informed through fully API-digestible analytics, which can be organized with tags to&nbsp;<a href="https://swiftype.com/documentation/app-search/guides/tags">automate deep relevance tuning</a>&nbsp;of your search experience.<h2>Summary</h2>The&nbsp;Query Suggestion API&nbsp;will help your users find the right words. When paired with the rest of the relevance refining features in Elastic App Search, we think you’ll enjoy seeing people find just the think they are seeking. The API is also available within the&nbsp;<a href="https://github.com/swiftype/swiftype-app-search-javascript">App Search JavaScript</a>&nbsp;client and the <a href="https://swiftype.com/documentation/app-search/guides/reference-ui">Reference UI</a>.You can get started today with a &nbsp;<a href="https://www.elastic.co/app-search/service?elektra=query-suggestion-api-blog">free 14 day trial</a>&nbsp;of our hosted version or &nbsp;<a href="https://elastic.co/downloads/app-search">download the beta</a>&nbsp;of the self-managed version.&nbsp;Each new trial comes preloaded with the National Parks data set, so you can experiment before bringing your own data.

AUTHOR

Articles by Orhan Toy

Personalizing content with signed search keys in Elastic App Search

Elastic App Search Beta 5 released

Elastic App Search Beta 4 released

Elastic App Search: Query Suggestion API Now Available

Sign up for Elastic Cloud free trial

Products & Solutions

Company

We're hiring

Resources

Solutions

Elastic (ELK) Stack

New

Featured topics

News

AUTHOR

Articles by Orhan Toy

Personalizing content with signed search keys in Elastic App Search

Elastic App Search Beta 5 released

Elastic App Search Beta 4 released

Elastic App Search: Query Suggestion API Now Available

Sign up for Elastic Cloud free trial

Company

We're hiring

Resources