Merge pull request #943 from jakartaee/update-documentation-nosql

Update the spec to fix the issue 782

Author: otaviojava

spec/src/main/asciidoc/method-query.asciidoc

@@ -108,6 +108,16 @@ Absence of an operator implies the equality condition.
 
 The conditions belonging to the restriction determine the parameters of the method, as specified below in <<Query by Method Name Conditions>>.
 
+[WARNING]
+====
+When using NoSQL databases, the support for restrictions varies depending on the database type:
+
+- **Key-Value Databases**: Support for the equals restriction is required for the `Id` attribute. There is no requirement to support other types of restrictions, the `And` and `Or` keywords, or restrictions on other entity attributes. Queries in key-value databases are typically limited to operations using the `Id` attribute only.
+- **Wide-Column Databases**: Wide-column databases must support the `AND` operator but are not required to support the `Or` operator. Restrictions must be supported for the key attribute that is annotated with `jakarta.nosql.Id`. Support for restrictions on other attributes is not required. Typically they can be used if they are indexed as secondary indexes, although support varies by database provider.
+- **Graph and Document Databases**: The `And` and `Or` keywords and all of the restrictions described in this section must be supported. Precedence between `And` and `Or` operators is not guaranteed and may vary significantly based on the NoSQL provider.
+
+====
+
 === Orders
 
 A `find` query may have an _order_. The _order_ specifies how records must be sorted. It is formed by concatenating `OrderBy` with one or more ordered pairs of an entity attribute name and a direction of sorting, `Asc` or `Desc`. The direction may be omitted if there is only one entity attribute, in which case `Asc` is implied.
@@ -116,6 +126,25 @@ The order is lexicographic, that is, ordered pairs occurring earlier take preced
 
 If no order is specified, the records are not sorted.
 
+[WARNING]
+====
+When using NoSQL databases, sorting support varies by database type:
+
+- **Key-Value Databases**: Support for sorting of results is not required.
+
+- **Wide-Column Databases**: Support for sorting of results is not required. In general, sorting is not natively supported. When sorting is available, it is typically limited to:
+  * The key attribute, defined by an annotation such as `jakarta.nosql.Id`.
+  * Fields that are indexed as secondary indexes.
+
+- **Graph and Document Databases**: Support for sorting by a single entity attribute is required. Support for compound sorting (sorting by multiple entity attributes) is not required and may vary due to:
+  * Potential instability with tied values, where sorting for equivalent values may differ across queries.
+  * Schema flexibility and mixed data types.
+  * Dependence on indexes and internal storage order, requiring proper indexing to ensure predictable sorting.
+  * The distributed nature of sharded clusters, where sorting across shards may introduce additional complexity.
+
+====
+
+
 === Example query methods
 
 The following table displays some examples of legal method signatures.
@@ -334,6 +363,24 @@ List<Product> findByNameLikeAndYearMadeBetweenAndPriceLessThan(String namePatter
                                                                Order<Product> sortBy)
 ----
 
+[WARNING]
+====
+When using NoSQL databases, support for the listed method conditions may vary significantly:
+
+- **Textual Conditions**: The `Contains`, `EndsWith`, `IgnoreCase`, `Like`, and `StartsWith` restrictions depend on text processing capabilities and are not required to be supported by Key-Value, Wide-Column, Document and Graph databases. The ability to handle these operations varies widely and depends on the database's support for text-based queries.
+
+- **Null Conditions**: The handling of `Null` values differs across NoSQL databases. In schemaless databases, a field's absence is often treated as non-existent rather than `Null`. This distinction can affect query behavior because some databases might not support `Null` checks or might interpret them differently. This specification does not make any requirements on how `Null` and non-existent fields are handled for Key-Value, Wide-Column, Document and Graph databases.
+
+- **Key-Value Databases**: Support is required for the `=` (equals) restriction when the attribute is the key. The key attribute is defined by `jakarta.nosql.Id`.
+
+- **Wide-Column Databases**: Support for restrictions on attributes other than the `Id` attribute is not required. Some databases might allow support for restrictions on other entity attributes if a secondary index is configured. Handling of `Null` values is not required to be supported and might vary in behavior because some wide-column stores might treat missing columns as `Null`, while others might not store the column at all.
+
+- **Document and Graph Databases**: These databases are generally more feature-rich. Support for the `Contains`, `EndsWith`, `IgnoreCase`, `Like`, and `StartsWith` restrictions is not required. Similarly, `Null` values are not required to be supported. Handling of `Null` in these databases may vary, especially when dealing with omitted fields versus explicitly set `Null` values.
+
+Developers are encouraged to consult the documentation of their chosen NoSQL database provider to confirm the supported operations and clarify the behavior of `Null` versus non-existent fields.
+====
+
+
 === Return Types
 
 The return type of a Query by Method Name is determined as indicated in the following table, where `E` is the queried entity type.
