Walkthrough: Configure Azure Cognitive Search

Abstract

Configure your Azure Cognitive Search instance with this developer guide.

Caution

Azure Cognitive Search will be discontinued in the future and Sitecore will no longer provide support for this service in future releases.

To use Azure Cognitive Search with Sitecore you must first configure your Azure Cognitive Search service with your Sitecore instance. Work through the following sections to configure your Azure Cognitive Search service.

Create a search service

To create a search service with Azure, work through the following instructions.

  1. Log in to the Azure portal, click More services, and create a Search service.

  2. In the Filter field, enter Search service and click Search services.

    The Filter field.

  3. In the Search services window, click Add.

    Click Add.

  4. In the New Search Service window:

    • Specify the name of your Search Service instance.

    • Choose the type of subscription that suits you.

    • Choose the appropriate resource group, location, and pricing tier that suits you.

    Note

    Sitecore uses 15 search indexes, and therefore requires the Standard pricing tier as a minimum. 

    The S standard pricing tier.

  5. When the Search Service instance is configured, click Create.

  6. Open your newly created search service and click Settings, Keys.

  7. Copy the Primary admin key or the Secondary admin key to the apiKey parameter. It doesn't matter which key you choose to use, but the key will be used in the connection string.

Format the connection string

The default connection string name for Cloud Search is cloud.search and it contains the following information:

  • serviceUrl – the HTTPS URL of the search service API (for example, https://dk-test.search.windows.net).

  • apiVersion – follows a date format, for example, 2015-11-11 (see more information on API versions).

  • apiKey – the admin key to the service that you obtain from the Azure management portal.

Note

The latest supported version is 2017-11-11. For information about other supported versions, refer to the Azure Search compatibility table.

The connection string format is:

<add name="cloud.search" connectionString="serviceUrl=<url>;apiVersion=<apiVersion>;apiKey=<apiKey>" />

Note

Azure Cognitive Search for xConnect does not support this feature.

Geo-replicated scenarios

Sitecore supports a Search service with geo-replicated scenarios. To use this type of scenario:

  1. Create two or more Search service instances.

  2. Add connection strings with a pipe separator (|). If you have two search services, for example, searchservice1 and searchservice2, and you want to use them in a geo-replicated scenario, you must use the following connection string:

    <add name="cloud.search" 
connectionString="serviceUrl=https://searchservice1.search.windows.net;apiVersion=2015-02-28;apiKey=AdminKey1|serviceUrl=https://searchservice2.search.windows.net;apiVersion=2015-02-28;apiKey=AdminKey2" />

Advanced scaling scenarios

For advanced scaling scenarios, it is best practice to use a dedicated search service for your index. To set this up:

  1. Add a new connection string (for example, cloud.search.analytics).

  2. Configure the corresponding index with this connection string name:

Configure the corresponding index with the connection string name.

Set up configuration files

The Cloud search provider follows the same configuration pattern as Solr and Lucene and brings Azure-specific settings in a separate configuration file. To set up Azure Cognitive Search, you must first disable all Lucene or Solr configuration files and enable the corresponding cloud configuration files.

By default Sitecore is distributed with the Lucene search provider enabled.

You must switch the configuration files so that Azure Cognitive Search is enabled and Lucene is disabled:

  1. Enable the following *.Azure.Index* files by removing the .disabled extension:

    • Sitecore.ContentSearch.Azure.DefaultIndexConfiguration.config.disabled

    • Sitecore.ContentSearch.Azure.Index.Analytics.config.disabled

    • Sitecore.ContentSearch.Azure.Index.Core.config.disabled

    • Sitecore.ContentSearch.Azure.Index.Master.config.disabled

    • Sitecore.ContentSearch.Azure.Index.Web.config.disabled

    • Sitecore.ContentTesting.Azure.IndexConfiguration.config.disabled

    • Sitecore.FXM.Azure.DomainsSearch.DefaultIndexConfiguration.config.disabled

    • Sitecore.FXM.Azure.DomainsSearch.Index.Master.config.disabled

    • Sitecore.FXM.Azure.DomainsSearch.Index.Web.config.disabled

    • Sitecore.ListManagement.Azure.Index.List.config.disabled

    • Sitecore.ListManagement.Azure.IndexConfiguration.config.disabled

    • Sitecore.Marketing.Azure.Index.Master.config.disabled

    • Sitecore.Marketing.Azure.Index.Web.config.disabled

    • Sitecore.Marketing.Azure.IndexConfiguration.config.disabled

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories.Azure.Index.Master.config.disabled

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories.Azure.Index.Web.config.disabled

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories.Azure.IndexConfiguration.config.disabled

    • Sitecore.Social.Azure.Index.Master.config.disabled

    • Sitecore.Social.Azure.Index.Web.config.disabled

    • Sitecore.Social.Azure.IndexConfiguration.config.disabled

  2. Disable all of the following Lucene *.Lucene.Index files by adding the .disabled extension:

    • Sitecore.ContentSearch.Lucene.DefaultIndexConfiguration.config

    • Sitecore.ContentSearch.Lucene.Index.Analytics.config

    • Sitecore.ContentSearch.Lucene.Index.Core.config

    • Sitecore.ContentSearch.Lucene.Index.Master.config

    • Sitecore.ContentSearch.Lucene.Index.Web.config

    • Sitecore.ContentTesting.Lucene.IndexConfiguration.config

    • Sitecore.FXM.Lucene.DomainsSearch.DefaultIndexConfiguration.config

    • Sitecore.FXM.Lucene.DomainsSearch.Index.Master.config

    • Sitecore.FXM.Lucene.DomainsSearch.Index.Web.config

    • Sitecore.ListManagement.Lucene.Index.List.config

    • Sitecore.ListManagement.Lucene.IndexConfiguration.config

    • Sitecore.Marketing.Lucene.Index.Master.config

    • Sitecore.Marketing.Lucene.Index.Web.config

    • Sitecore.Marketing.Lucene.IndexConfiguration.config

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories.Lucene.Index.Master.config

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories.Lucene.Index.Web.config

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories.Lucene.IndexConfiguration.config

    • Sitecore.Social.Lucene.Index.Master.config

    • Sitecore.Social.Lucene.Index.Web.config

    • Sitecore.Social.Lucene.IndexConfiguration.config

    • Sitecore.Speak.ContentSearch.Lucene.configSitecore.Marketing.Definitions.MarketingAssets.Repositories. Lucene.Index.Web.config

    • Sitecore.Marketing.Definitions.MarketingAssets.Repositories. Lucene.IndexConfiguration.config

    • Sitecore.Social.Lucene.Index.Master.config

    • Sitecore.Social.Lucene.Index.Web.config

    • Sitecore.Social.Lucene.IndexConfiguration.config

    • Sitecore.Speak.ContentSearch.Lucene.config

Rebuild the indexes

You must rebuild the indexes to ensure Sitecore is fully operational.

To rebuild the indexes:

  1. Go to the Sitecore login page (http:// {your_instance}/sitecore/login) and log in with your admin credentials.

  2. On the Sitecore Launchpad, click Control Panel, and select Indexing manager.

  3. To select and rebuild all of the indexes, on the Indexing Manager page, click Select all, Rebuild.

    Note

    Rebuilding the index is a time consuming operation and can take 15 minutes or more.

    When the indexes are rebuilt, the Sitecore search indexes appear in the Search service window of the Azure Portal.

    Indexes.

Map the Azure field types

Azure Cognitive Search uses the following Entity Data Model (EDM) field types. Refer to the table to ensure you map the field types correctly.

Field type

Description

Edm.String

Optional: Text that can be tokenized for full-text search, for example, word-breaking, stemming, and so on.

Collection(Edm.String)

A list of strings that can be tokenized for full-text search. There is no upper limit on the number of items in a collection, but remember that the 16 MB upper limit on payload size applies to collections.

Edm.Boolean

Contains true or false values.

Edm.Int32

Contains 32-bit integer values.

Edm.Int64

Contains 64-bit integer values.

Edm.Double

Uses double-precision numeric data.

Edm.DateTimeOffset

The date and time values are represented in the OData V4 format, for example:

yyyy-MM-ddTHH:mm:ss.fffZ

yyyy-MM-ddTHH:mm:ss.fff[+|-]HH:mm.

Note

The precision of DateTime fields is limited to milliseconds. If you upload DateTime values that have submillisecond precision, the returned value will be rounded up to milliseconds, for example:

2015-04-15T10:30:09.7552052Z will be returned as:

2015-04-15T10:30:09.7550000Z.

To see how to define the different types of mapping between .Net and Sitecore, go to sitecore\contentsearch\indexConfigurations\defaultCloudIndexConfiguration\CloudTypeMapper, and open the Sitecore.ContentSearch.Cloud.DefaultIndexConfiguration.config file.

Note

You must define the map element for all custom fields like this:

<map type="<Field type>" cloudType="<Edm type from list of supported types>" />

Map fields

When listing all of the fields that the components use under the index configuration section, it is best practice that you list them as follows:

  • sitecore\contentSearch\configuration\indexes\index\configuration\fieldMap

The supported attributes are:

Attribute

Description

fieldName

The name of the field, as defined for Lucene and Solr.

cloudFieldName

The field name as defined for Cloud. It can only contain letters, numbers, and underscores.

Note

The first character must be a letter.

boost

Use the boost attribute to give one field more importance than another.

format

You must configure this attribute for DateTime type fields. The supported value is yyyy-MM-ddTHH:mm:ss.fffZ.

settingType

The settingType property must be: Sitecore.Cloud.ContentSearch.CloudSearchFieldConfiguration, Sitecore.Cloud.ContentSearch

Support for Azure Cognitive Search

Use the support reference for Azure Cognitive Search to ensure that you configure query support and facet support correctly.