So, I've started migrating our production environment to HSearch 5 at long last. Some of the initial pains that may warrant some documentation love: * @IndexedEmbedded basically inverts the default because before HSearch 5, the default was essentially: @IndexedEmbedded(includeEmbeddedObjectId=true), whereas now it's essentially: @IndexedEmbedded(includeEmbeddedObjectId=false). Inverting defaults seems like a dangerous upgrade choice to me. * I use a lot of indexedEmbedded(includePaths="id") style includes. public class MyClass{ @Id @GeneratedValue(strategy = GenerationType.AUTO) @Column(name="userId", nullable=false, insertable=false, updatable=false) @DocumentId public Long getId() { return id; } } I always queried these as follows: qb.keyword().onField("id").matching(myLongId).createQuery() where the Long would implicitly converted to a String. and the term query would be +id:1 Now, it becomes a NumericRangeQuery based on the fact that I'm passing a Long. But DocumentIds apparently are still strings by default. And this query will fail to deliver results. It makes most sense to me to convert DocumentId to NumericFields and adding @NumericField to it seems to fix it, but I'm not sure if this could create problems in other areas since this is the documentId. Anyway, this is undocumented. * The way to access a MutableSearchFactory has changed and is not documented. This is more of an edge case That's it for now. Cheers, Marc