☰

Elasticsearch Index Configuration:

Elasticsearch Index Configuration: Mappings and Settings

Create an index in Elasticsearch, send it a few documents, and it just works. That is by design. Elasticsearch looks at your data and decides for itself how to store each field. But the choices it makes are not always the ones you want. A phone number can end up as text, a price can end up as a decimal that you cannot sort the way you expect, and a name field can be split in ways that break your exact match.

Index configuration is how you take control. It has two parts. Mappings describe the fields and how each one is stored and searched. Settings control how the index itself behaves, such as how many shards it has, how many copies it keeps, and which analyzers are available.

In this guide, we go through both parts, using the bank account example from the original page. We fix the two examples so that they work, and explain what each line does. We also cover what the page left out: dynamic against explicit mapping, which settings you can change later and which you cannot, how to change a mapping that is already in use, and the mistakes that cause errors.

What is Index Configuration in Elasticsearch?

When you create an index, Elasticsearch fills in a default configuration for you. You can supply your own to describe your data better. The old page said that you can define two configurations for an index. They are:

Index configuration at a glance
Configuration What it controls
Mappings The fields of your documents, the data type of each field, and how each field is indexed. It is the schema of the index
Settings How the index behaves: shards, replicas, refresh time, limits and analyzers

Both can go into one create index request, as we show below.

Mappings

A mapping defines how a document and its fields are stored and indexed. The Elastic docs say that each field has a data type, and that the mapping also holds metadata fields. The old page said that you use mappings to define, and then the list was missing. Here is the list that belongs there.

  • Which fields exist. The names of the fields in your documents.
  • The type of each field. Text, number, date and so on.
  • How a field is searched. For example, which analyzer splits a text field into words.
  • How the metadata fields behave. For example, whether the original JSON is kept.

Dynamic Mapping and Explicit Mapping

There are two ways to get a mapping. The Elastic docs describe both.

Dynamic mapping compared with explicit mapping
Aspect Dynamic mapping Explicit mapping
Who decides Elasticsearch detects the type from the first value it sees You define each field
Good for Quick tests, and data you do not know yet Anything real, and types that cannot be detected, such as geo_point and custom date formats
Risk A wrong guess, or too many fields (mapping explosion) More work at the start

Here is dynamic mapping at work. If the index has no field called city, and you add a document that has one, Elasticsearch adds the field for you:

kibana dev tools
POST bank_account_details/_doc
{
  "name": "Asha Rao",
  "date": "2026-10-01",
  "balance": 25000.5,
  "liability": 1200,
  "city": "Kolkata"
}

That is handy, but it can go wrong. If a field keeps getting new names, such as one new field for each user, the mapping grows without end. The Elastic docs call this mapping explosion. They warn that too many fields can cause out of memory errors that are hard to recover from, and say to use the mapping limit settings to cap the number of fields. I could not confirm the default limit from the page I checked, so look at the mapping limit settings page for your version.

To stop new fields from appearing at all, set dynamic to strict. A document with an unknown field is then refused:

kibana dev tools
PUT bank_account_details_strict
{
  "mappings": {
    "dynamic": "strict",
    "properties": {
      "name": {
        "type": "text"
      }
    }
  }
}

Mapping Types: What the Old Page Got Wrong

The old page had a section called Mapping types, with two items, meta fields and fields. But those are two parts of a mapping, and not types. In older Elasticsearch, an index could have several mapping types, such as one for users and one for orders. That idea was removed. The Elastic docs say that mapping types were removed in 7.0.0. Today an index has one mapping, with metadata fields and your own fields.

Meta Fields

Meta fields are fields that Elasticsearch adds to every document, to handle its metadata. Their names start with an underscore. These are the ones you will see most:

Common meta fields
Meta field What it holds
_index The name of the index that holds the document
_id The ID of the document
_source The original JSON that you sent. The Elastic docs name this one in the mapping page
_routing A value that decides which shard the document goes to
_meta A place for your own notes about the mapping

The old page also listed _type. For a current version, remove it, as explained above. The mapping page I checked names only _source as a meta field, so please check the meta fields page for your version before you add more to this table.

Fields or Properties

The fields of your documents go in a block called properties. Each field has a name, and a type, and sometimes more options. This is the first example from the old page. It maps four fields of a bank account record.

The old version failed for four reasons. The quotes were curly, the comma was missing after the text type, the opening quote on standard was the wrong mark, and the index name had capital letters. Elasticsearch needs lower case index names, so I changed BankAccountDetails to bank_account_details. Here is the fixed request:

kibana dev tools
PUT bank_account_details
{
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "standard"
      },
      "date": {
        "type": "date"
      },
      "balance": {
        "type": "double"
      },
      "liability": {
        "type": "double"
      }
    }
  }
}

If you send the old name, Elasticsearch refuses it, because index names must be lower case:

kibana dev tools
PUT BankAccountDetails

