Parameter-based Automatic Queries as a full alternative to Query by Method Name

[njr-11]

The parameter-based Automatic Queries pattern already provides an alternative to much of what Query by Method Name offers for the repository author to define queries upfront, but some parts are lacking which we should address. Applications ought to be able to choose to fully utilize this pattern and not need to rely on Query by Method Name in places.

The most notable piece that is lacking is the ability to request conditions other than equality. One way to address that would be with a single Is annotation that accepts an enumerated value for the condition to apply. For example,

@Find
@OrderBy(_Product.PRICE)
@OrderBy(_Product.NAME)
@OrderBy(_Product.ID)
Page<Product> search(@By(_Product.NAME) @Is(Like) String pattern,
                     @By(_Product.PRICE) @Is(LessThan) float max,
                     PageRequest pageRequest);

The above directly corresponds to the following Query by Method Name method that could currently be used:

Page<Product> findByNameLikeAndPriceLessThanOrderByPriceAscNameAscIdAsc(String pattern,
                                                                        float max,
                                                                        PageRequest pageRequest);

Note that everything that is needed for the former is already in the Jakarta Data specification except for the mechanism for specifying the condition to be something other than equals. So the enhancement here has a direct equivalence to the Query by Method Name and achieves it with a minor addition that fits right in to an existing specification pattern.

There has been some confusion over how this differs from other new capability like Restrictions and new Special parameter types (Pattern/Range) with which the repository user can customize different types of conditions. These are two very different usage patterns. In some cases, the nature of the application involves a repository user needing the flexibility to compute different conditions at run time, such as in response to an end user defining different search conditions. But in other cases, the repository author wishes to provide specific capability and to externalize it to the repository user in the most simplistic and direct way, eliminating as much misuse and error conditions as possible.

When the repository author has a set of requirements that can be encoded into the repository method definition in advance, they ought to be able to do so, in order to abstract the complexity away from the repository user, who can then use the repository in the simplest way, without concern for complexities that the repository author has already taken care of.

A brief example of this is a repository for a library that wants to identify overdue books in order to remind the borrower to return them. The repository author might write the following method, encoding the LESS_THAN condition for the dueDate to identify overdue books, and appropriately naming the method so that the repository user knows exactly what it is for,

@Find
@OrderBy(_Book.DUE_DATE)
@OrderBy(_Book.BORROWER)
@OrderBy(_Book.TITLE)
List<Book> booksDueBefore(@Is(LESS_THAN) LocalDate dueDate);

The repository user can easily understand that they should invoke the method with today's date to find the books that are overdue,

overdueBooks = library.booksDueBefore(LocalDate.now());

If the repository author had instead written the method without encoding the LESS_THAN requirement, and instead only encoding that it needs to compare the dueDate in some way, then it might look something like this,

@Find
@OrderBy(_Book.DUE_DATE)
@OrderBy(_Book.BORROWER)
@OrderBy(_Book.TITLE)
List<Book> booksDueBefore(Range<LocalDate> dueDate);

The burden is then on the repository user to figure out what type of range to supply in order to make the method do what its name says it will do.

One right answer is that they can use Range.before, sending in the current date to make it return all past values to finds all overdue books,

overdueBooks = library.booksDueBefore(Range.before(LocalDate.now()));

The other right answer is that they can use Range.to, sending in 1 less than the current date, also making it return all past values to find all overdue books,

overdueBooks = library.booksDueBefore(Range.to(LocalDate.now().minus(Period.ofDays(1))));

There is (unwanted) flexibility to send in some other Ranges to the method, making it possible to do things that contradict what its name says it will do,

booksThatAreNotOverdue = library.booksDueBefore(Range.from(LocalDate.now()));

There are multiple problems here:

• The repository author is unable to encode/enforce the requirements that it knows it has
• The repository method is not guaranteed to do what its name says it will do, is vulnerable to mistakes, and can be misused for other purposes
• The repository user needs to stop and think extra about how to use the method in order to ensure the above
• The repository user is burdened with writing extra code, which is also more difficult to read when trying to understand the business logic of the application.

A best practice should be that the repository author always encodes in advance all of the restrictions that they know will remain constant across all usage of the method. Currently, the only ways to do that are Query by Method Name (but that pattern is discouraged and expected to go away) and Query Language (advanced users only). This issue is opened so that we have a simple recommended way for newer and non-advanced users. It should be straightforward, clear, and easily discoverable which restrictions are available.

[gavinking]

I definitely 100% understand where this proposal is coming from, and I want to emphasize that I don't hate it, but, after reflection, my preference is still for #546.

@Find
@OrderBy("price, name, id")
Page<Product> search(@By("name like ?1") String pattern,
                     @By("price < ?2") float max,
                     PageRequest pageRequest);

This option is:

1. significantly less verbose, and easier on the eyes,
2. much more flexible (it can be easily extended to accommodate more things), and
3. can be made completely typesafe.

Furthermore:

• It "unifies" @Find with @Query in a way I find elegant, whereas introducing stuff like @Is(Like) keeps them separate and in fact doubles down on the divergence.
• It's super low impact / high leverage: @By and @OrderBy already accept strings so this much of the proposal has actually zero impact on the APIs, and can be prototyped in implementations today!