@@ -352,6 +399,17 @@ The return type of a Query by Method Name is determined as indicated in the foll
 | `find` accepting a `PageRequest` | `Page<E>` or `CursoredPage<E>` | For use with pagination
 |===
 
+[WARNING]
+====
+When working with NoSQL databases, the `count` operation might not be supported, depending on the database structure and capabilities:
+
+- **Key-Value Databases**: Support for count is not required. The majority of Key-Value databases do not support counting. Their design focuses on retrieving values by keys rather than aggregating data.
+
+- **Wide-Column Databases**: Support for count is not required. For databases that are capable of returning a count, it might require additional configuration, such as enabling secondary indexes or performing costly full table scans, which can affect performance.
+- **Graph and Document Databases**: Support for count is required. Performance might vary based on factors like indexing and query complexity.
+
+====
+
 
 === Persistent Attribute Names in Query by Method Name
 

spec/src/main/asciidoc/query-language.asciidoc

@@ -51,6 +51,22 @@ The character sequences `+`, `-`, `*`, `/`, `||`, `=`, `<`, `>`, `<>`, `&lt;=`,
 
 The characters `(`, `)`, and `,` are _punctuation characters_.
 
+[WARNING]
+====
+When working with NoSQL databases, the support for arithmetic operations and support of parentheses for precedence might vary significantly:
+
+- **Key-Value Databases**: Arithmetic operations (`+`, `-`, `*`, `/`) are not supported. These databases are designed for simple key-based lookups and lack query capabilities for complex operations.
+
+- **Wide-Column Databases**: Arithmetic operations are not required to be supported. Some wide-column databases might offer limited support, which might require secondary indexing even for basic querying.
+
+- **Document Databases**: Support of arithmetic operations and support of parenthesis for precedence are not required, although databases typically offer these capabilities. Behavior and extent of support can vary significantly between providers.
+
+- **Graph Databases**: Support for arithmetic operations and parentheses for precedence are not required but is typically offered by databases. Behavior and extent of support can vary significantly between providers.
+
+Due to the diversity of NoSQL database types and their querying capabilities, there is no guarantee that all NoSQL providers will support punctuation characters such as parentheses `(`, `)` for defining operation precedence. It is recommended to consult your NoSQL provider's documentation to confirm the supported query features and their behavior.
+====
+
+
 ==== String literals
 
 A _literal string_ is a character sequence quoted using the character `'`.
@@ -279,6 +295,17 @@ The operands of an equality or inequality operator must have the same type.
 
 NOTE: Portability is maximized when Jakarta Data providers interpret equality and inequality operators in a manner consistent with the implementation of `Object.equals()` or `Comparable.compareTo()` for the assigned Java type.
 
+[WARNING]
+====
+When using NoSQL databases, there are limitations to the support of equality and inequality operators:
+
+1. **Key-Value Databases**: Support for the equality restriction on the key attribute is required. The key attribute is defined by the annotation `jakarta.nosql.Id`. Key-value databases are not required to support any other restrictions.
+
+2. **Wide-Column Databases**: Support for equality restriction and the inequality restriction on the `Id` attribute is required. Support for restrictions on other entity attributes is not required. These operations typically work only with the `Id` by default but might be compatible for other entity attributes if secondary indexes are configured in the database schema.
+
+3. **Graph and Document Databases**: Support for all equality and inequality operators is required.
+====
+
 ==== Ordering
 
 Every <<Basic Types,basic type>> can, in principle, be equipped with a total order. An order for a type determines the result of inequality comparisons, and the effect of the <<Order clause>>.
