Leverage Enhanced Search Results in Azure AI Search

You should already be logged into the Azure portal, using the credentials provided with the lab. When you first log in to the Azure Portal, you will land on the overview page for the resource group already deployed for you. Note the location/region for the resource group.

Using the Azure portal, create an Azure AI Search service with the following configuration:

• Create the service in the existing resource group, and in the same location as that resource group.
• Use any valid name you choose.
• Ensure the location matches the location of the resource group for the lab.
• Create the service in the Basic pricing tier. Do not choose the Free tier, as only one is allowed per subscription, and your lab environment is on a shared subscription with other students.

Navigate to the newly deployed Azure AI Search service, and on the "Overview" page, select "Import Data."

• Import from the existing "Samples" provided by Microsoft and choose the Cosmos DB dataset called "hotels-sample."
• Skip the option to add cognitive skills
• Customize the target index by making the LastRenovationDate filterable, if it is not already. This step will be important for the next objective.
• Take note of the other features enabled for each field, such as which ones can be used for sorting and filtering. Do not change any of the settings other than the LastRenovationDate field.
• Create the indexer, leaving all defaults in place.
• When the indexer run is complete, navigate to the index populated by the indexer and note the number of JSON documents created and the storage size. There should be about 50 documents, each containing the data related to a single hotel.

Tip: If the UI Indicates 0 Documents and 0 Bytes

If the UI in the index screen appears to indicate that there are no documents, make sure the indexer has completed running. However, there may also be a quirk in the UI. You can also perform a quick query by putting an asterisk (*) in the search bar and running the query. If the query returns documents, the UI just hasn't caught up with the underlying data statistics; you can proceed with the next objective.

At this point, you should have created the index and be on the Index page that includes not only the Search Explorer, but other features, such as a Scoring profile.

Browse the Indexed Data

• Switch to the JSON view for in the Search Explorer to execute the default search and see the results returned in no particular order.
• Edit the search JSON to only display four fields: HotelName, Description, Category, LastRenovationDate.
• Execute the query to confirm this greatly simplified view of the data, which will help you in the steps that follow. Note that the LastRenovationDate value varies from relatively recent, to the distant past.

Search Explorer Tips

• There may be a quirk in the UI, where the index UI appears to indicate that there are 0 documents and 0 bytes. As long as the Search Explorer query editor is returning records, you can safely ignore this UI error.
• Showing only specific fields: Add another parameter (key-value pair) after the "search" parameter, called "select" and assign the desired list of fields in a string wrapped in double-quotes. Be sure to separate the two parameters with a comma.
• Sticky Session: You may encounter a case where, after executing the query with an additional parameter to return only a handful of fields, the UI still returns all the fields (and no errors). To correct, copy the JSON of the search query and paste it back into the query window. Then execute the search, again. This should force the tool to recognize the desired query.

Create A Scoring Profile with One Scoring Function

Suppose you want to offer users of a hotel search web site the ability to sort returned results according the most recently renovated properties.

1. From the current screen, create a scoring proflie on the index, designed to show the most recently renovated hotel properties first. Based on calculations in the scoring profile, the first hotel property returned will have a search score (a "boost") as high as 5, where a non-boosted record will have a search score of 1. Boost only properties that were renovated in the last 15 years, 5475 days. This is referred to as the "boosting duration." All other properties will receive a search score of 1 and will be returned in no particular order, below the "boosted" properties.
2. Save the scoring profile definition.
3. A new scoring profile is an update to the index, so be sure to save the changed index after you save the scoring profile definition.
4. Run the search, again, to see the hotel properties, sorted by the most recently renovated. If the scoring profile is configured correctly, you should see about a half-dozen that were renovated within the last 15 years, and which have a search score above 1. All of the remaining hotel records should have a search score of 1. UI Quirk? See the "Sticky Session" tip under "Search Exploer Tips" if the returned results include the records with all fields instead of the select few defined in the query parameter.

Scoring Profile Tips

• Name the scoring profile anything you want and make it the default profile.
• A scoring profile can have both field weighting as well as one or more scoring functions. This profile will include just one scoring function.
• The type of the scoring function required is "freshness."
• Set the Interpolation parameter to "linear."
• Hover over the "info" tip (the letter "i" within a circle) next to the "Boost" and "Boosting Duration." to help you populate those with valid values that fulfill the description of the desired scoring profile.

Create A Scoring Profile with Weighting

Suppose you have noticed that users who search on the word "luxury" may see hotels that your organization has not rated as luxury level hotels, but where the description uses the word "luxury." You can control the category designation in your data, but not the description you receive from the hotel owners. You want to ensure that if a user happens to search on a term that is one of those used in the category fields that hotel properties with that term in the category field will be priortized — listed earlier in the returned results — over properties where it is only in the description. Technically, you can combine weighting and functions in a single scoring profile, but for simplicity, you are going to create a new default scoring profile.

