Azure Search naming restrictions

Azure Search has some limitations on it’s allowed naming conventions for index and field names. ExamineX will automatically re-format invalid names into valid names.

Field names

Generally you won’t have to worry about this because any custom field names defined in Examine will be returned correctly in the search results even though the actual field name in Azure Cognitive Search may be different. This is handled internally by Azure Cognitive Search field mappings. For example, Examine’s own naming conventions for ‘system’ fields are prefixed with double underscores like __NodeId. This field name is invalid in Azure Cognitive Search so is prefixed with x so the end result is x__NodeId.

Index names

Index names however are not so transparent since to access an Index in Examine it needs to be by it’s exact name. Therefore if you create a custom index with an invalid name you’ll need to check in the Azure portal to see what ExamineX has named the index. Index names in Azure Cognitive Search must: Start with a letter, use only lowercase letters, digits, or dashes (“-“), and have a limit of 60 characters. ExamineX will automatically transform any provided index name to align to these rules. For example, if you’re custom index name is My Product Index, the resulting name will be my-product-index.

The ExamineX.SiteFriendlyName setting is used to prefix the index names in your Azure Cognitive Search service. So even though the Umbraco index names are: “InternalIndex”, “ExternalIndex”, “MemberIndex”, they will show up in your Azure Cognitive Search service names prefixed with your friendly name. This also means you can use one Azure Cognitive Search Service for multiple Umbraco websites.

As an example, if your Site Friendly name is “Sam’s Adventure Site”, the 3 indexes that will be created within Azure Cognitive Search would be:

  • sam-s-adventure-site-internal
  • sam-s-adventure-site-external
  • sam-s-adventure-site-members

However, the indexes themselves within Umbraco will still be referenced by their standard names (respectively):

  • Constants.UmbracoIndexes.InternalIndexName (“InternalIndex”)
  • Constants.UmbracoIndexes.ExternalIndexName (“ExternalIndex”)
  • Constants.UmbracoIndexes.MembersIndexName (“MembersIndex”)