Mapping an Index in Elasticsearch using NodeJS

Introduction

If you’re storing documents in an Elasticsearch index, you’ll probably want to create a mapping for the index. Mapping an index allows you to define how the fields in a documents are stored and handled in Elasticsearch: which fields contain numbers, which fields should be handled as full-text fields, how dates should be formatted, and much more. While that may sound like a daunting task, the process is actually quite simple. In this tutorial, we’ll show you an example of mapping an index in Node.js.

Prerequisites

Before we attempt to map an index using Node.js, it’s important to make sure certain prerequisites are in place. There are a few key system requirements:

  • First, ensure that Elasticsearch is installed and running on your server.

  • You’ll also need to make sure npm, the Node Package Manager, is installed before you attempt to install any Node modules. Running the command npm install elasticsearch without having npm installed will return the below warning:

Command `npm` not found, but can be installed with:

apt install npm
  • Make sure that the latest version of Node.js is installed,

Warning: Currently, the only release you’ll find on npm is a beta release that works with Elasticsearch 7. Once the final version of this library is released, support will be added for Elasticsearch 5 and 6 as well.

If you’re not sure if npm or Node.js are installed, a bit of testing can help you figure it out:

>1. Test Node.js. To validate installation of Node.js type node -v in terminal. Version number should be returned, which will look something like this:

v0.10.35.

>2. Test NPM. To validate NPM is installed, type npm -v in terminal. The command returns the version number, so you’ll see the following in response:

2.1.17
  • It’s helpful to have a fair knowledge of Node.js if you’re planning to perform Elasticsearch-related tasks in this environment.

Connecting to Elasticsearch

The first step in our example of mapping an index in Node.js is to connect to Elasticsearch. The code shown below will create an instance of elasticsearch and assign it to var elasticsearch. ___

var elasticsearch = require('elasticsearch');

The next chunk of code we’ll look at creates a credential directly in the host URL. Note that the Client constructor accepts a single object as its argument. You can find a listing of all of the available options/keys in the Config options section of Elasticsearch’s documentation:

var client = new elasticsearch.Client({
hosts: [ 'https://username:password@host:port']
});

module.exports = client;
  • Copy the above code and save it as connection.js. For your own use, you’ll need to replace the username, password, server and port shown in this example with the real values from your Elasticsearch deployment.
  • To confirm that everything is working, you can ping your Elasticsearch cluster using the code shown below:
client.ping({
requestTimeout: 30000
}, function(error) {
if (error) {
console.error('Error Encountered! Elasticsearch cluster is down');
console.trace('Error:', error);

} else {
console.log('Connected!');
}
// on finish
client.close();
});

>If something didn’t work correctly, you can debug the problem using the error object returned by the callback.

Mapping an Index

At this point, we’re ready to try mapping an index in Node.js. As we discussed earlier, mapping refers to the structure of data in Elasticsearch. If you don’t provide a mapping for an index, Elasticsearch dynamically creates one. When a document is indexed, Elasticsearch examines each field of the JSON data and defines that mapping based on its type. This dynamic mapping can lead to problems if data types aren’t detected correctly by Elasticsearch; for better control over the way your data is treated and indexed, it’s helpful to specify a mapping.

>For instance, if the key/value pair{"key1": 12} is already indexed, Elasticsearch automatically maps the field key1 as long. This means that all future values of key1 that get indexed will be expected to be of type long. If you try to index {"key1": "value1", "key2": "value2"}, you’ll get an error. However, the object {"key1": 13, "key2": "value2"} would be indexed successfully because the value 13 is of type long. When this object is indexed, the field key2 of type string will be added to the mapping.

  • The code shown below will create a mapping for the index myindex:
var client = require('./connection.js');

client.indices.putMapping({
index: 'myindex',
type: 'mytype',
body: {
properties: {
'propertyname': {
'type': 'string'
},
}
}
},function(err,resp,status){
if (err) {
console.log(err);
}
else {
console.log(resp);
}
});

There’s a lot going on in this code, so let’s take a closer look to better understand what’s taking place in each part.

The require method

var client = require('./connection.js');

You can now utilize the client var whenever you want to perform an operation by including the line shown above in any other file you will create. Remember that the field connection.js contains the connection settings we created earlier in Connecting to Elasticsearch

The API

The Elasticsearch.js API makes use of the code shown below to register a specific mapping definition for a specific type:

client.indices.putMapping([params, [callback]])

We’ll use the putMapping() function in the following code, supplying the parameters needed to set up our mapping:

The params

client.indices.putMapping({
index: 'myindex',
type: 'mytype',
body: {
properties: {
'propertyname': {
'type': 'string'
},
}
}

The Callback

Including the following callback code allows us to catch and debug potential errors:

},function(err,resp,status){
if (err) {
console.log(err);
}
else {
console.log(resp);
}
});

Conclusion

Specifying a mapping for an Elasticsearch index allows you to have tighter control over the way your data is handled. You can define data types for fields, specify which fields should be treated as full searchable text, and much more. With the step-by-step instructions provided in this tutorial, you’ll have no trouble mapping an index in Node.js.

Pilot the ObjectRocket Platform Free!

Try Fully-Managed CockroachDB, Elasticsearch, MongoDB, PostgreSQL (Beta) or Redis.

Get Started

Keep in the know!

Subscribe to our emails and we’ll let you know what’s going on at ObjectRocket. We hate spam and make it easy to unsubscribe.