We know for a fact that we're going to be able to count on IDE support for this stuff (the IntelliJ folks have been super responsive here).

[gavinking]

it can be easily extended to accommodate more things

For example, we get this for free:

@Find
Thing thing(@By("lower(code) like lower(?1)") String code`)

Whereas with @Is, I'm really not sure how you would express it.

[beikov]

Just to throw another idea into the pit, how about we introduce special value types per predicate instead of annotations?

@Find
Page<Product> search(@By(_Product.NAME) LikePattern namePattern,
                     @By(_Product.PRICE) ComparisonValue<Float> maxPrice,
                     PageRequest pageRequest);

That would also allow some runtime flexibility e.g. use a different comparison operator without having to duplicate the whole method.

[graemerocher]

I agree with @gavinking introducing overly complex annotation-based DSLs doesn't seem to be a wise direction

[gavinking]

Just to throw another idea into the pit, how about we introduce special value types per predicate instead of annotations?

@Find
Page<Product> search(@By(_Product.NAME) LikePattern namePattern,
                     @By(_Product.PRICE) ComparisonValue<Float> maxPrice,
                     PageRequest pageRequest);

That would also allow some runtime flexibility e.g. use a different comparison operator without having to duplicate the whole method.

This is a very interesting idea. I definitely think LikePattern is a really excellent alternative to @Pattern.

Nice one @beikov.

[njr-11]

Just to throw another idea into the pit, how about we introduce special value types per predicate instead of annotations?

@Find
Page<Product> search(@By(_Product.NAME) LikePattern namePattern,
                     @By(_Product.PRICE) ComparisonValue<Float> maxPrice,
                     PageRequest pageRequest);

That would also allow some runtime flexibility e.g. use a different comparison operator without having to duplicate the whole method.

@beikov - Yes, that's an interesting approach for dynamically specifying comparisons. The point of this issue was to cover static, upfront definition of the comparisons. We have a separate issue #829 that is looking into dynamic patterns and your idea should be considered there rather than under this issue.

[otaviojava]

I liked this ComparisonValue mainly because we could use it in both situations, static and also dynamic queries.

I need to go deep on this next week and open a PR to make it easier to see this.

[njr-11]

it can be easily extended to accommodate more things

For example, we get this for free:

@Find
Thing thing(@By("lower(code) like lower(?1)") String code`)

Whereas with @Is, I'm really not sure how you would express it.

It is not the goal to be able to express everything you can do in query language. That would result in an overly complex solution as is being cautioned against in some earlier comments.
Instead the goal is to cover the same sort of basic capability new users will want such as what you get from Query by Method Name, except without the need to learn and rely on special syntax and parsing of method names.

The particular capability does actually have a Query by Method Name equivalent and so it's good to bring it up. Note that the query language solution, even the reduced one you give as an example, requires knowing there is a special lower function that you can take advantage of, applying to both the supplied value and the value in the datastore within a query to achieve a case insensitive comparison. That is asking a lot of users for something so basic (case insensitive compare on a single entity attribute). The query language solution is not intuitive or easy for beginning users.

It will be more clear once I have a chance to write it up in a PR, but the Is annotation does cover this particular scenario. The enumerated values that go into the annotation value make it clear and intuitive to users exactly what is available, making it easy to choose from,

@Find
List<Thing> match(@By(_Thing.CODE) @Is(LikeIgnoreCase) String code)

There are no hard-coded strings where you can make mistakes typing things or where you don't know what is valid to put there in the first place.
There is no query language to learn.
It (will be) well-defined in the API. The enumerated values are all isolated to one place within the annotation, so it avoids cluttering the rest of the spec. This will also be a great place to put an example and description of each of the defined options.
It is conducive to autocomplete while writing code. Just pick from the available list.

I know some people have hesitations. And I think there are some misconceptions that this is going to expand into some complex model that tries to do everything query language does. That is not the point at all. It is only aiming to achieve some of the very core and basic things that Query by Method Name gives you, but in a way that is easier and more obvious (and type-safe) for beginning users.

[njr-11]

Regarding query language fragments, I do think it is a good topic to consider and explore, but has a different goal and serves a different subset of users than what this issue is proposed for. In any case, I'll aim to keep discussion of query fragments to the #546 issue that is open for that. Once we have both of these proposals more fully developed, then we can assess whether it will make sense to have both of them in the spec, just one, neither, or other ideas that come up.

[KyleAure]

Sorry just getting caught up again. Here are my 2 cents on what has been discussed so far.

Seeing as how Jakarta Query is being proposed as a new spec for Jakarta EE 12 I would be hesitant to consider implementing query fragments until we know how Jakarta Data and Query are going to interoperate.

I think the biggest issue we need to address in EE 12 is the deprecation / removal of Query by Method Name. In this case, I agree with Nathan that we need to have simple, easy to code, and easy to understand alternative. In the past, we have pushed those scenarios into the parameter-based automatic queries and left the more complex queries to JDQL. The more complex we make parameter-based automatic queries the less useful it becomes and we will force users into JDQL and increase the learning curve of Jakarta Data.

An @Is or @Does annotation seems to be a good solution IMO.