Motivation

Elasticsearch is one of the candidates to provide search and auto-completion features to web and mobile applications. I’ve delivered Elasticsearch in production for many years in various services. However, I’m stupid enough to forget its technical jargon and essential concepts, configurations, and operations. It’s a waste of time to investigate the Elastic official documents again and again because the page I looked for was always the same. Thus, I will leave the important information to deliver Elasticsearch in production from my experiences.

Related article

This article is one of the articles to dump my head for deliveries of Elasticsearch in production. The articles are divided into the following parts.

  • Understand important concept and terminology in Elasticsearch world (this article)
  • Elaborate the Elasticsearch configurations for scalability and high availability (part2)
  • Summarize basic Elasticsearch operations to deliver the clusters in production (part3)

Goal

  • Understand important concepts and terminologies for Elasticsearch world

Disclaimer

I’ve been delivering Elasticsearch 5.5 for my company and this note is composed through my experiences to run the version in production. There should be minor changes if you use different version of Elasticsearch.

Fundamentals of Elasticsearch

This section refers Terminology | Elastic Glossary | Elastic.

Basic Terminology

Elasticsearch provides distributed search engine by delivering its cluster. The cluster is built upon various physical and logical boundaries and they are described as follows:

Cluster

One or more nodes that share the same cluster name. Each cluster has a single master node, which is chosen automatically by the cluster and can be replaced if it fails.

Node

A running instance of Elasticsearch that belongs to a cluster. Multiple nodes can be started on a single server for testing purposes, but usually you should have one node per server.

Index

An index is like a database in a relational database and an optimized collection of JSON documents. Each document is a collection of fields, the key-value pairs that contain your data.

An index is a logical namespace that maps to one or more primary shards and can have zero or more replica shards.

Shard

An index is a logical namespace which points to primary and replica shards. Other than defining the number of primary and replica shards that an index should have, you never need to refer to shards directly. Instead, your code should deal only with an index.

Elasticsearch distributes shards amongst all nodes in the cluster, and can move shards automatically from one node to another in the case of node failure, or the addition of new nodes.

Type

A type used to represent the type of document, e.g. an email, a user, or a tweet. Types are deprecated and are in the process of being removed. See Removal of mapping types.

Document

A document is a JSON document which is stored in Elasticsearch. It is like a row in a table in a relational database. Each document is stored in an index and has a type and an id.

A document is a JSON object (also known in other languages as a hash / hashmap / associative array) which contains zero or more fields, or key-value pairs.

Field

A document contains a list of fields, or key-value pairs. The value can be a simple (scalar) value (e.g a string, integer, date), or a nested structure like an array or an object. A field is similar to a column in a table in a relational database.

The mapping for each field has a field type (not to be confused with document type) which indicates the type of data that can be stored in that field, e.g integer, string, object. The mapping also allows you to define (amongst other things) how the value for a field should be analyzed.

Mapping

A mapping is like a schema definition in a relational database. Each index has a mapping, which defines a type, plus a number of index-wide settings.

A mapping can either be defined explicitly, or it will be generated automatically when a document is indexed.

Primary & Replica

Primary shard

Each document is stored in a single primary shard. When you index a document, it is indexed first on the primary shard, then on all replicas of the primary shard.

By default, an index has one primary shard. You can specify more primary shards to scale the number of documents that your index can handle.

You cannot change the number of primary shards in an index, once the index is created. However, an index can be split into a new index using the split index API.(Refer from the official doc)

Replica (shard)

Each primary shard can have zero or more replicas. If people say “replica”, it means the replica shards. A replica is a copy of the primary shard, and has two purposes:

  1. Increase failover: a replica shard can be promoted to a primary shard if the primary fails
  2. Increase performance: get and search requests can be handled by primary or replica shards.

By default, each primary shard has one replica, but the number of replicas can be changed dynamically on an existing index. A replica shard will never be started on the same node as its primary shard.

Role of node

See details: Node | Elasticsearch Reference [5.5] | Elastic

I’ve been using Master eligible node, Data node, and Coordinating node only. But I will describe all node types for Elasticsearch 5.5 here. By default a node is a master-eligible node and a data node, plus it can pre-process documents through ingest pipelines. This is very convenient for small clusters but, as the cluster grows, it becomes important to consider separating dedicated master-eligible nodes from dedicated data nodes.

Master / Master eligible node

A node that has node.master set to true (default), which makes it eligible to be elected as the master node, which controls the cluster.

Data node

A node that has node.data set to true (default). Data nodes hold data and perform data related operations such as CRUD, search, and aggregations.

Ingest node

A node that has node.ingest set to true (default). Ingest nodes are able to apply an ingest pipeline to a document in order to transform and enrich the document before indexing. With a heavy ingest load, it makes sense to use dedicated ingest nodes and to mark the master and data nodes as node.ingest: false.

Coordinating node

Requests like search requests or bulk-indexing requests may involve data held on different data nodes. A search request, for example, is executed in two phases which are coordinated by the node which receives the client request — the coordinating node.

In the scatter phase, the coordinating node forwards the request to the data nodes which hold the data. Each data node executes the request locally and returns its results to the coordinating node. In the gather phase, the coordinating node reduces each data node’s results into a single global resultset.

Every node is implicitly a coordinating node. This means that a node that has all three node.master, node.data and node.ingest set to false will only act as a coordinating node

Recovery, Replica allocation, and Rebalancing

Recovery

Shard recovery is the process of syncing a replica shard from a primary shard. Upon completion, the replica shard is available for search. Recovery automatically occurs during the following processes:

  • Node startup or failure. This type of recovery is called a local store recovery.
  • Primary shard replication.
  • Relocation of a shard to a different node in the same cluster.
  • Snapshot restoration.

Replica allocation

Shard allocation is about taking unassigned shard copies and finding each of them a node to inhabit.

Rebalancing

Rebalancing is about taking assigned shard copies and moving them to different nodes to even out the distribution of shards.