Communicate with OpenSearch

You can communicate with OpenSearch using the REST API or one of the OpenSearch language clients. This page introduces the OpenSearch REST API. If you need to communicate with OpenSearch in your programming language, see the Clients section for a list of available clients.

OpenSearch REST API

You interact with OpenSearch clusters using the REST API, which offers a lot of flexibility. Through the REST API, you can change most OpenSearch settings, modify indexes, check cluster health, get statistics—almost everything. You can use clients like cURL or any programming language that can send HTTP requests.

You can send HTTP requests in your terminal or in the Dev Tools console in OpenSearch Dashboards.

Sending requests in a terminal

When sending cURL requests in a terminal, the request format varies depending on whether you’re using the Security plugin. As an example, consider a request to the Cluster Health API.

If you’re not using the Security plugin, send the following request:

  1. curl -X GET "http://localhost:9200/_cluster/health"

copy

If you’re using the Security plugin, provide the username and password in the request:

  1. curl -X GET "http://localhost:9200/_cluster/health" -ku admin:<custom-admin-password>

copy

The default username is admin, and the password is set in your docker-compose.yml file in the OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> setting.

OpenSearch generally returns responses in a flat JSON format by default. For a human-readable response body, provide the pretty query parameter:

  1. curl -X GET "http://localhost:9200/_cluster/health?pretty"

copy

For more information about pretty and other useful query parameters, see Common REST parameters.

For requests that contain a body, specify the Content-Type header and provide the request payload in the -d (data) option:

  1. curl -X GET "http://localhost:9200/students/_search?pretty" -H 'Content-Type: application/json' -d'
  2. {
  3.   "query": {
  4.     "match_all": {}
  5.   }
  6. }'

copy

Sending requests in Dev Tools

The Dev Tools console in OpenSearch Dashboards uses a simpler syntax to format REST requests as compared to the cURL command. To send requests in Dev Tools, use the following steps:

  1. Access OpenSearch Dashboards by opening http://localhost:5601/ in a web browser on the same host that is running your OpenSearch cluster. The default username is admin, and the password is set in your docker-compose.yml file in the OPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password> setting.
  2. On the top menu bar, go to Management > Dev Tools.

  3. In the left pane of the console, enter the following request:

    1.  GET _cluster/health

    copy

  4. Choose the triangle icon on the upper right of the request to submit the query. You can also submit the request by pressing Ctrl+Enter (or Cmd+Enter for Mac users). To learn more about using the OpenSearch Dashboards console for submitting queries, see Running queries in the console.

In the following sections, and in most of the OpenSearch documentation, requests are presented in the Dev Tools console format.

Indexing documents

To add a JSON document to an OpenSearch index (that is, to index a document), you send an HTTP request with the following header:

  1. PUT https://<host>:<port>/<index-name>/_doc/<document-id>

For example, to index a document representing a student, you can send the following request:

  1. PUT /students/_doc/1
  2. {
  3.   "name": "John Doe",
  4.   "gpa": 3.89,
  5.   "grad_year": 2022
  6. }

copy

Once you send the preceding request, OpenSearch creates an index called students and stores the ingested document in the index. If you don’t provide an ID for your document, OpenSearch generates a document ID. In the preceding request, the document ID is specified as the student ID (1).

To learn more about indexing, see Managing indexes.

Dynamic mapping

When you index a document, OpenSearch infers the field types from the JSON types submitted in the document. This process is called dynamic mapping. For more information, see Dynamic mapping.

To view the inferred field types, send a request to the _mapping endpoint:

  1. GET /students/_mapping

copy

OpenSearch responds with the field type for each field:

  1. {
  2.   "students": {
  3.     "mappings": {
  4.       "properties": {
  5.         "gpa": {
  6.           "type": "float"
  7.         },
  8.         "grad_year": {
  9.           "type": "long"
  10.         },
  11.         "name": {
  12.           "type": "text",
  13.           "fields": {
  14.             "keyword": {
  15.               "type": "keyword",
  16.               "ignore_above": 256
  17.             }
  18.           }
  19.         }
  20.       }
  21.     }
  22.   }
  23. }

