Make the entry points to the Search API more intuitive
Description
Activity
Show:
Fixed
Details
Details
Assignee

Reporter

Components
Sprint
None
Fix versions
Priority
Created March 5, 2019 at 2:20 PM
Updated March 21, 2019 at 5:27 PM
Resolved March 14, 2019 at 3:59 PM
There are a few problems with the current search APIs in Hibernate Search 6 that make them quite difficult to understand without reading the documentation:
FullTextQuery, FullTextEntityManager and FullTextSession extend Hibernate ORM types. As a result, they expose dozens of different methods, making it difficult to find the relevant ones, especially since a lot of them are not about Hibernate Search at all (session.persist, ...), and some of them won't even work. This makes it harder to find the
fulltextsession.search()
method in particular. Note this should be fixed as part of HSEARCH-3403.The concept of "search target" is necessary when using the "object" syntax for predicates/sorts/etc., but not really when using the lambda syntax, which is probably what we want to recommend to new users. Worse, on top of not (always) being necessary, it's confusing at first glance: after typing
fulltextsession.search( ... )
, it's a bit hard to know whether we should use.predicate()
or.query()
: both could make sense in that context.The naming of "search targets" is not crystal clear... Maybe something like "scope" would be more obvious?
The naming of API types is inconsistent: some use the "FullText" prefix, some use the "Search" prefix, with the same intended meaning ("this type is major API entry point"). If I had to pick one, I'd go with "Search", which encompasses all use cases (numeric predicates, faceting, ...), not just full-text ones.
Also making things harder to understand: the reference documentation always presents the lambda syntax (which supposedly is the more convenient syntax) as an alternative, instead of presenting it as the main syntax.