Quickstart

A quick guide for installing and using elasticsearch-lua.

Installation

  • Directly using luarocks:

    $ luarocks install elasticsearch
    
  • Using elasticsearch as a dependency in your project

    • Add elasticsearch in your ‘rockspec’:

      dependencies = {
        "elasticsearch"
      }
      
    • Install dependencies using luarocks:

      $ luarocks install <your_rockspec_file>
      

Setting up Client

Requiring elasticsearch in source file:

local elasticsearch = require "elasticsearch"

Creating a client:

local client = elasticsearch.client{
  hosts = {
    {
      host = "localhost",
      port = "9200"
    }
  }
}

Note

host and port are optional. In case any parameter is not specified, host defaults to ‘localhost’ and port defaults to ‘9200’.

Operations

elasticsearch-lua uses Lua tables to pass parameters for any operation. Common keys include index, type, id and body. Each kind of operation may have additional parameters. The body itself is a Lua table.

Every operation returns two values

local value1, value2 = client:operation()

The result depends on whether the operation succeeded or failed

  Success Failure
value1 Actual result nil
value2 HTTP status code error message

Indexing Documents

To index a document, you need to pass index, type, id and body as parameters:

local res, status = client:index{
  index = "my_index",
  type = "my_type",
  id = "my_id",
  body = {
    my_key = "my_value"
  }
}

On success, the response will be returned in res as a Lua table and the HTTP status code in status. Sample output:

{
  ["_index"] = "my_index",
  ["_type"] = "my_type",
  ["_id"] = "my_id",
  ["created"] = true,
  ["_version"] = 1.0,
  ["_shards"] = {
    ["successful"] = 1.0,
    ["failed"] = 0.0,
    ["total"] = 2.0,
  }
}

Getting Documents

To get a document, you need to pass index, type and id of the document as parameters:

local res, status = client:get{
  index = "my_index",
  type = "my_type",
  id = "my_id"
}

The following response is returned if the document can be retrieved:

{
  ["_index"] = "my_index",
  ["_type"] = "my_type",
  ["_id"] = "my_id",
  ["found"] = true,
  ["_version"] = 1.0,
  ["_source"] = {
    ["my_key"] = "my_value"
  }
}

Otherwise, if the document is not present or cannot be retrieved, nil and an error string is returned.

Searching Documents

For searching documents, you can either perform a URI based search(by passing a q parameter) or a request body search(by passing the search DSL in body parameter). Searches can be restricted to ‘index’, ‘type’, or even both, by optionally passing index and type parameters. A sample request body search:

local res, status = client:search{
  index = "my_index",
  type = "my_type",
  body = {
    query = {
      match = {
        my_key = "my_value"
      }
    }
  }
}

The returned response consists of some metadata(took, timed_out, etc.) and a hits table. hits.total contains the total number of matches. hits.hits is a lua array, each entry represents one matching document.

{
  ["took"] = 3.0,
  ["timed_out"] = false,
  ["_shards"] = {
    ["failed"] = 0.0,
    ["total"] = 5.0,
    ["successful"] = 5.0
  },
  ["hits"] = {
    ["total"] = 1.0,
    ["max_score"] = 7.7399282,
    ["hits"] = {
      ["1"] = {
        ["_index"] = "my_index",
        ["_type"] = "my_type",
        ["_id"] = "my_id",
        ["_score"] = 7.7399282,
        ["_source"] = {
          ["my_key"] = "my_param"
        }
      }
    }
  }
}

Deleting Documents

To delete a document, you need to pass index, type, id and body as parameters:

local res, status = client:delete{
  index = "my_index",
  type = "my_type",
  id = "my_id"
}

On deletion, the following response is returned back:

{
  ["_index"] = "my_index",
  ["_type"] = "my_type",
  ["_id"] = "my_id",
  ["found"] = true,
  ["_version"] = 2.0,
  ["_shards"] = {
    ["failed"] = 0.0,
    ["total"] = 2.0,
    ["successful"] = 1.0,
  }
}

Wrap up

This was just a brief overview of using elasticsearch-lua. The client functions, the body parameter and the response returned bears resemblance with the Elasticsearch REST API.

Read the rest of the documentation to know more about the client.