Quickstart: Use Search explorer to run queries in the portal

In this quickstart, you'll learn how to use Search explorer, a built-in query tool in the Azure portal used for running queries against a search index in Azure Cognitive Search. This tool makes it easy to learn query syntax, test a query or filter expression, or confirm data refresh by checking whether new content exists in the index.

This quickstart uses an existing index to demonstrate Search explorer.

Prerequisites

Before you begin, have the following prerequisites in place:

• An Azure account with an active subscription. Create an account for free.

• An Azure Cognitive Search service. Create a service or find an existing service under your current subscription. You can use a free service for this quickstart.

• The realestate-us-sample-index is used for this quickstart. To create the index, use the Import data wizard, choose the sample data, and step through the wizard using all of the default values.

  

Start Search explorer

1. In the Azure portal, open the search overview page from the dashboard or find your service.

2. Open Search explorer from the command bar:

   

   Or use the embedded Search explorer tab on an open index:

   

Unspecified query

In Search explorer, requests are formulated using the Search REST API, with responses returned as verbose JSON documents.

For a first look at content, execute an empty search by clicking Search with no terms provided. An empty search is useful as a first query because it returns entire documents so that you can review document composition. On an empty search, there's no search rank and documents are returned in arbitrary order ("@search.score": 1 for all documents). By default, 50 documents are returned in a search request.

Equivalent syntax for an empty search is * or search=*.

search=*

Results

Free text search

Free-form queries, with or without operators, are useful for simulating user-defined queries sent from a custom app to Azure Cognitive Search. Only those fields attributed as Searchable in the index definition are scanned for matches.

Notice that when you provide search criteria, such as query terms or expressions, search rank comes into play. The following example illustrates a free text search. The "@search.score" is a relevance score computed for the match using the default scoring algorithm.

Seattle apartment "Lake Washington" miele OR thermador appliance

Results

You can use Ctrl-F to search within results for specific terms of interest.

Count of matching documents

Add $count=true to get the number of matches found in an index. On an empty search, count is the total number of documents in the index. On a qualified search, it's the number of documents matching the query input. Recall that the service returns the top 50 matches by default, so the count might indicate more matches in the index than what's returned in the results.

$count=true

Results

Limit fields in search results

Add $select to limit results to the explicitly named fields for more readable output in Search explorer. To keep the previously mentioned parameters in the query, use & to separate each parameter.

search=seattle condo&$select=listingId,beds,baths,description,street,city,price&$count=true

Results

Return next batch of results

Azure Cognitive Search returns the top 50 matches based on the search rank. To get the next set of matching documents, append $top=100,&$skip=50 to increase the result set to 100 documents (default is 50, maximum is 1000), skipping the first 50 documents. You can check the document key (listingID) to identify a document.

Recall that you need to provide search criteria, such as a query term or expression, to get ranked results. Notice that search scores decrease the deeper you reach into search results.

search=seattle condo&$select=listingId,beds,baths,description,street,city,price&$count=true&$top=100&$skip=50

Results

Filter expressions (greater than, less than, equal to)

Use the $filter parameter when you want to specify precise criteria rather than free text search. The field must be attributed as Filterable in the index. This example searches for bedrooms greater than 3:

search=seattle condo&$filter=beds gt 3&$count=true

Results

Sorting results

Add $orderby to sort results by another field besides search score. The field must be attributed as Sortable in the index. An example expression you can use to test this out is:

search=seattle condo&$select=listingId,beds,price&$filter=beds gt 3&$count=true&$orderby=price asc

Results

Both $filter and $orderby expressions are OData constructions. For more information, see Filter OData syntax.

Takeaways

In this quickstart, you used Search explorer to query an index using the REST API.

• Results are returned as verbose JSON documents so that you can view document construction and content, in entirety. The $select parameter in a query expression can limit which fields are returned.

• Search results are composed of all fields marked as Retrievable in the index. To view field attributes in the portal, select realestate-us-sample in the Indexes list on the search overview page, and then open the Fields tab.

• Keyword search, similar to what you might enter in a commercial web browser, are useful for testing an end-user experience. For example, assuming the built-in real estate sample index, you could enter "Seattle apartments lake washington", and then you can use Ctrl-F to find terms within the search results.

• Query and filter expressions are articulated in a syntax implemented by Azure Cognitive Search. The default is a simple syntax, but you can optionally use full Lucene for more powerful queries. Filter expressions are articulated in an OData syntax.

Clean up resources

When you're working in your own subscription, it's a good idea at the end of a project to identify whether you still need the resources you created. Resources left running can cost you money. You can delete resources individually or delete the resource group to delete the entire set of resources.

You can find and manage resources in the portal, using the All resources or Resource groups link in the left-navigation pane.

If you're using a free service, remember that you're limited to three indexes, indexers, and data sources. You can delete individual items in the portal to stay under the limit.

Next steps

To learn more about query structures and syntax, use Postman or an equivalent tool to create query expressions that use more parts of the API. The Search REST API is especially helpful for learning and exploration.

Create a basic query in Postman