Sense - a Cool JSON Aware Interface to Elasticsearch

Introduction

HTTP and JSON are the backbone for any work with Elasticsearch. Indexing, searching, administrative operations: Everything is done with HTTP and JSON. Most examples you will see are using cURL, the http client widely available on different systems. With cURL you pass the HTTP method and the body of a request as command line parameters.

While because of its availability on different systems cURL is great to be used for examples you might long for something more comfortable for your daily work. Enter Sense, a Chrome plugin for Elasticsearch.

Basics

After installing Sense, it will allow you to use a simpler query request format, offers code completion and a highlighted response section.

Like any extension, it can be started from the menu on the top right of Chrome. The UI consists of two larger panes, a white one on the left that is used to enter your requests to Elasticsearch and a black response section on the right. The host to be used can be configured in the top line and defaults to a local installation.

You will see that there already is an example query that you can immediately execute using the green arrow on the top right of the query pane. It queries the current instance for all documents of all types in all indices. If you are starting with a fresh Elasticsearch installation this will return an empty result list but you can immediately start with some examples from the Elasticsearch guide. Let’s index some data.

Copy and Paste

As so many examples are already using cURL Sense offers a nice copy and paste feature that translates cURL requests to the proper syntax to use for Sense. Just copy the following snippet to your clipboard:

curl -XPUT 'http://localhost:9200/twitter/tweet/1' -H 'Content-Type: application/json' -d '{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elastic Search"
}'

Mark all of the existing query in the left pane and press Ctrl-V to paste the text. You will notice that Sense automatically removes the cURL parameters and transforms the query to its internal syntax.

PUT /twitter/tweet/1
{
    "user" : "kimchy",
    "post_date" : "2009-11-15T14:12:12",
    "message" : "trying out Elastic Search"
}

Once you click the green arrow to execute the indexing query you will see the familiar response from Elasticsearch that your document has been indexed.

You can also go the other way around. If you’d like to get the cURL equivalent of a query you can mark it in the pane, press the little tool icon and choose Copy as cURL. You can then paste the result to a shell and execute the same command using cURL. The keyboard shortcut for this is Ctrl + Shift + C.

Autocompletion

Instead of copying and pasting we can of course also create the query ourselves. Remove all the existing text from the query pane and start typing GET. Sense will immediately offer a small tooltip with possible completions. Continue typing the / and you will notice that the popup has some internal knowledge of our Elasticsearch instance: It offers our index, twitter, that we just created.

We can continue to enter our query, e.g. a simple term query on the user:

GET /twitter/tweet/_search
{
    "query": {
        "term": {
           "user": {
              "value": "kimchy"
           }
        }
    }
}

If during any part of typing the query you are unsure what is allowed or wonder about the correct spelling you can always press Ctrl-Space to get a list of possible options. This powerful context sensitive completion can help a lot when experimenting with Elasticsearch.

History

When working with Sense you might notice that you did something exciting a while ago but can’t remember what you did. No need to undo all your edits; just open the history that can be accessed on the top right. It will show you the last 500 edits and you can choose one that you would like to execute again.

Structuring JSON

Sometimes requests and responses can become rather large with different indentation levels. To structure them you can use two features of Sense: Code indentation and code folding. If you don’t insert well indented code at first Sense can do the indentation for you: Just press Ctrl-I to have it formatted. And if your query or response really gets too long you can use the code folding feature. In the query as well as the response pane you can see little arrows at some line numbers. Those can be used to fold or unfold a code block. This can help a lot to make the JSON more approachable.

Conclusion

Sense is a fantastic tool for everyday work with Elasticsearch as well as for learning the query syntax. It will guide you with the queries, format everything correctly and do syntax highlighting on the query and response for you. If you’re not using it yet you should at least give it a try.

Editor’s Note (May 1, 2017): Starting with 6.0, any curl command to Elasticsearch containing content will require a valid content type header. As a result, this post has been updated to reflect this change and to set readers of this post up for success with future versions.