Mindmajix

Curl Syntax in Elasticsearch with Examples

Curl syntax

We use HTTP requests to talk to ElasticSearch. A HTTP request is made up of several components such as the URL to make the request to, HTTP verbs (GET, POST etc) and headers. In order to succinctly and consistently describe HTTP requests the ElasticSearch documentation uses cURL command line syntax. This is also the standard practice to describe requests made to ElasticSearch within the user community.

An example HTTP request using cURL syntax looks like this:

A simple search request using cURL.

curl -XPOST "http://localhost:9200/_search" -d'
  {
     "query": {
       "match_all": {}
     }
  }'

The above snippet, when executed in a console, runs the curl program with three arguments. The first argument, -XPOST, means that the request that cURL makes should use the POST HTTP verb. The second argument, “http://localhost:9200/_search” is the URL that the request should be made to. The final argument, -d'{…}’ uses the -d flag which instructs cURL to send what follows the flag as the HTTP POST data.

Whenever you see a request formatted using cURL syntax, you can either:

  • Copy it and execute it in a console (given that you have cURL installed).
  • Read it and translate it into whatever HTTP client that you are using.
  • Paste it into the left part of Sense.

When using the last option, pasting cURL formatted requests into Sense, Sense will recognize the cURL syntax and automatically transform it to a request formatted the Sense way. Sense also offers functionality for doing the opposite. When you have a request in Sense, you can click the wrench icon to bring up a dialog offering an option to “Copy as cURL”.

Copy as cURL dialog in Sense

The Copy as cURL dialog in Sense.

Hello world

For now, just run the below HTTP requests in Sense and take them at face value.

First, let’s index a simple document:

Indexing a simple document using cURL.

curl -XPOST "http://localhost:9200/my-first-index/message" -d'
  {
          "text": "Hello world!"
  }'

Now, let’s see if we can find it by searching for “hello”:

A search request searching for the word ‘hello’.

curl -XPOST "http://localhost:9200/_search" -d'
  {
     "query": {
        "query_string": {
            "query": "hello"
          }
       }
  }'

The response from ElasticSearch to the second HTTP request should look like the one below, containing a single hit.

Example response from ElasticSearch to the above request.

{
  "took": 12,
  "timed_out": false,
  "_shards": {
     "total": 12,
     "successful": 12,
     "failed": 0
  },
  "hits": {
     "total": 1,
     "max_score": 0.19178301,
     "hits": [
       {
            "_index": "my-first-index",
            "_type": "message",
            "_id": "AUqiBnvdK4Rpq0ZV4-Wp",
            "_score": 0.19178301,
            "_source": {
                "text": "Hello world!"
                }
            }
        ]
     }
  }

Curl syntax is programming language agnostic making it perfect to show HTTP interactions in a way that is both succinct and independent of any programming language. However, in the real world, except when debugging, we usually interact with ElasticSearch from our programming language of choice. Let’s look at a couple of examples of how the above requests could be implemented in actual applications.

Node.JS example

Elasticsearch Node.js client is official client for Node.js.

For Node.JS, we use the official JavaScript client which can be installed in a Node.JS application using npm install elasticsearch. A simple application that indexes a single document and then proceeds to search for it, printing the search results to the console, looks like this:

A simple implementation of the Hello World example in Node.JS.

var elasticsearch = require('elasticsearch');
var client = new elasticsearch.Client({
      host: 'localhost:9200'
  });
//An object that we'll index
  var theMessage = {
       text: "Hello world!"
  };
//Indexing the above object
  client.index({
      index: "my-first-index",
      type: "message",
      body: theMessage
  }).then(function() {
      setTimeout(search, 1100);
  });
//Searching and printing the results
  function search() {
       client.search({
           index: "my-first-index",
           type: "message",
           body: {
                query: {
                     query_string: {
                          query: "hello"
                         }
                      }
                    }
  }).then(function(response) {
     console.log("Number of hits: "
          + response.hits.total);
     response.hits.hits.forEach(function(hit) {
          console.log(hit._source.text);
        })
     });
  }

Note that we add a waiting period between indexing and searching. We do this because an indexed document won’t immediately be searchable after indexing. We have to wait for the index to be refreshed which by default happens every second. It’s possible to require ElasticSearch to immediately refresh the index when indexing a document but that’s bad performance wise and therefore we opt to wait a little.

.NET example

In the Node.JS example, we (naturally) used JavaScript and the official ElasticSearch client which more or less maps directly to ElasticSearch’s HTTP/JSON API. Therefore, the code for our Node.JS application looked quite similar to the original cURL based example. Now, let’s look how we can interact with ElasticSearch from a strongly typed language, C#, using a client library that introduces more abstractions, NEST.

In order to implement the Hello World example in C#, we start by creating a new console application to which we add the NEST ElasticSearch client using NuGet (PM > Install-Package NEST). Next, we create a class which we’ll index and search for instances of.

A C# class representing a message.

namespace HelloElasticSearch
  {
     public class Message
     {
         public Message(string text)
         {
            Text = text;
          }
        public string Text { get; private set; }
       }
  }

The entry point of our application which implements the Hello World example by indexing a message and then searching for it looks like this:

Basic example of indexing and searching using C# and the NEST client library.

using System;
  using System.Threading;
  using Nest;
namespace HelloElasticSearch
  {
      class Program
      {
          static void Main(string[] args)
           {
              //Create a client that will talk to our ES cluster
              var node = new Uri("http://localhost:9200");
               var settings = new ConnectionSettings(
                      node,
                      defaultIndex: "my-first-index"
              );
              var client = new ElasticClient(settings);
              //Creating and indexing a message object
              var theMessage = new Message("Hello world!");
              client.Index(theMessage);
             //Waiting for the index to be refreshed
                Thread.Sleep(1100);
            //Search for messages and print the results
             var response = client.Search<Message>(
                  body => body.Query(
                       q => q.QueryString(
                           qs => qs.Query("hello"))));
           Console.WriteLine("Number of hits: " + response.Total);
             foreach (var hit in response.Hits)
            {
               Console.WriteLine(hit.Source.Text);
             }
         }
     }
  }


0 Responses on Curl Syntax in Elasticsearch with Examples"

Leave a Message

Your email address will not be published. Required fields are marked *

Copy Rights Reserved © Mindmajix.com All rights reserved. Disclaimer.
Course Adviser

Fill your details, course adviser will reach you.