Node Client

Instantiating a node based client is the simplest way to get a Client that can execute operations against elasticsearch.

import static org.elasticsearch.node.NodeBuilder.*;

// on startup

Node node = nodeBuilder().node();
Client client = node.client();

// on shutdown

node.close();

When you start a Node, it joins an elasticsearch cluster. You can have different clusters by simply setting the cluster.name setting, or explicitly using the clusterName method on the builder.

You can define cluster.name in the /src/main/resources/elasticsearch.yml file in your project. As long as elasticsearch.yml is present in the classpath, it will be used when you start your node.

cluster.name: yourclustername

Or in Java:

Node node = nodeBuilder().clusterName("yourclustername").node();
Client client = node.client();

The benefit of using the Client is the fact that operations are automatically routed to the node(s) the operations need to be executed on, without performing a "double hop". For example, the index operation will automatically be executed on the shard that it will end up existing at.

When you start a Node, the most important decision is whether it should hold data or not. In other words, should indices and shards be allocated to it. Many times we would like to have the clients just be clients, without shards being allocated to them. This is simple to configure by setting either node.data setting to false or node.client to true (the NodeBuilder respective helper methods on it):

import static org.elasticsearch.node.NodeBuilder.*;

// on startup

// Embedded node clients behave just like standalone nodes,
// which means that they will leave the HTTP port open!
Node node =
    nodeBuilder()
        .settings(Settings.settingsBuilder().put("http.enabled", false))
        .client(true)
    .node();

Client client = node.client();

// on shutdown

node.close();

Another common usage is to start the Node and use the Client in unit/integration tests. In such a case, we would like to start a "local" Node (with a "local" discovery and transport). Again, this is just a matter of a simple setting when starting the Node. Note, "local" here means local on the JVM (well, actually class loader) level, meaning that two local servers started within the same JVM will discover themselves and form a cluster.

import static org.elasticsearch.node.NodeBuilder.*;

// on startup

Node node = nodeBuilder().local(true).node();
Client client = node.client();

// on shutdown

node.close();

Node Client Downsides

Embedding a node client into your application is the easiest way to connect to an Elasticsearch cluster, but it carries some downsides.

  • Frequently starting and stopping one or more node clients creates unnecessary noise across the cluster.
  • Embedded node client will respond to outside requests, just like any other client.

    • You almost always want to disable HTTP for an embedded node client.