Quickstart: Use Search explorer to run queries in the Azure portal

In this quickstart, you learn how to use Search explorer, a built-in query tool in the Azure portal for running queries against an Azure AI Search index. Use this tool to test a query or filter expression or to confirm whether content exists in the index.

This quickstart uses an existing index to demonstrate Search explorer.

Prerequisites

• An Azure account with an active subscription. Create a trial subscription.

• An Azure AI Search service. Create a service or find an existing service in your current subscription. For this quickstart, you can use a free service.

• This quickstart uses the realestate-us-sample index. To create the index, run the Import data wizard, select the built-in sample data, and step through the wizard using all the default values.

  

Start Search explorer

1. Sign in to the Azure portal and select your search service.

2. From the left pane, select Overview.

3. On the command bar, select Search explorer.

   

   Alternatively, select the Search explorer tab on the index page.

   

Query three ways

There are three approaches to querying in Search explorer:

• Query view provides a default search bar. It accepts an empty query or free-text query with Booleans, such as seattle condo + parking.

• Image view provides a window to browse or drag and drop PNG, JPG, or JPEG files. Unless your index has an image vectorizer and an equivalent skill, this view is unavailable.

• JSON view supports parameterized queries. Filters, orderby, select, count, searchFields, and all other parameters must be set in JSON view.

  

Example: Image query

Search explorer accepts images as query inputs through Image view, which requires that you use a supported vectorizer-skill pair. For more information, see Configure a vectorizer in a search index.

The realestate-us-sample index isn't configured for image vectorization. If you want to run image queries, create an index as described in Quickstart: Vector search in the Azure portal. The quickstart relies on text-based sample data, so you must use documents that contain images.

To run an image query, select or drag an image to the search area, and then select Search. Search explorer vectorizes the image and sends the vector to the search engine for query execution. The search engine returns documents that are sufficiently similar to the input image, up to the specified k number of results.

Examples: JSON queries

The following are examples of JSON queries you can run using Search explorer. To follow these examples, switch to JSON view. You can paste each JSON example into the text area.

Run an unspecified query

In Search explorer, POST requests are formulated internally using Documents - Search Post (REST API), with responses returned as verbose JSON documents.

For a first look at content, execute an empty search by selecting 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 score, and documents are returned in arbitrary order ("@search.score": 1 for all documents). By default, 50 documents are returned per search request.

Equivalent syntax for an empty search is * or "search": "*".

{
   "search": "*",
   "count": true
}

Results

Run a free-text query

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

You don't need the JSON view for a free-text query, but we provide it in JSON for consistency with other examples in this article.

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.

{
    "search": "Seattle townhouse `Lake Washington` miele OR thermador appliance"
}

Results

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

Count matching documents

Add "count": true to get the number of matches found in an index. On an empty search, the 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.

{
    "search": "Seattle townhouse `Lake Washington` miele OR thermador appliance",
    "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. Only fields attributed as retrievable in the index can show up in results.

{
   "search": "seattle condo",
   "count": true,
   "select": "listingId, beds, baths, description, street, city, price"
}

Results

Return next batch of results

Azure AI Search returns the top-50 matches based on the search rank. To get the next set of matching documents, append "top": 100 and "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. Search scores decrease the deeper you reach into search results.

{
   "search": "seattle condo",
   "count": true,
   "select": "listingId, beds, baths, description, street, city, price",
   "top": 100,
   "skip": 50
}

Results

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

Use the filter parameter to specify inclusion or exclusion criteria. The field must be attributed as filterable in the index. This example searches for bedrooms greater than three:

{
    "search": "seattle condo",
    "count": true,
    "select": "listingId, beds, baths, description",
    "filter": "beds gt 3"
}

Results

Sort results

Add orderby to sort results by another field besides search score. The field must be attributed as sortable in the index. In situations where the filtered value is identical (for example, same price), the order is arbitrary, but you can add more criteria for deeper sorting. Here's an example expression you can use to test this out:

{
    "search": "seattle condo",
    "count": true,
    "select": "listingId, price, beds, baths, description",
    "filter": "beds gt 3",
    "orderby": "price asc"
}

Results

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 the construction and content of each document in its entirety. The select parameter in a query expression limits which fields are returned.

• Search results are composed of all fields attributed as retrievable in the index. Select the Fields tab to review attributes.

• Keyword search, similar to what you might enter in a commercial web browser, is useful for testing an end-user experience. For example, assuming the built-in realestate-us-sample index, you can 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 AI 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 work 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.

In the Azure portal, you can find and manage resources by selecting All resources or Resource groups from the left pane.

Remember that a free search service is limited to three indexes, three indexers, and three data sources. To stay under the limit, you can delete these items individually in the Azure portal.

Next step

To learn more about query structures and syntax, use a REST client to create query expressions that use more parts of the REST API. Documents - Search Post (REST API) is especially helpful for learning and exploration.