Elasticsearch is an analytics and full-text search engine that is often used for enabling search functionality for applications. Besides providing functionality and flexibility in regards to searching data, Elasticsearch is also highly scalable. IBM Cloud Databases for Elasticsearch makes Elasticsearch even better by managing it the service for you as an offering on IBM Cloud. This includes offering an easy, auto-scaling deployment system which delivers high availability and redundancy, automated no-stop backups, and much more.

Learning objectives

This tutorial demonstrates how to perform Create, Read, Update and Delete (CRUD) operations with IBM Cloud Databases for Elasticsearch by using Postman. Moreover you will learn these operations, which is the base of Elasticsearch, and not have to manage an Elasticsearch of your own.

Prerequisites

  • Download Postman. Postman is a useful tool when trying to dissect RESTful APIs made by others or test ones you have made yourself. It offers a sleek user interface with which to make HTML requests, without the hassle of writing a bunch of code just to test an API’s functionality.

  • A billable account for IBM Cloud. IBM Cloud Databases for Elasticsearch is not available for (free) Lite Accounts, so you are not able to follow this guide without a billable account.

Estimated time

  • Set up of the Postman is approximately 30 minutes.
  • Set up of Compose for Elasticsearch is approximately 8 minutes.
  • Sending all Requests is approximately 10 minutes.

Steps

Create an Elasticsearch service on IBM Cloud

Log into IBM Cloud. Click the Catalog button and find the Data & Analystics options in the menu. Then select Databases for Elasticsearch and create the service:

create_service

Find your Elasticsearch endpoint

After your service is created, you can find the URL of the public endpoint for your elasticsearch service from the Manage section of the cloud console for your instance. The endpoint can be found in the yellow rectangular area in the following image. You use this URL as yourlink throughout this tutorial.

find_endpoint

Notice that the URL contains the strings $USERNAME and $PASSWORD. You will find values for these in the next step.

Generate a service credential

Select the Service credential section of your instance and then click the New credential button. Select Add in the pop-up to create a new service credential. Once it is created, View credentials and then scroll down until you find the htts: authentication: section. This is where you find the user name and password to use in yourlink.

create_cred

Test a PUT operation

Now you are now ready to send your first request to the Elasticsearch cluster.

  1. Launch Postman.
  2. Select PUT from the request types.
  3. Paste yourlink + myindex. It should be something like this:

     https://xxxxxxxxxxxxxxxxxxxx:ibm_cloud_xxxxxx_xxxx_xxxxxx@c9664f56-0f22-4885-a916-2c6fd2899300.0135ec03d5bf43b196433793c98e8bd5.databases.appdomain.cloud:30855/myindex
    
  4. Send your request by clicking Send.

  5. The following results are displayed.

put_index

Add a document with a POST request

Now that you have an index, add some some documents to it. You do this by sending a POST request to a URI consisting of index name, followed by a type. In this tutorial our index name is myindex and type name is default, which combine to make the request URI myindex/default.

  1. Select POST from the request types and add yourlink + /myindex/default.
  2. Select Body and choose the raw option to write your document. Be sure the dropdown to the right of the raw option says JSON (application/json)
  3. Write a JSON document to add to the index as shown below:

     {
       "name": "Musa Berat Bahadir",
       "contents": {
         "topic": "Databases for Elasticsearch",
         "details": "CRUD operations"
       }
     }
    

    add_doc

  4. Now send the request and the following result is shown:

add_doc_res

Note: Because no ID was specified, Elasticsearch will generate a random ID.

Add a document with a PUT request

To specify an ID for Elasticsearch we need to specify an ID in the URL.

  1. Change the HTTP verb to PUT and specify the ID by adding a number to the end of yourlink + /myindex/defautlt. In the example below, we’re using an ID of 1 by adding /myindex/default/1
  2. Select Body and choose the raw option to write your document. Be sure the dropdown to the right of the raw option says JSON (application/json)
  3. Write a JSON document to add to the index, as shown below:

     {
       "name": "Musa Berat Bahadir 2",
       "contents": {
         "topic": "Databases for Elasticsearch",
         "details": "CRUD operations"
       }
     }
    

    add_doc_id

  4. Now send the request and the response will be shown below the request.

add_doc_id

Retrieve a document with a GET request

Now we have a couple of documents available within our index. For retrieving a document with a specific ID from our index:

  1. Select GET from the request types and add yourlink + /myindex/default/1 in the request URL area.
  2. Send the request by clicking the Send button.

get_doc

Update a document with a POST request

Instead of replacing the entire document, we can update only a specific portion of it.

  1. Select POST from the request types and add yourlink + /myindex/default/1/_update.
  2. Select Body and choose the raw option to add your document. Be sure the dropdown to the right of the raw option says JSON (application/json)

  3. The update API expects a JSON object and within this object you should add a doc property, which itself should be an object. For this tutorial, the document can been written as follows:

     {
       "doc": {
         "name": "Unidentified Flying Object",
         "tags": ["Elasticsearch", "IBM Cloud"]
       }
     }
    

    Note: Within this object we can specify the fields that you would like to change (name) or add new fields with this approach (tags).

  4. Send the request by clicking the Send button:

    updat_doc

  5. The response is shown below the request:

    update_doc_res

Delete a document with a DELETE request

  1. Select DELETE from the request types and add yourlink + /myindex/default/1.
  2. Send the request by clicking the Send button.

delete_doc

Summary

At the completion of this tutorial, you have created an index and learned a few simple CRUD operations for Elasticsearch without having to install and manage Elasticsearch locally. By using the Databases for Elasticsearch service on IBM Cloud, you are able to choose your Elasticsearch version and have greater security by checking incoming connections with certificate confirmation, IP whitelisting, and mandatory creation of users with passwords.

Thanks for reading!