Upgrading to v11
ExamineX v11 targets Umbraco 19 and the new Umbraco Search (Umbraco.Cms.Search) on .NET 11. If you’re upgrading from ExamineX v10 or earlier (Umbraco 13 - 18), read this page first. Most sites only need to update packages and rebuild their indexes.
Index names
Section titled “Index names”Umbraco Search replaces Umbraco’s Examine indexes, so update any code or configuration (DisabledIndexes, ConfigureIndex, TryGetIndex and so on) that uses the old index names:
| Umbraco 13 - 18 | Umbraco 19 | Constant |
|---|---|---|
InternalIndex |
Umb_Content |
Constants.Search.IndexAliases.DraftContent |
ExternalIndex |
Umb_PublishedContent |
Constants.Search.IndexAliases.PublishedContent |
MembersIndex |
Umb_Members |
Constants.Search.IndexAliases.DraftMembers |
DeliveryApiContentIndex |
No separate index, the Delivery API uses Umbraco Search | |
Umb_Media |
Constants.Search.IndexAliases.DraftMedia |
|
Umb_Elements |
Constants.Search.IndexAliases.DraftElements |
The indexes in your search service get new names too (for example my-site-umb-publishedcontent), see Azure AI Search index names or Elasticsearch index names. The indexes created by previous versions aren’t used, so you can delete them once you’ve upgraded.
Examine 4
Section titled “Examine 4”ExamineX now depends on Examine 4 (4.0.1) instead of Examine 3. Most queries won’t need to change, but a few Examine APIs did:
Examineness.Explicit,Examineness.EscapedandExamineness.Boostedare obsolete. If you were using.Escape()to match an exact phrase, use.Phrase()instead, e.g..Field("nodeName", "codegarden 09".Phrase()).new ExamineValue(...)is replaced byExamineValue.Create(...).- Facets are new, see Faceting for Azure or Elastic. To get facet counts a field needs to be defined with one of the
FieldDefinitionTypes.Facet*types.
See the Examine documentation for the full details.
DateTime values are treated as UTC
Section titled “DateTime values are treated as UTC”Any DateTime value with DateTimeKind.Unspecified is now treated as UTC, both when indexing and when querying (e.g. RangeQuery<DateTime>). Previously Azure Search treated these as the server’s local time and converted them to UTC, so the stored value was shifted by whatever the server’s time zone was.
DateTimeKind.Utc- used as-is (no change)DateTimeKind.Local- converted to UTC (no change to the stored value, except for date facet fields, see below)DateTimeKind.Unspecified- treated as UTC, this is the change. This includes date strings without an offset like"2024-02-01".DateTimeOffset- used as-is (no change)
This makes indexed dates independent of the server’s time zone which matters when you are load balancing across regions, or around daylight saving changes. Umbraco 19 (Umbraco Search) indexes UTC dates with an Unspecified kind, so without this change all Umbraco dates would be off by the server’s UTC offset.
If your server isn’t running in UTC and you index Unspecified dates, you’ll want to rebuild your indexes after upgrading, and check any queries that pass in local wall clock times with an Unspecified kind - either convert them to UTC or use DateTimeKind.Local.
Date-resolution facet fields (FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour, FacetDateMinute and their FacetTaxonomyDate* equivalents) are rounded down on UTC boundaries. If your server isn’t running in UTC and these fields are populated from DateTimeKind.Local values, a value near a local midnight is stored in the UTC day, month or year, which can differ from the local one. Indexes built with an earlier ExamineX version (including v11 pre-releases) have different stored boundaries, so rebuild the indexes that contain these fields after upgrading.
Any DateTime value with DateTimeKind.Unspecified is now explicitly treated as UTC, both when indexing and when querying (e.g. RangeQuery<DateTime>). DateTimeKind.Local values are converted to UTC and DateTimeKind.Utc and DateTimeOffset values are used as-is.
For Elastic Search this mostly formalizes what already happened, since Elastic Search interprets dates without an offset as UTC, so most indexed values won’t change. The difference is that dates are now always sent to Elastic Search as UTC (with a Z suffix) instead of with the server’s offset, or no offset at all. This is the same behavior as ExamineX for Azure Search, and it matches how Umbraco 19 (Umbraco Search) indexes dates.
The exception is date-resolution facet fields (FacetDateYear, FacetDateMonth, FacetDateDay, FacetDateHour, FacetDateMinute and their FacetTaxonomyDate* equivalents). These are rounded down on UTC boundaries. If your server isn’t running in UTC and these fields are populated from DateTimeKind.Local values, a value near a local midnight is stored in the UTC day, month or year, which can differ from the local one. Indexes built with an earlier ExamineX version (including v11 pre-releases) have different stored boundaries, so rebuild the indexes that contain these fields after upgrading.
Elasticsearch: NEST replaced by Elastic.Clients.Elasticsearch
Section titled “Elasticsearch: NEST replaced by Elastic.Clients.Elasticsearch”ExamineX for Elastic Search v11 now uses Elastic’s official
Elastic.Clients.Elasticsearch client
instead of the end of life NEST client. The new client talks to both Elasticsearch 8.x and 9.x servers.
If you only use ExamineX through the Examine APIs, nothing changes. If you use any of the customization APIs above, or the Elastic Search APIs directly, the following changes apply:
- Namespaces.
Nestis gone.FieldTypeis nowElastic.Clients.Elasticsearch.Mapping.FieldType, and the analyzer types (CustomAnalyzer, tokenizers, token filters) are inElastic.Clients.Elasticsearch.Analysis. ElasticSearchIndex.ServiceClientis now anElasticsearchClientinstead of anIElasticClient.CreatingOrUpdatingIndexEventArgsnow exposesRequestas anElastic.Clients.Elasticsearch.Requests.RequestandElasticClientas anElasticsearchClient. To modify the mapping, check forCreateIndexRequestorPutMappingRequestand mutateMappings.Properties/Properties.- Properties no longer know their own name.
IPropertyonly exposesType; a field’s name is thePropertyNamekey it is stored under in thePropertiesdictionary.ElasticFieldtherefore exposes a collection ofElasticFieldPropertyname/property pairs rather than named properties. For the same reasonElasticSearchFieldReferences.SearchableFieldsvalues areElasticFieldProperty(use.Propertyfor the mapping and.Namefor the field’s real name in the index), and a customIElasticSearchFieldValueType.AddValuesreceives anElasticFieldProperty. Write values underfield.Name, not your own formatted name: lookups are case insensitive so the index’s field may differ by case, and writing a differently cased name makes Elasticsearch map a duplicate field. Propertiesmust be cast to be enumerated - it implementsIDictionary<PropertyName, IProperty>explicitly.- The NEST marker interfaces are gone (
ITextProperty,IDocValuesProperty,INumberProperty, and so on). ExamineX exposesElasticPropertyExtensionswithIsAnalyzedText(),IsSearchable(),HasDocValues(),GetAnalyzer(),TrySetIndexable(), andTryGetOriginalAlias()to replace them. - Numeric properties are now distinct types. There is no
NumberProperty/NumberType; an integer field maps toIntegerNumberProperty, a double toDoubleNumberProperty, and so on. FieldTypemember changes.FieldType.Murmur3Hashis nowFieldType.Murmur3, andFieldType.Pointno longer exists. New members includeMatchOnlyText,Version,DenseVector,SparseVector,SemanticText,CountedKeyword,PassthroughandIcuCollationKeyword.- Sort order.
SortOrder.Ascending/SortOrder.Descendingare nowSortOrder.Asc/SortOrder.Desc. - Response validity.
response.IsValidis nowresponse.IsValidResponse, andresponse.OriginalExceptionis nowresponse.TryGetOriginalException(out var exception). - Serialization now uses
System.Text.Jsonrather than Utf8Json.
Azure AI Search: zero downtime rebuilds
Section titled “Azure AI Search: zero downtime rebuilds”Index rebuilds now swap an index alias, so your site keeps searching while an index rebuilds. Existing indexes are migrated the first time they are rebuilt. Each rebuild needs one spare index in your search service, see Azure Search Limits.
See also Known limitations.