FMWK-316 Improve querying documentation

src/main/asciidoc/index.adoc

@@ -32,7 +32,13 @@ include::reference/aerospike-reactive-repositories.adoc[]
 include::spring-data-commons-docs/repository-projections.adoc[]
 include::reference/aerospike-projections.adoc[]
 include::spring-data-commons-docs/query-by-example.adoc[]
-include::reference/query-methods.adoc[]
+include::reference/query-methods-preface.adoc[]
+include::reference/query-methods-simple-property.adoc[]
+include::reference/query-methods-collection.adoc[]
+include::reference/query-methods-map.adoc[]
+include::reference/query-methods-pojo.adoc[]
+include::reference/query-methods-id.adoc[]
+include::reference/query-methods-modification.adoc[]
 include::spring-data-commons-docs/object-mapping.adoc[]
 include::reference/aerospike-object-mapping.adoc[]
 include::reference/template.adoc[]

src/main/asciidoc/reference/query-methods-collection.adoc

@@ -0,0 +1,125 @@
+[[aerospike.query_methods.collection]]
+= Collection Repository Queries
+
+[width="100%",cols="<7%,<30%,<25%",options="header",]
+|===
+|Keyword |Repository query sample |Snippet
+
+|Is, Equals
+
+or no keyword a|
+[source,java]
+----
+findByStringList(Collection<String> stringList)
+----
+|...where x.stringList = ?
+
+|Not, IsNot a|
+[source,java]
+----
+findByStringListNot(Collection<String> stringList)
+----
+|...where x.stringList <> ?
+
+|In a|
+[source,java]
+----
+findByStringListIn(Collection<Collection<String>>)
+----
+|...where x.stringList in ?
+
+|Not In a|
+[source,java]
+----
+findByStringListNotIn(Collection<Collection<String>>)
+----
+|...where x.stringList not in ?
+
+|Null, IsNull a|
+[source,java]
+----
+findByStringListIsNull()
+----
+
+|...where x.stringList = null or x.stringList does not exist
+
+|Exists
+
+NotNull, IsNotNull a|
+[source,java]
+----
+findByStringListExists()
+----
+
+[source,java]
+----
+findByStringListNotNull()
+----
+
+|...where x.stringList != null
+
+("Exists" and "IsNotNull" represent the same functionality and can be used interchangeably, objects and fields exist when their value is not equal to null)
+
+|LessThan, IsLessThan a|
+[source,java]
+----
+findByStringListLessThan(Collection<String> stringList)
+----
+|...where x.stringList < ?
+
+|LessThanEqual, IsLessThanEqual a|
+[source,java]
+----
+findByStringListLessThanEqual(Collection<String> stringList)
+----
+|...where x.stringList <= ?
+
+|GreaterThan, IsGreaterThan a|
+[source,java]
+----
+findByStringListGreaterThan(Collection<String> stringList)
+----
+|...where x.stringList > ?
+
+|GreaterThanEqual, IsGreaterThanEqual a|
+[source,java]
+----
+findByStringListGreaterThanEqual(Collection<String> stringList)
+----
+|...where x.stringList >= ?
+
+|Between, IsBetween a|
+[source,java]
+----
+findByStringListBetween(Collection<String> lowerLimit, Collection<String> upperLimit)
+----
+|...where x.stringList between ? and ?
+
+|Containing, IsContaining, Contains a|
+[source,java]
+----
+findByStringListContaining(String string)
+----
+|...where x.stringList contains ?
+
+|NotContaining, IsNotContaining, NotContains a|
+[source,java]
+----
+findByStringListNotContaining(String string)
+----
+|...where x.stringList not contains ?
+
+|And a|
+[source,java]
+----
+findByStringListAndIntList(Collection<String> stringList, Collection<Integer> intList)
+----
+|...where x.stringList = ? and x.intList = ?
+
+|Or a|
+[source,java]
+----
+findByStringListOrIntList(Collection<String> stringList, Collection<Integer> intList)
+----
+|...where x.stringList = ? or x.intList = ?
+|===

src/main/asciidoc/reference/query-methods-id.adoc

@@ -0,0 +1,21 @@
+[[aerospike.query_methods.id]]
+= Id Repository Queries
+
+[width="100%",cols="<7%,<30%,<25%",options="header",]
+|===
+|Keyword |Repository query sample |Snippet
+
+|no keyword a|
+[source,java]
+----
+findById(String id)
+----
+|...where x.PK = ?
+
+|And a|
+[source,java]
+----
+findByIdAndFirstName(String id, String firstName)
+----
+|...where x.PK = ? and x.firstName = ?
+|===

src/main/asciidoc/reference/query-methods-map.adoc

