Managing Indices
Learn how to create, update and delete indices with CBElasticsearch
Elasticsearch documents are stored in an "index", with the document structure defined by a "mapping". An Elasticsearch index is a JSON document store, and the mapping is a JSON configuration which defines the data type Elasticsearch should use for each document field.
By default, Elasticsearch will dynamically generate these index mapping when a document is saved to the index. See Dynamic Mappings in Elasticsearch for more details.

Retrieving information on Indices

To retrieve a list of all indices on the connected cluster, use the client getIndices method:
var indexMap = getInstance( "[email protected]" ).getIndices();
This will return a struct of all indices ( with the names as keys ), which will provide additional information on each index, such as:
  • Any assigned aliases
  • The number of documents in the index
  • The size of the storage space used for the index in bytes

Creating an Index

The IndexBuilder model assists with the creation and mapping of indices. Mappings define the allowable data types within your documents and allow for better and more accurate search aggregations. Let's say we have a book model that we intend to make searchable via a bookshop index. Let's go ahead and create the index using the IndexBuilder:
var indexBuilder = getInstance( "[email protected]" ).new( "bookshop" ).save();
This will create an empty index which we can begin populating with documents.

Creating an Explicit Index Mapping

To avoid the inherent troubles with dynamic mappings, you can define an explicit mapping using the properties argument:
getInstance( "[email protected]" )
.new(
name = "bookshop",
properties = {
"title" : { "type" : "text" },
"summary" : { "type" : "text" },
"description" : { "type" : "text" },
// denotes a nested struct with additional keys
"author" : { "type" : "object" },
// date with specific format type
"publishDate" : {
"type" : "date",
// our format will be = yyyy-mm-dd
"format" = "strict_date"
},
"edition" : { "type" : "integer" },
"ISBN" : { "type" : "integer" }
}
)
.save();
While it is not required that you explicitly define an index mapping, it is highly recommended since Elasticsearch's assumptions about the incoming document data may not always be correct. This leads to issues where the Elasticsearch-generated mapping is wrong and prevents further data from being indexed if it does not match the expected data type.

Using Client.ApplyIndex

In the previous examples, we've created the index and mapping from the IndexBuilder itself. If we wish, we could instead pass the IndexBuilder object to the [email protected] instance's applyIndex( required IndexBuilder indexBuilder ) method:
var myNewIndex = indexBuilder.new( "bookshop" )
.populate( getInstance( "[email protected]" ).getConfig() );
getInstance( "[email protected]" ).applyIndex( myNewIndex );

Configuring Index Settings

So far we've passed a simple struct of field mappings in to the index properties. If we wanted to add additional settings or configure replicas and shards, we could pass a more comprehensive struct, including a range of settings to the new() method to do so:
indexBuilder.new(
"bookshop",
{
"settings" : {
"number_of_shards" : 10,
"number_of_replicas" : 2,
"auto_expand_replicas" : true,
"shard.check_on_startup" : "checksum"
},
"mappings" : {
"properties" : {
"title" : { "type" : "text" },
"summary" : { "type" : "text" },
"description" : { "type" : "text" },
// denotes a nested struct with additional keys
"author" : { "type" : "object" },
// date with specific format type
"publishDate" : {
"type" : "date",
// our format will be = yyyy-mm-dd
"format" : "strict_date"
},
"edition" : { "type" : "integer" },
"ISBN" : { "type" : "integer" }
}
}
}
);

Updating an Existing Index

The IndexBuilder model also provides a patch() convenience method for updating the mapping or settings on an index:
indexBuilder.patch(
"bookshop",
settings = {
"number_of_shards" : 10,
"number_of_replicas" : 2,
"auto_expand_replicas" : true,
"shard.check_on_startup": "checksum"
}
);
Here's a quick example of using indexBuilder.patch() to add two new fields to an existing reviews index:
indexBuilder.patch(
"reviews",
properties = {
"authorName" : { "type" : "text" },
"helpfulRating": { "type" : "integer" }
}
);

Deleting an Index

All good things must come to an end, eh? You can use Client.deleteIndex() to delete an existing index:
getInstance( "[email protected]" ).deleteIndex( "reviews" )
Or you can use IndexBuilder.delete():
IndexBuilder.new( "reviews" ).delete();

Additional Reading

Deprecation notice: Custom index types are deprecated since Elasticsearch v7.0, and should no longer be used. Only a single type will be accepted in future releases.
Copy link
Edit on GitHub
Outline
Retrieving information on Indices
Creating an Index
Creating an Explicit Index Mapping
Using Client.ApplyIndex
Configuring Index Settings
Updating an Existing Index
Deleting an Index
Additional Reading