elasticsearch-lua

A low level client for Elasticsearch written in Lua. This is a fork of the original repo by Dhaval Kapil, which he no longer maintains. This repo does not try to be all things to all people. It is tested against and supports Elasticsearch 7,x, 8,x and Amazon Opensearch 2.0 and Lua 5.1, 5.2, 5.3, 5.4 and LuaJIT.

In accordance with the official low level clients, the client accepts associative arrays in the form of lua tables as parameters.

Features:

1. One-to-one mapping with REST API and other language clients.
2. Proper load balancing across all nodes.
3. Pluggable and multiple connection, selection strategies and connection pool.
4. Console logging facility.
5. Almost every parameter is configurable.

Elasticsearch Version Matrix

Elasticsearch Version	elasticsearch-lua Branch
ES 7.0 - 8.x + OS 2.0	master

Lua Version Requirements

elasticsearch-lua works for lua >= 5.1 <= 5.4 version and luajit.

Setup

It can be installed using luarocks

  [sudo] luarocks install elasticsearch-lua

Documentation

The complete documetation is here.

Create elasticsearch client instance:

  local elasticsearch = require "elasticsearch"

  local client = elasticsearch.client{
    hosts = {
      { -- Ignoring any of the following hosts parameters is allowed.
        -- The default shall be set
        connectionstring = "", -- Ignore host, port and protocol and parse this string instead
        protocol = "http",
        host = "localhost",
        port = 9200,
        username = "elastic",
        password = "changeme",
        verify = "peer",
        cafile = ""
      }
    },
    -- Optional parameters
    params = {
      pingTimeout = 2
    }
  }

The verify and cafile params are only applicable if the protocol is https.

  -- Will connect to default host/port
  local client = elasticsearch.client()

Full list of params:

1. pingTimeout : The timeout of a connection for ping and sniff request. Default is 1.
2. selector : The type of selection strategy to be used. Default is RoundRobinSelector.
3. connectionPool : The type of connection pool to be used. Default is StaticConnectionPool.
4. connectionPoolSettings : The connection pool settings,
5. maxRetryCount : The maximum times to retry if a particular connection fails.
6. logLevel : The level of logging to be done. Default is warning.

Standard call

local param1, param2 = client:<func>()

param1: Stores the data returned or nil on error

param2: Stores the HTTP status code on success or the error message on failure

Getting info of elasticsearch server

local data, err = client:info()

Type mapping deprecation

Elasticsearch 7 and above have deprecated and removed type mappings. To that end, if the type parameter is supplied, it will be ignored.

Index a document

Everything is represented as a lua table.

local data, err = client:index{
  index = "my_index",
  id = "my_doc",
  body = {
    my_key = "my_param"
  }
}

Get a document

data, err = client:get{
  index = "my_index",
  id = "my_doc"
}

Delete a document

data, err = client:delete{
  index = "my_index",
  id = "my_doc"
}

Searching a document

You can search a document using either query string:

data, err = client:search{
  index = "my_index",
  q = "my_key:my_param"
}

Or either a request body:

data, err = client:search{
  index = "my_index",
  body = {
    query = {
      match = {
        my_key = "my_param"
      }
    }
  }
}

Update a document

data, err = client:update{
  index = "my_index",
  id = "my_doc",
  body = {
    doc = {
      my_key = "new_param"
    }
  }
}

Contribution

Feel free to file issues and submit pull requests – contributions are welcome. Please try to follow the code style used in the repository.

License

elasticsearch-lua is licensed under the MIT license.