Enable or disable semantic ranker

Semantic ranker is a premium feature that's billed by usage. By default, semantic ranker is turned off on a new search service, but it can be enabled by anyone with Contributor permissions. If you don't want anyone enabling it inadvertently, you can disable it using the REST API.

Check availability

Check the regions list to see if your region is listed.

Enable semantic ranker

Follow these steps to enable semantic ranker at the service level. Once enabled, it's available to all indexes. You can't turn it on or off for specific indexes.

Azure portal

1. Open the Azure portal.

2. Navigate to your search service. On the Overview page, make sure the service is a billable tier, Basic or higher.

3. On the left-nav pane, select Settings > Semantic ranking.

4. Select either the Free plan or the Standard plan. You can switch between the free plan and the standard plan at any time.

   

The free plan is capped at 1,000 queries per month. After the first 1,000 queries in the free plan, an error message indicates you've exhausted your quota on the next semantic query. When quota is exhausted, you should upgrade to the standard plan to continue using semantic ranking.

REST

To enable semantic ranker using the REST API, you can use the Create or Update Service API.

Management REST API calls are authenticated through Microsoft Entra ID. See Manage your Azure AI Search service with REST APIs for instructions on how to authenticate.

• Management REST API version 2023-11-01 provides the configuration property.

• Owner or Contributor permissions are required to enable or disable features.

Note

Create or Update supports two HTTP methods: PUT and PATCH. Both PUT and PATCH can be used to update existing services, but only PUT can be used to create a new service. If PUT is used to update an existing service, it replaces all properties in the service with their defaults if they are not specified in the request. When PATCH is used to update an existing service, it only replaces properties that are specified in the request. When using PUT to update an existing service, it's possible to accidentally introduce an unexpected scaling or configuration change. When enabling semantic ranking on an existing service, it's recommended to use PATCH instead of PUT.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
    {
      "properties": {
        "semanticSearch": "standard"
      }
    }

Disable semantic ranker using the REST API

To reverse feature enablement, or for full protection against accidental usage and charges, you can disable semantic ranker using the Create or Update Service API on your search service. After the feature is disabled, any requests that include the semantic query type will be rejected.

Management REST API calls are authenticated through Microsoft Entra ID. See Manage your Azure AI Search service with REST APIs for instructions on how to authenticate.

PATCH https://management.azure.com/subscriptions/{{subscriptionId}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2023-11-01
    {
      "properties": {
        "semanticSearch": "disabled"
      }
    }

To re-enable semantic ranker, rerun the previous request, setting "semanticSearch" to either "free" (default) or "standard".

Next steps

Configure semantic ranker so that you can test out semantic ranking on your content.