Make the entry points to the Search API more intuitive

Description

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:

  1. 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.

  2. 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.

  3. The naming of "search targets" is not crystal clear... Maybe something like "scope" would be more obvious?

  4. 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.

Activity

Show:
Fixed

Details

Assignee

Reporter

Components

Sprint

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