Enable or disable semantic ranker

Semantic ranker is a premium feature that's billed by usage. By default, semantic ranker is disabled on all services.

Check availability

Check the Products Available by Region page on the Azure web site to see if your region is listed.

Enable semantic ranking

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 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, you'll receive an error message letting you know you've exhausted your quota the next time you issue a semantic query. When this happens, you need to upgrade to the standard plan to continue using semantic ranking.

REST

To enable semantic ranking 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 ranking using the REST API

To reverse feature enablement, or for full protection against accidental usage and charges, you can disable semantic ranking 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 ranking, rerun the above request, setting "semanticSearch" to either "free" (default) or "standard".

Next steps

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