OpenSearch mapped the numeric fields to the float and long types. Notice that OpenSearch mapped the name text field to text and added a name.keyword subfield mapped to keyword. Fields mapped to text are analyzed (lowercased and split into terms) and can be used for full-text search. Fields mapped to keyword are used for exact term search.

OpenSearch mapped the grad_year field to long. If you want to map it to the date type instead, you need to delete the index and then recreate it, explicitly specifying the mappings. For instructions on how to explicitly specify mappings, see Index mappings and settings.

Searching for documents

To run a search for the document, specify the index that you’re searching and a query that will be used to match documents. The simplest query is the match_all query, which matches all documents in an index:

  1. GET /students/_search
  2. {
  3.   "query": {
  4.     "match_all": {}
  5.   }
  6. }

copy

OpenSearch returns the indexed document:

  1. {
  2.   "took": 12,
  3.   "timed_out": false,
  4.   "_shards": {
  5.     "total": 1,
  6.     "successful": 1,
  7.     "skipped": 0,
  8.     "failed": 0
  9.   },
  10.   "hits": {
  11.     "total": {
  12.       "value": 1,
  13.       "relation": "eq"
  14.     },
  15.     "max_score": 1,
  16.     "hits": [
  17.       {
  18.         "_index": "students",
  19.         "_id": "1",
  20.         "_score": 1,
  21.         "_source": {
  22.           "name": "John Doe",
  23.           "gpa": 3.89,
  24.           "grad_year": 2022
  25.         }
  26.       }
  27.     ]
  28.   }
  29. }

For more information about search, see Search your data.

Updating documents

In OpenSearch, documents are immutable. However, you can update a document by retrieving it, updating its information, and reindexing it. You can update an entire document using the Index Document API, providing values for all existing and added fields in the document. For example, to update the gpa field and add an address field to the previously indexed document, send the following request:

  1. PUT /students/_doc/1
  2. {
  3.   "name": "John Doe",
  4.   "gpa": 3.91,
  5.   "grad_year": 2022,
  6.   "address": "123 Main St."
  7. }

copy

Alternatively, you can update parts of a document by calling the Update Document API:

  1. POST /students/_update/1/
  2. {
  3.   "doc": {
  4.     "gpa": 3.91,
  5.     "address": "123 Main St."
  6.   }
  7. }

copy

For more information about partial document updates, see Update Document API.

Deleting a document

To delete a document, send a delete request and provide the document ID:

  1. DELETE /students/_doc/1

copy

Deleting an index

To delete an index, send the following request:

  1. DELETE /students

copy

Index mappings and settings

OpenSearch indexes are configured with mappings and settings:

  • A mapping is a collection of fields and the types of those fields. For more information, see Mappings and field types.
  • Settings include index data like the index name, creation date, and number of shards. For more information, see Configuring OpenSearch.

You can specify the mappings and settings in one request. For example, the following request specifies the number of index shards and maps the name field to text and the grad_year field to date:

  1. PUT /students
  2. {
  3.   "settings": {
  4.     "index.number_of_shards": 1
  5.   }, 
  6.   "mappings": {
  7.     "properties": {
  8.       "name": {
  9.         "type": "text"
  10.       },
  11.       "grad_year": {
  12.         "type": "date"
  13.       }
  14.     }
  15.   }
  16. }

copy

Now you can index the same document that you indexed in the previous section:

  1. PUT /students/_doc/1
  2. {
  3.   "name": "John Doe",
  4.   "gpa": 3.89,
  5.   "grad_year": 2022
  6. }

copy

To view the mappings for the index fields, send the following request:

  1. GET /students/_mapping

copy

OpenSearch mapped the name and grad_year fields according to the specified types and inferred the field type for the gpa field:

  1. {
  2.   "students": {
  3.     "mappings": {
  4.       "properties": {
  5.         "gpa": {
  6.           "type": "float"
  7.         },
  8.         "grad_year": {
  9.           "type": "date"
  10.         },
  11.         "name": {
  12.           "type": "text"
  13.         }
  14.       }
  15.     }
  16.   }
  17. }

Once a field is created, you cannot change its type. Changing a field type requires deleting the index and recreating it with the new mappings.

Further reading

Next steps