1. Update this part of the query in the Search Explorer: "search": "*" to search specifically on the word "luxury," like this "search": "luxury". Execute the query and observe that there is a hotel categorized as "budget" near the top of the search results due to its relatively recent renovation. Scroll further, and you will see a few other hotels with the Category field assigned something other than "luxury."
2. From the current screen, create another scoring proflie on the index, designed to give greater credence to the data in the category field vs. the description field. Be sure to make this scoring profile the default profile. Weight the Category field to 20 and save the profile definition.
3. A new scoring profile is an update to the index, so be sure to save the changed index after you save the scoring profile definition.
4. Run the search on "luxury", again. The hotels with "luxury" in the Category field should be listed above those with other values in Category . UI Quirk? See the "Sticky Session" tip under "Search Exploer Tips" if the returned results include the records with all fields instead of the select few defined in the query parameter.

Tips for the Second Scoring Profile

• Name the scoring profile anything you want and make it the default profile.
• A scoring profile can have both field weighting as well as one or more scoring functions. This profile will include just field weighting.
• For future reference: The default scoring profile will be used, unless you indicate a scoring profile using the scoringProfile parameter of the query. But, for simplicity, we are simply modifying the default scoring profile designation for testing in this lab.

Context: At this point in the lab, you should be on the index page, where you were most recently working with the Search Explorer and Scoring Profiles. If not, navigate in the Azure Portal to the index you created in the prior objective. You should have also already set up storage backing for the Azure Cloud Shell as a housekeeping task. If not, return to the housekeeping objective, and complete that task.

When searching for a hotel at the beach, some of us might search on "shore," "coast," or "seaside," instead of "beach". In this objective, you will create a synonym map with a synonym rule set up on the search service, such that the four terms are treated as equivalent and the use of any of the four will return the same set of records, regardless of which of the four is used in the text of the hotel listing. Synonym maps are created at the service level in Azure AI Search and are applied at the field level.

Search the Indexed Data

1. In the Search Explorer, switch to the JSON view (if not already there), and enter this search query:

"search": "beach",
"select": "HotelName, Description"

The select parameter is used to simplify returned results for purposes of this exercise.

2. Execute the query and note that all the descriptions include either the term "beach" or the plural form, "beaches."
3. In the query editor, change the value of the search parameter to "shore" and execute to see that no results are returned. Do the same thing for "coast," and "seaside" to confirm that those terms do not return any results.

Create a Synonym Map with One Rule

Open the Cloud Shell integrated terminal and use the Azure CLI az rest command to construct a REST API call that creates the synonym map, described above, on the Azure AI Search service you created.

• You will need to use the following parameters: --method, --headers, --url, and --body.
• You can retrieve the service URI from the Overview page of your search service.
• Find "Keys" in the menu of the search service page to retrieve the primary admin key value and use it in your --headers argument.
• In the --method parameter, use POST (versus PUSH).
• For the api-version in the URL, use 2020-06-30.
• Name your synonym map "beach-synonyms".
• Punctuation tip: Note that both --headers and --body expect valid JSON, which will include double-quotes in the key-value pairs, so it is easier to wrap the values for those two arguments in single-quotes, versus escaping all the double-quotes in the JSON.
• If your API call is successful, the response will echo back the synonym map in JSON format. (You can ignore any informational message/warning regarding access tokens; we are providing a key to connect.)

NOTE: You may find it helpful to open the editor ({ }) in the Cloud Shell or, another text editor, as a scratch-sheet to construct your az restcommand.

ASSISTANCE OPTION 1: Complete the Synonym Map Guided by Documentation

Learn about the az rest command here:

Azure CLI az rest Command

Learn about how to construct the Synonym Map REST API call here:

Azure AI Search Synonym Map Basics

Azure AI Search Synonym Map with REST

ASSISTANCE OPTION 2: Complete the Synonym Map Guided by an Example

Replace the bold text with appropriate values:

az rest --method POST --headers '{"Content-Type": "application/json","api-key": "Your Admin Key"}' --url "https://your-search-service.search.windows.net/synonymmaps?api-version=2020-06-30" --body '{"name": "beach-synonyms","format": "solr","synonyms": "term1, term2, term3, term4"}'

Apply Synonym Map to Description Field

1. Navigate back to your search index (where you last used the Search Explorer).
2. Select the "Edit JSON" option to edit the index. Find the "Description" field and alter the synonymMaps parameter to reference the synonym map you just created, like this: "synonymMaps": ["beach-synonyms"]
3. In the Search Explorer, switch to the JSON view and enter this search query:

"search": "beach",
"select": "HotelName, Description"

4. Execute the query and note that all the descriptions include either the term "beach" or the plural form, "beaches."
5. In the query editor, change the value of the search parameter to "shore" and execute to see that it returns the same records as the query on "beach." Do the same thing for "coast," and "seaside" to confirm that those synonyms now, also work.

1. Open an incognito or in-private window and log in to the Azure portal using the username and password provided in the lab environment.
2. From within the portal, initiate the Cloud Shell to select Bash (versus PowerShell) and set up with new backing storage — do not use an existing storage account that might be deployed into the lab environment. You will need both storage accounts to complete the lab.