@@ -0,0 +1,125 @@
+[[aerospike.query_methods.map]]
+= Map Repository Queries
+
+[width="100%",cols="<7%,<30%,<25%",options="header",]
+|===
+|Keyword |Repository query sample |Snippet
+
+|Is, Equals
+
+or no keyword a|
+[source,java]
+----
+findByStringMap(Map<String, String> stringMap)
+----
+|...where x.stringMap = ?
+
+|Not, IsNot a|
+[source,java]
+----
+findByStringMapNot(Map<String, String> stringMap)
+----
+|...where x.stringMap <> ?
+
+|In a|
+[source,java]
+----
+findByStringMapIn(Collection<Map<String, String>>)
+----
+|...where x.stringMap in ?
+
+|Not In a|
+[source,java]
+----
+findByStringMapNotIn(Collection<Map<String, String>>)
+----
+|...where x.stringMap not in ?
+
+|Null, IsNull a|
+[source,java]
+----
+findByStringMapIsNull()
+----
+
+|...where x.stringMap = null or x.stringMap does not exist
+
+|Exists
+
+NotNull, IsNotNull a|
+[source,java]
+----
+findByStringMapExists()
+----
+
+[source,java]
+----
+findByStringMapNotNull()
+----
+
+|...where x.stringMap != null
+
+("Exists" and "IsNotNull" represent the same functionality and can be used interchangeably, objects and fields exist when their value is not equal to null)
+
+|LessThan, IsLessThan a|
+[source,java]
+----
+findByStringMapLessThan(Map<String, String> stringMap)
+----
+|...where x.stringMap < ?
+
+|LessThanEqual, IsLessThanEqual a|
+[source,java]
+----
+findByStringMapLessThanEqual(Map<String, String> stringMap)
+----
+|...where x.stringMap <= ?
+
+|GreaterThan, IsGreaterThan a|
+[source,java]
+----
+findByStringMapGreaterThan(Map<String, String> stringMap)
+----
+|...where x.stringMap > ?
+
+|GreaterThanEqual, IsGreaterThanEqual a|
+[source,java]
+----
+findByStringMapGreaterThanEqual(Map<String, String> stringMap)
+----
+|...where x.stringMap >= ?
+
+|Between, IsBetween a|
+[source,java]
+----
+findByStringMapBetween(Map<String, String> lowerLimit, Map<String, String> upperLimit)
+----
+|...where x.stringMap between ? and ?
+
+|Containing, IsContaining, Contains a|
+[source,java]
+----
+findByStringMapContaining(AerospikeQueryCriterion criterion, String string)
+----
+|...where x.stringMap contains ?
+
+|NotContaining, IsNotContaining, NotContains a|
+[source,java]
+----
+findByStringNameNotContaining(AerospikeQueryCriterion criterion, String string)
+----
+|...where x.stringMap not contains ?
+
+|And a|
+[source,java]
+----
+findByStringMapAndIntMap(Map<String, String> stringMap, Map<Integer, Integer> intMap)
+----
+|...where x.stringMap = ? and x.intMap = ?
+
+|Or a|
+[source,java]
+----
+findByStringMapOrIntMap(Map<String, String> stringMap, Map<Integer, Integer> intList)
+----
+|...where x.stringMap = ? or x.intMap = ?
+|===

src/main/asciidoc/reference/query-methods-modification.adoc

@@ -0,0 +1,68 @@
+= Query Modification
+
+== Query Modifiers
+
+[width="100%",cols="<12%,<25%,<30%",options="header",]
+|===
+|Keyword |Sample |Snippet
+
+|IgnoreCase |findByLastNameIgnoreCase |...where UPPER(x.lastName) = UPPER(?)
+
+|OrderBy |findByLastNameOrderByFirstNameDesc |...where x.lastName = ? order by x.firstName desc
+|===
+
+== Limiting Query Results
+
+[width="100%",cols="<12%,<25%,<30%",options="header",]
+|===
+|Keyword |Sample |Snippet
+|First |findFirstByAge | select top 1 where x.age = ?
+
+|First N |findFirst3ByAge | select top 3  where x.age = ?
+
+|Top |findTopByLastNameStartingWith | select top 1 where x.lastName like 'abc%' = ?
+
+|Top N |findTop4ByLastNameStartingWith | select top 4  where x.lastName like 'abc%'
+
+|Distinct | findDistinctByFirstNameContaining | select distinct ... where x.firstName like 'abc%'
+|===
+
+[[find-using-query]]
+== Find Using Query
+
+User can perform a custom `Query` for finding matching entities in the Aerospike database.
+A `Query` can be created using a `Qualifier` which represents an expression.
+It may contain other qualifiers and combine them using either `AND` or `OR`.
+
+`Qualifier` can be created for regular bins, metadata and ids (primary keys).
+Below is an example of different variations:
+
+[source,java]
+----
+    // creating an expression "firsName is equal to John"
+    Qualifier firstNameEqJohn = Qualifier.builder()
+        .setField("firstName")
+        .setFilterOperation(FilterOperation.EQ)
+        .setValue1(Value.get("John"))
+        .build();
+    result = repository.findUsingQuery(new Query(firstNameEqJohn));
+    assertThat(result).containsOnly(john);
+
+    // creating an expression "primary key is equal to person's id"
+    Qualifier keyEqJohnsId = Qualifier.idEquals(john.getId());
+    result = repository.findUsingQuery(new Query(keyEqJohnsId));
+    assertThat(result).containsOnly(john);
+
+    // creating an expression "since_update_time metadata value is less than 50 seconds"
+    Qualifier sinceUpdateTimeLt50Seconds = Qualifier.metadataBuilder()
+        .setMetadataField(SINCE_UPDATE_TIME)
+        .setFilterOperation(FilterOperation.LT)
+        .setValue1AsObj(50000L)
+        .build();
+    result = repository.findUsingQuery(new Query(sinceUpdateTimeLt50Seconds));
+    assertThat(result).contains(john);
+
+    // expressions are combined using AND
+    result = repository.findUsingQuery(new Query(Qualifier.and(firstNameEqJohn, keyEqJohnsId, sinceUpdateTimeLt50Seconds)));
+    assertThat(result).containsOnly(john);
+----