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.
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:
| 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.
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.
There are two ways to get a mapping. The Elastic docs describe both.
| 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:
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:
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 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:
| 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.
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:
If you send the old name, Elasticsearch refuses it, because index names must be lower case:
I did not run this, so I have not copied the exact error text. Check it on your own cluster.
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.
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.
| 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 |
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.
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 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.
| 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 |
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:
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 old page sent this request to an existing index:
It has three problems.
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 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.
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.
To see the difference, compare it with the standard analyzer. For the text Opening Balance: Paid, the expected tokens are:
| 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:
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.
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.
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.
Two requests show the current mapping and settings. Use them before and after any change.
The Elastic docs say that you can add new fields at any time, either explicitly or dynamically. Use the update mapping API:
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:
Create a new index, such as bank_account_details_v2, with the mapping that you want.
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:
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:
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.
| 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 |
bank_account_details index with the full request on this page, and read it back with the mapping and settings requests.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.