Searching with Query Strings – Basics

In this post, we will take a look at searching through the use of query strings in the URI.

The query string API is powerful and contains many features, so I am just going to show you the basic and most important ways to use it. If you need a complete walkthrough of the query string API, then please refer to the documentation.

Let’s write a simple query to start with. I will use the “ecommerce” index and search for documents with the product type. To perform searches, I will use the _search API, and because I want to search by query string, I will add a q parameter. The value of this parameter is going to be our search string. For the first example, I just want to show you how you can match all of the documents of the product type within the index, which you can do by using an asterisk as a wildcard. This can be useful if you want to have an index of all of the documents, for instance.

GET /ecommerce/product/_search?q=*

999 documents are matched, which is the total number of documents in the index.

I will just take a moment to discuss the important parts of the result. Within the hits key, there are two meta properties about the results. The total property contains the number of matched results, while the max_score property contains the highest score of all the matched documents. The nested hits property contains an array of matched documents. For each document, you can see the meta fields that we discussed in a previous post. Another important property is _score, which is a score indicating how well the document matched the search query. This number is based on complex mathematical calculations, and you do not need to know more about this for now. The _source property contains the matched document as the JSON that we added to the index when we added the document.

Next, let’s try to search for a specific value, for example pasta.

GET /ecommerce/product/_search?q=pasta

By default, query string searches search all fields, unless one or more fields are specified in the query. In this example, we are therefore searching for the term pasta in any field within a document of the type product, within the ecommerce index.

We can also specify which field should contain the value. We do this by adding the name of the field, followed by a colon and then the value.

GET /ecommerce/product/_search?q=name:pasta

This means that we are searching for all of the products that contain pasta in their name. With our test data, this gives the same result, but if I change the field name to description, then you will see that we get no matches.

GET /ecommerce/product/_search?q=description:pasta

Those were the very basics of searching with query strings in Elasticsearch. In the following posts, I will talk about more features, before I will move on to talking about the query DSL.