Elastic Search naming restrictions

Elastic Search has some naming restrictions for index and field names. ExamineX will automatically re-format invalid names into valid names.

Typically, these rules are:

  • Lowercase only
  • Cannot include \, /, *, ?, ", <, >, |, space (the character, not the word), ,, #
  • Cannot start with -, _, +
  • Cannot be . or ..
  • Cannot be longer than 255 characters

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 Elastic Search may be different. This is handled internally by ExamineX using metadata in the fields created in Elastic Search. For example, Examine’s own naming conventions for ‘system’ fields are prefixed with double underscores like __NodeId. This field name is invalid in Elastic Search so it becomes prefixed with x and the end result is x__NodeId.

Index names

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

ExamineX will also suffix the index names with a timestamp: yyyy-MM-dd-HHmmss. This is used for rebuilding an index with zero downtime so that when searching an index while it is rebuilding, no errors occur.

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

  • sam-s-adventure-site-internal-2024-02-02-122515
  • sam-s-adventure-site-external-2024-02-02-122515
  • sam-s-adventure-site-members-2024-02-02-122515

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”)