I did not run this, so I have not copied the exact error text. Check it on your own cluster.

What Each Line Means

  • name is a text field, which is split into words so that you can search part of a name. The standard analyzer is the default, so naming it is optional.
  • date is a date field. If you send no format, it accepts common date formats such as 2026-10-01.
  • balance and liability are double fields, which hold decimal numbers.

A note for money. A double can show small rounding differences. Elasticsearch has a scaled_float type that stores a decimal as a whole number with a scaling factor, and it may suit amounts better. Check the field data types page for your version before you choose.

Field Datatypes

Every field needs a data type. The old page listed text, keyword, date and geo_point, and said that string fields can use analyzers. That last point needs a correction. Only the text type is analysed. The keyword type stores the whole value as one exact term, and is used for filters, sorting and grouping.

Field data types and when to use them
Type Use it for Example value
text Full text search, in words A description or a name
keyword Exact values, filters, sorting and aggregations A status, a city, an email
integer, long, double Numbers 25000.5
boolean True or false true
date Dates and times 2026-10-01
geo_point A latitude and longitude, for map searches A shop location
object, nested A field that holds other fields An address with street and city

Text or Keyword? Use Both

Many fields need both. You may want to search part of a name, and also match it exactly or sort by it. A multi field does this. It gives one field two ways of being indexed. The Elastic docs say that you can add multi fields to an existing field, but older documents will not have values for them until they are updated or reindexed.

kibana dev tools
PUT bank_account_details_v2
{
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "fields": {
          "keyword": {
            "type": "keyword"
          }
        }
      }
    }
  }
}

Now you search name for words, and name.keyword for the exact value. This is the same pattern we used in the aggregations and query DSL guides.

Settings

Settings control the index itself. The old page said they set shards, replicas and custom analyzers. Here are the ones to know, with the defaults from the Elastic 8.18 docs. The docs say that this version is no longer updated, so check the latest docs for your version.

Common index settings with their defaults
Setting Kind Default What it does
index.number_of_shards Static 1 How many primary shards. Fixed when the index is created
index.number_of_replicas Dynamic 1 How many copies of each shard. Setting 0 risks downtime or data loss
index.refresh_interval Dynamic 1s How often new documents become searchable. Set to minus 1 to switch off
index.max_result_window Dynamic 10000 The largest value of from plus size in a search
index.codec Static default best_compression saves disk, but makes some reads slower
index.hidden Dynamic false Hides the index from wildcard searches

Static and Dynamic Settings

This is the key idea, and the old page did not mention it. The Elastic docs say that static settings can only be set when the index is created, or on a closed index. Dynamic settings can be changed on a live index. Dynamic changes use the update settings API:

kibana dev tools
PUT bank_account_details/_settings
{
  "index": {
    "number_of_replicas": 1,
    "refresh_interval": "30s"
  }
}

Here the number of copies goes to 1, and new documents become searchable every 30 seconds instead of every second. A longer refresh time can help when you load a lot of data, but it means that new documents show up in search later.

The Second Example, Fixed

The old page sent this request to an existing index:

kibana dev tools
PUT bank_account_details/_settings
{
  "index": {
    "number_of_shards": 3,
    "number_of_replicas": 2,
    "analysis": {
      "analyzer": {
        "content": {
          "type": "custom",
          "tokenizer": "whitespace"
        }
      }
    }
  }
}

It has three problems.

  • The shard count cannot change. index.number_of_shards is static. The docs say it can be set at creation only, and that it cannot be changed on a closed index. To get 3 shards, you have to create a new index, and reindex into it.
  • The analyzer is defined, and never used. The analyzer called content does nothing until a field uses it.
  • Replicas need nodes. With 2 replicas, each shard has 3 copies, and no two copies of the same shard may live on the same node. You need at least 3 nodes for the index to be green. On a one node cluster, the primary shards work, but the copies cannot be placed, and the index shows yellow.

The simplest fix is to put the settings in the create request. Here is the whole index in one request, with the settings and the mapping together. I used 1 shard and 0 replicas, which suits a single node test cluster. Do not use 0 replicas for data that you cannot lose.

