You're viewing version 2.13 of the OpenSearch documentation. This version is no longer maintained. For the latest version, see the current documentation. For information about OpenSearch version maintenance, see Release Schedule and Maintenance Policy.
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:
curl -XGET "http://localhost:9200/_cluster/health"
If you’re using the Security plugin, provide the username and password in the request:
curl -X GET "http://localhost:9200/_cluster/health" -ku admin:<custom-admin-password>
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:
curl -XGET "http://localhost:9200/_cluster/health?pretty"
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:
curl -XGET "http://localhost:9200/students/_search?pretty" -H 'Content-Type: application/json' -d'
{
"query": {
"match_all": {}
}
}'
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:
- 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 isadmin
, and the password is set in yourdocker-compose.yml
file in theOPENSEARCH_INITIAL_ADMIN_PASSWORD=<custom-admin-password>
setting. - On the top menu bar, go to Management > Dev Tools.
- In the left pane of the console, enter the following request:
GET _cluster/health
- 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
(orCmd+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:
PUT https://<host>:<port>/<index-name>/_doc/<document-id>
For example, to index a document representing a student, you can send the following request:
PUT /students/_doc/1
{
"name": "John Doe",
"gpa": 3.89,
"grad_year": 2022
}
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:
GET /students/_mapping
OpenSearch responds with the field type
for each field:
{
"students": {
"mappings": {
"properties": {
"gpa": {
"type": "float"
},
"grad_year": {
"type": "long"
},
"name": {
"type": "text",
"fields": {
"keyword": {
"type": "keyword",
"ignore_above": 256
}
}
}
}
}
}
}
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 settings and mappings.
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:
GET /students/_search
{
"query": {
"match_all": {}
}
}
OpenSearch returns the indexed document:
{
"took": 12,
"timed_out": false,
"_shards": {
"total": 1,
"successful": 1,
"skipped": 0,
"failed": 0
},
"hits": {
"total": {
"value": 1,
"relation": "eq"
},
"max_score": 1,
"hits": [
{
"_index": "students",
"_id": "1",
"_score": 1,
"_source": {
"name": "John Doe",
"gpa": 3.89,
"grad_year": 2022
}
}
]
}
}
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:
PUT /students/_doc/1
{
"name": "John Doe",
"gpa": 3.91,
"grad_year": 2022,
"address": "123 Main St."
}
Alternatively, you can update parts of a document by calling the Update Document API:
POST /students/_update/1/
{
"doc": {
"gpa": 3.91,
"address": "123 Main St."
}
}
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:
DELETE /students/_doc/1
Deleting an index
To delete an index, send the following request:
DELETE /students
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
:
PUT /students
{
"settings": {
"index.number_of_shards": 1
},
"mappings": {
"properties": {
"name": {
"type": "text"
},
"grad_year": {
"type": "date"
}
}
}
}
Now you can index the same document that you indexed in the previous section:
PUT /students/_doc/1
{
"name": "John Doe",
"gpa": 3.89,
"grad_year": 2022
}
To view the mappings for the index fields, send the following request:
GET /students/_mapping
OpenSearch mapped the name
and grad_year
fields according to the specified types and inferred the field type for the gpa
field:
{
"students": {
"mappings": {
"properties": {
"gpa": {
"type": "float"
},
"grad_year": {
"type": "date"
},
"name": {
"type": "text"
}
}
}
}
}
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
- For information about the OpenSearch REST API, see the REST API reference.
- For information about OpenSearch language clients, see Clients.
- For information about mappings, see Mappings and field types.
- For information about settings, see Configuring OpenSearch.
Next steps
- See Ingest data into OpenSearch to learn about ingestion options.