More explicit documentation of query prefix behavior [DATACMNS-1833]

[spring-projects-issues]

M. Justin opened DATACMNS-1833 and commented

This is a direct follow-up to DATACMNS-1100, and with exactly the same use case. That issue was closed due to lack of feedback with the conclusion that the docs seem to be sufficient. However, it is very non-obvious (to me) from just the documentation that arbitrary query prefixes are supported (assuming they don't happen to match specific supported keywords, such as "Distinct").

The mechanism strips the find...By, read...By, query...By, count...By, and get...By prefixes from the method and starts parsing the rest of it. The introducing clause can contain further expressions, such as a Distinct to set a distinct flag on the query to be created. However, the first By acts as a delimiter to indicate the start of the actual criteria.

This tells me that the initial part is stripped, and that it can include the "Distinct" expression. However, it does not tell me what happens if arbitrary text is included in there, nor does it make it clear that such arbitrary text is in fact intended to be allowed and is an acceptable usage. The only thing that implies this that I see is the example, and it's not explicitly spelled out there either:

  // Enables the distinct flag for the query
  List<Person> findDistinctPeopleByLastnameOrFirstname(String lastname, String firstname);
  List<Person> findPeopleDistinctByLastnameOrFirstname(String lastname, String firstname);```

A close reading shows that "People" is in the method name, though it doesn't spell out how it works or is intended to be used.

Ultimately, what I'd like to see is the documentation spell out that arbitrary prefixes are allowed (assuming they don't match prefix keywords such as "Distinct"), what purpose they are intended to serve, and what idiomatic usage of this feature looks like.

(Side notes: what is the behavior if the prefix contains a non-camelcase "By", e.g. findByzantineValue? Is there documentation of the full list of prefix expressions such as "Distinct" that have special meaning, and thus are disallowed as descriptive text, and does this vary by data store type?)

---

Referenced from: pull request #477

Backported to: 2.4.2 (2020.0.2), 2.3.6 (Neumann SR6)

[spring-projects-issues]

Mark Paluch commented

However, it does not tell me what happens if arbitrary text is included in there, nor does it make it clear that such arbitrary text is in fact intended to be allowed and is an acceptable usage

How would you improve the following:

The mechanism strips the … prefixes from the method and starts parsing the rest of it

?

It pretty much expresses that it removes the find…By meaning that this part isn't considered for the actual query. In the next sentence, we say:

The introducing clause can contain further expressions, such as a Distinct to set a distinct flag on the query to be created

We could be more precise and explain Distinct better and link to the section where First|Top is explained

[spring-projects-issues]

M. Justin commented

Maybe something like this: "In addition to these specific prefix expressions, the introducing clause can contain arbitrary words which have no effect on the query, but may serve to make the method name more expressive."

The query builder mechanism built into the Spring Data repository infrastructure is useful for building constraining queries over entities of the repository. The mechanism strips the find…By, read…By, query…By, count…By, and get…By prefixes from the method and starts parsing the rest of it. The introducing clause can contain further expressions, such as a Distinct to set a distinct flag on the query to be created. In addition to these specific prefix expressions, the introducing clause can contain arbitrary words which have no effect on the query, but may serve to make the method name more expressive. The first By acts as a delimiter to indicate the start of the actual criteria. At a very basic level, you can define conditions on entity properties and concatenate them with And and Or. The following example shows how to create a number of queries:

I do think explaining Distinct better as well as listing the other defined prefix expressions (First|Top) would be beneficial, since a user must not use them in their descriptive text, as it changes the results of the query

[spring-projects-issues]

Mark Paluch commented

We've updated the docs including the appendix