kibana dev tools
PUT bank_account_details
{
  "settings": {
    "index": {
      "number_of_shards": 1,
      "number_of_replicas": 0,
      "analysis": {
        "analyzer": {
          "content": {
            "type": "custom",
            "tokenizer": "whitespace"
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "name": {
        "type": "text",
        "analyzer": "standard",
        "fields": {
          "keyword": {
            "type": "keyword"
          }
        }
      },
      "date": {
        "type": "date"
      },
      "balance": {
        "type": "double"
      },
      "liability": {
        "type": "double"
      },
      "notes": {
        "type": "text",
        "analyzer": "content"
      }
    }
  }
}

The notes field now uses the content analyzer, so the analyzer is no longer unused. This analyzer is custom. It uses the whitespace tokenizer, which splits the text only at spaces.

What the Custom Analyzer Does

To see the difference, compare it with the standard analyzer. For the text Opening Balance: Paid, the expected tokens are:

Tokens produced by two analyzers
Analyzer Tokens
standard opening, balance, paid
content (whitespace) Opening, Balance:, Paid

The standard analyzer lower cases the words and drops the punctuation. The whitespace tokenizer keeps the capital letters and the colon, because it only cuts at spaces. This is the expected result from how the two work. I have not run it. You can test it with the analyze API on your own index:

kibana dev tools
GET bank_account_details/_analyze
{
  "analyzer": "content",
  "text": "Opening balance: Rs.25,000 paid"
}

If you want the content analyzer to ignore case, add a lowercase filter to it. For most text fields, the standard analyzer is the better choice.

Changing an Analyzer on an Existing Index

The safe way is to close the index, change the setting, and open it again. A closed index does not answer searches while it is closed, so plan for that. The Elastic docs say that you can change any documented setting on a closed index, but changing a setting that is not documented is not supported.

kibana dev tools
POST bank_account_details/_close
PUT bank_account_details/_settings
{
  "analysis": {
    "analyzer": {
      "content": {
        "type": "custom",
        "tokenizer": "whitespace"
      }
    }
  }
}
POST bank_account_details/_open

Analysis settings follow special rules, and an analyzer change does not rewrite the words that are already indexed. Documents that were indexed before the change keep their old tokens, so you usually need to reindex them. Check the docs for your version before you try this on a live index.

How to See What You Have?

Two requests show the current mapping and settings. Use them before and after any change.

kibana dev tools
GET bank_account_details/_mapping
GET bank_account_details/_settings

Add a Field to an Existing Mapping

The Elastic docs say that you can add new fields at any time, either explicitly or dynamically. Use the update mapping API:

kibana dev tools
PUT bank_account_details/_mapping
{
  "properties": {
    "branch": {
      "type": "keyword"
    }
  }
}

Change the Type of an Existing Field

This is where most beginners get stuck. The Elastic docs say that in most cases you cannot change the mapping of a field that is already mapped, because the change needs the data to be indexed again. The way out is to create a new index with the right mapping, and copy the data with the reindex API:

Step 1: Create the New Index

Create a new index, such as bank_account_details_v2, with the mapping that you want.

Step 2: Copy the Data

kibana dev tools
POST _reindex
{
  "source": {
    "index": "bank_account_details"
  },
  "dest": {
    "index": "bank_account_details_v2"
  }
}

Step 3: Switch Over With an Alias

If your application uses an alias, and not the index name, you can switch without any change to the code. Create the alias first, and point it at the old index:

kibana dev tools
POST _aliases
{
  "actions": [
    {
      "add": {
        "index": "bank_account_details",
        "alias": "bank_accounts"
      }
    }
  ]
}

When the new index is ready, move the alias in one request. The remove and the add happen together, so searches never see a gap:

kibana dev tools
POST _aliases
{
  "actions": [
    {
      "remove": {
        "index": "bank_account_details",
        "alias": "bank_accounts"
      }
    },
    {
      "add": {
        "index": "bank_account_details_v2",
        "alias": "bank_accounts"
      }
    }
  ]
}

The Elastic docs do not give reindex steps on the mapping page, so treat this as a pattern, and check the reindex and alias documentation for your version. Always test on a copy first.

Index Configuration Mistakes and How to Fix Them

Common index configuration mistakes and fixes
Problem Usual cause Fix
The create request is refused The index name has capital letters Use lower case names, such as bank_account_details
The JSON is rejected Curly quotes, or a missing comma Use straight quotes, and check the commas
The shard count will not change number_of_shards is static Create a new index and reindex
The index is yellow Replicas have no node to go to Add nodes, or set replicas to 0 on a test cluster
A field has the wrong type Dynamic mapping guessed it Define the mapping first, or reindex
A new field appears that you did not expect Dynamic mapping is on Set dynamic to strict
Exact match finds nothing on a name The field is text, and not keyword Use a keyword field or a keyword multi field
A custom analyzer has no effect No field uses it Set the analyzer on the field

Practice Exercises

  1. Create the bank_account_details index with the full request on this page, and read it back with the mapping and settings requests.
  2. Add a document with an extra field called city, and look at the mapping again to see the field that dynamic mapping made.
  3. Create a second index with dynamic set to strict, and try to add a document with an unknown field.
  4. Change the refresh interval to 30 seconds, and then back to 1 second.
  5. Create a v2 index with a different type for one field, reindex into it, and move an alias to it.

A little time spent on the mapping saves a lot of work later, because the type of a field is the one thing that is hard to change once you have data. Define your mapping before you load real data, keep dynamic mapping under control, and choose shards with care. A good next step is to take one of your own indexes, read its mapping with the request above, and check every field type against what you really meant.

Popular Tags: