include::{commons}@data-commons::query-by-example.adoc[]

Here's an example:

[source,java,indent=0]
----
include::example$r2dbc/QueryByExampleTests.java[tag=example]
----

<1> Create a domain object with the criteria (`null` fields will be ignored).
<2> Using the domain object, create an `Example`.
<3> Through the repository, execute query (use `findOne` for a single item).

This illustrates how to craft a simple probe using a domain object.
In this case, it will query based on the `Employee` object's `name` field being equal to `Frodo`.
`null` fields are ignored.

[source,java,indent=0]
----
include::example$r2dbc/QueryByExampleTests.java[tag=example-2]
----

<1> Create a custom `ExampleMatcher` that matches on ALL fields (use `matchingAny()` to match on *ANY* fields)
<2> For the `name` field, use a wildcard that matches against the end of the field
<3> Match columns against `null` (don't forget that `NULL` doesn't equal `NULL` in relational databases).
<4> Ignore the `role` field when forming the query.
<5> Plug the custom `ExampleMatcher` into the probe.

It's also possible to apply a `withTransform()` against any property, allowing you to transform a property before forming the query.
For example, you can apply a `toUpperCase()` to a `String` -based property before the query is created.

Query By Example really shines when you don't know all the fields needed in a query in advance.
If you were building a filter on a web page where the user can pick the fields, Query By Example is a great way to flexibly capture that into an efficient query.
