AWS Builder Center
Running Your first Search on OpenSearch

Running Your first Search on OpenSearch

Search on OpenSearch · Part 1 of 9: Create an index, add a document, and run your first query in under ten minutes

Series: Search on OpenSearch (8 articles)

  1. 1
    Running Your first Search on OpenSearch This article
OpenSearch Specialist Solutions Architect at AWS
The first time I opened a search engine's API, I wanted one thing: put a record in, search for it, get it back. Everything else, the relevance tuning, the vectors, the aggregations, comes later. So that is exactly what this first part does. By the end you will have created an index, added a document, and run a query that returns it, and you will understand what each step did.
This is Part 1 of a beginner series on search with  Amazon OpenSearch Service , the managed service for running  OpenSearch  in the AWS Cloud. You do not need any prior search experience, and you do not need to install anything. You need one thing: access to an OpenSearch Service deployment where you can run queries in a browser. The next section sets up the fastest one.

Set up a test environment (the fast path)

You need a place to run these commands. For learning and testing, the quickest option is  Amazon OpenSearch Serverless , because there are no instances to size or provision the way an Amazon OpenSearch Service domain requires. In the console, choose the NextGen collection generation and use Express Create: enter a name, choose the Search collection type, and choose Create collection. Express Create builds the encryption, network, and data access policies for you with sensible defaults, so you skip writing security policies by hand. The collection reaches  Active  in a few minutes, which is faster than provisioning a domain.
Express Create defaults to public network access and grants your current IAM principal full access to the collection. That is convenient for a tutorial. Do not reuse those defaults for anything with real data. OpenSearch Serverless also scales compute to zero when your collection group is idle, so a test environment costs you only storage while you are not using it (scale-to-zero-compute, not zero cost).
Once the collection is  Active , open Dev Tools to run the requests in this article. Dev Tools is the query console inside OpenSearch Dashboards, the visualization and query interface tied to the single domain or collection that hosts it. In Dev Tools you type a request on the left and see the response on the right, so you do not install anything or write any code.
You may also come across OpenSearch UI, and it is worth knowing the difference. OpenSearch UI is a modernized, AWS Cloud-hosted analytics interface that gives you a unified view across multiple data sources and organizes work into workspaces such as Search, Observability, and Security Analytics. Unlike OpenSearch Dashboards, which connects only to the one domain or collection that hosts it, OpenSearch UI can connect to several. For this article, you only need Dev Tools in OpenSearch Dashboards.
Two terms before you start. An index is where OpenSearch stores a group of related records, similar to a table in a database. A document is a single record, written as JSON. That is enough vocabulary to begin.

Step 1: Create an index

In Dev Tools, run the following.  PUT  creates the index named  books .
PUT books
The response includes  "acknowledged": true , which means the index exists. You did not define any fields yet. OpenSearch can infer field types from the first document you add, which is fine while you are learning.

Step 2: Add a document

Now add one book.  POST  sends a new document to the  books  index, and  _doc  is the endpoint for adding documents.
POST books/_doc
{
"title": "The Left Hand of Darkness",
"author": "Ursula K. Le Guin",
"year": 1969
}
The response contains  "result": "created"  and an auto-generated  _id . Your document is now stored and searchable. Add one or two more books the same way so your query has something to choose from.
POST books/_doc
{
"title": "A Wizard of Earthsea",
"author": "Ursula K. Le Guin",
"year": 1968
}

Step 3: Run your first query

Search the  title  field for the word "darkness".  GET  with  _search  runs a query, and  match  is the standard full-text query for "find documents where this field contains these words".
GET books/_search
{
"query": {
"match": {
"title": "darkness"
}
}
}
You get back a  hits  section. Inside it,  hits.total.value  tells you how many documents matched, and each entry under  hits.hits  is a matching document with its stored fields in  _source . The book with "darkness" in its title comes back, and the one without it does not.
Notice that you searched for "darkness" in lowercase and matched a title that has "Darkness" capitalized. That is because  match  analyzes text: it lowercases and splits the field into terms before comparing. This is the difference between full-text search and an exact string comparison, and it is why search feels forgiving. Part 2 goes deeper into  match  and how to combine conditions.

What just happened

You did three things: created a place to store records, added a record, and asked a question that returned it. The important idea is that OpenSearch broke your title text into searchable terms at index time, so a loose query still finds the right document. You did not configure relevance, shards, or mappings, and you did not need to. Those become useful once you have a real dataset and real queries, which is where the rest of this series goes.

Series: Search on OpenSearch (8 articles)

  1. 1
    Running Your first Search on OpenSearch This article
Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.
Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article