@@ -297,6 +324,25 @@ For other types, there is at least some freedom in the choice of order. Usually,
 
 - This specification does not define an order for UUID values, which is provider-dependent.
 
+[WARNING]
+====
+When using NoSQL databases, sorting support varies by database type:
+
+- **Key-Value Databases**: Sorting of results is not supported.
+
+- **Wide-Column Databases**: Support for sorting of results is not required. In general, sorting is not natively supported. When sorting is available, it is typically limited to:
+  * The key attribute, defined by an annotation such as `jakarta.nosql.Id`.
+  * Fields that are indexed as secondary indexes.
+
+- **Graph and Document Databases**: Support for sorting by a single entity attribute is required. Support for compound sorting (sorting by multiple entity attributes) is not required and may vary due to:
+  * Potential instability with tied values, where sorting for equivalent values may differ across queries.
+  * Schema flexibility and mixed data types.
+  * Dependence on indexes and internal storage order, requiring proper indexing to ensure predictable sorting.
+  * The distributed nature of sharded clusters, where sorting across shards may introduce additional complexity.
+
+====
+
+
 ==== Logical operators
 
 The logical operators are `and`, `or`, and `not`.
@@ -311,6 +357,17 @@ CAUTION: A compliant implementation of JDQL might feature SQL/JPQL-style ternary
 
 Syntactically, logical operators are parsed with lower precedence than <<Equality and inequality operators,equality and inequality operators>> and other <<Conditional expressions,conditional expressions listed above>>. The `not` operator has higher precedence than `and` and `or`. The `and` operator has higher precedence than `or`.
 
+[WARNING]
+====
+When using NoSQL databases, the support for restrictions varies depending on the database type:
+
+- **Key-Value Databases**: Support for the equality restriction is required for the `Id` attribute. There is no requirement to support other types of restrictions or restrictions on other entity attributes.
+- **Wide-Column Databases**: Wide-column databases are not required to support the `AND` operator or the `OR` operator. Restrictions must be supported for the key attribute that is annotated with `jakarta.nosql.Id`. Support for restrictions on other attributes is not required. Typically they can be used if they are indexed as secondary indexes, although support varies by database provider.
+- **Graph and Document Databases**: The `AND` and `OR` operators and all of the restrictions described in this section must be supported. Precedence between `AND` and `OR` operators is not guaranteed and may vary significantly based on the NoSQL provider.
+
+====
+
+
 === Clauses
 
 Each JDQL statement is built from a sequence of _clauses_. The beginning of a clause is identified by a keyword: `from`, `where`, `select`, `set`, or `order`.
@@ -371,6 +428,22 @@ If the JDQL implementation does not support `count(this)`, it must throw `Unsupp
 
 The `select` clause is optional in `select` statements. When it is missing, the query returns the queried entity.
 
+[WARNING]
+====
+When working with NoSQL databases, the `select` clause behavior may vary depending on the database structure and capabilities:
+
+- **Key-Value Databases**: These databases generally do not support `select` clauses beyond retrieving values by their keys. Support for complex path expressions and aggregate functions like `count(this)` is not required.
+
+- **Wide-Column Databases**: The ability to use a `select` clause may depend on the presence of secondary indexes. Without secondary indexes, selection is often restricted to key-based operations. Support for `count(this)` is not required.
+
+- **Graph and Document Databases**: Support for flexible `select` clauses, including path expressions and aggregate functions like `count(this)` is required. Performance might vary based on the size and indexing of the dataset.
+
+For `count(this)` in particular, if the NoSQL datastore does not natively support counting query results, the Jakarta Data provider is encouraged to implement this operation in Java. However, providers are not required to do so. If `count(this)` is unsupported, an `UnsupportedOperationException` must be thrown during query execution, or repository methods using this expression may be rejected at compilation time.
+
+It is advisable to review your NoSQL provider's documentation to confirm the support and performance implications of `select` clauses and aggregate functions in your queries.
+====
+
+
 ==== Set clause
 
 The `set` clause, with syntax given by `set_clause`, specifies a list of updates to attributes of the queried entity. For each record which satisfies the restriction imposed by the `where` clause, and for each element of the list, the scalar expression is evaluated and assigned to the entity attribute identified by the path expression.