Skip to content
ExamineX
These docs are for ExamineX 11 · Umbraco 19 (pre-release). For the current release see ExamineX 6–10 · Umbraco 13–18.

Index and field names

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

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.

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 Elasticsearch service, so you can use one Elasticsearch service for multiple Umbraco websites. Umbraco Search creates these indexes, and you reference them in your code by these names:

  • Umb_Content (Constants.Search.IndexAliases.DraftContent)
  • Umb_PublishedContent (Constants.Search.IndexAliases.PublishedContent)
  • Umb_Media (Constants.Search.IndexAliases.DraftMedia)
  • Umb_Members (Constants.Search.IndexAliases.DraftMembers)
  • Umb_Elements (Constants.Search.IndexAliases.DraftElements)

ExamineX also suffixes the index names with a timestamp: yyyy-MM-dd-HHmmss. The index name without the timestamp is an alias that points to the current index. As an example, if your Site Friendly name is “Sam’s Adventure Site”, the indexes in your Elasticsearch service would be:

  • sam-s-adventure-site-umb-content-2024-02-02-122515
  • sam-s-adventure-site-umb-publishedcontent-2024-02-02-122515
  • sam-s-adventure-site-umb-media-2024-02-02-122515
  • sam-s-adventure-site-umb-members-2024-02-02-122515
  • sam-s-adventure-site-umb-elements-2024-02-02-122515

When Umbraco Search rebuilds an index (or when rebuilding within IExamineXIndex.BeginRebuild() and IExamineXIndex.CompleteRebuild()), ExamineX creates a new timestamped index and searches keep using the current index until the new one is fully populated. Only then is the alias swapped to the new index, and the previous index is deleted. Zero downtime rebuilds are built into ExamineX, so Umbraco’s own Umbraco:CMS:Search:Examine:ZeroDowntimeIndexing setting isn’t needed: if it’s enabled, ExamineX turns it off (and logs a warning) and uses its own instead.