
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)
- 1Running Your first Search on OpenSearch This article
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 booksThe 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)
- 1Running Your first Search on OpenSearch This article
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article