Document matchesPattern implementation in CQL (#576)

java/persistence-services.md

@@ -46,6 +46,8 @@ entity Books : cuid {
 To disable statement-wide collation for all queries, set [`cds.sql.hana.ignoreLocale`](../java/development/properties#cds-sql-hana-ignoreLocale) to `true`.
 :::
 
+4. The SAP HANA supports _Perl Compatible Regular Expressions_ (PCRE) for regular expression matching. If you need to match a string against a regular expression and are not interested in the exact number of the occurrences, consider using lazy (_ungreedy_) quantifiers in the pattern or the option `U`.
+
 ### PostgreSQL
 
 CAP Java SDK is tested on [PostgreSQL](https://www.postgresql.org/) 15 and supports most of the CAP features. Known limitations are:
@@ -65,6 +67,7 @@ CAP Java SDK is tested on [PostgreSQL](https://www.postgresql.org/) 15 and suppo
 4. Although referential and foreign key constraints are supported, H2 [doesn't support deferred checking](https://www.h2database.com/html/grammar.html#referential_action). As a consequence, schema SQL is never generated with referential constraints.
 5. In [pessimistic locking](query-execution#pessimistic-locking), _shared_ locks are not supported but an _exclusive_ lock is used instead.
 6. The CDS type `UInt8` can't be used with H2, as there is no `TINYINT`. Use `Int16` instead.
+7. For regular expressions, H2's implementation is compatible with Java's: the matching behaviour is an equivalent of the `Matcher.find()` call for the given pattern.  
 
 ::: warning
 Support for localized and temporal data via session context variables requires H2 v2.2.x or later.
@@ -85,6 +88,7 @@ CAP does support most of the major features on SQLite, although there are a few
 7. Sorting of character-based columns is never locale-specific but if any locale is specified in the context of a query then case insensitive sorting is performed.
 8. Views in SQLite are read-only. However, the CAP Java SDK supports some views to be updatable as described [here](query-execution#updatable-views).
 9. Foreign key constraints are supported, but disabled by default. To activate the feature using JDBC URL, append the `foreign_keys=on` parameter to the connection URL, for example, `url=jdbc:sqlite:file:testDb?mode=memory&foreign_keys=on`. For more information, visit the [SQLite Foreign Key Support](https://sqlite.org/foreignkeys.html) in the official documentation.
+10. CAP enables regular expressions on SQLite via a Java implementation. The matching behaviour is an equivalent of the `Matcher.find()` call for the given pattern.
 
 ## Datasources
 

java/query-api.md

@@ -1733,6 +1733,36 @@ ENDS WITH
 </tr>
 </table>
 
+#### `matchesPattern` Predicate {#matches-pattern}
+
+The `matchesPattern` predicate is applied to a String value and tests if it matches a given regular expression.
+
+The regular expressions are evaluated on the database. Therefore, the supported syntax of the regular expression and the options you can use depends on the database you are using.
+
+For example, following code matches title of the book that contains the word "CAP" in the title:
+
+```java
+Select.from("bookshop.Books").where(t -> t.get("title").matchesPattern("CAP"));
+```
+
+::: tip
+As a general rule, consider regular expressions as a last resort. They are powerful, but also complex and hard to read. For simple string operations, prefer other simpler functions like `contains`.
+::::
+
+In the following example, the title of the book must start with the letter `C` and end with the letter `e` and contains any number of letters in between: 
+
+```java
+Select.from("bookshop.Books").where(t -> t.get("title").matchesPattern("^C\w*e$"));
+```
+
+The behavior of the regular expression can be customized with the options that can be passed as a second argument of the predicate. The set of the supported options and their semantics depends on the underlying database.  
+
+For example, the following code matches that the title of the book begins with the word "CAP" while ignoring the case of the letters:
+
+```java
+Select.from("bookshop.Books").where(t -> t.get("title").matchesPattern(CQL.val("^CAP.+$"), CQL.val("i")));
+```
+
 #### `anyMatch/allMatch` Predicate {#any-match}
 
 The `anyMatch` and `allMatch` predicates are applied to an association and test if _any_ instance/_all_ instances of the associated entity set match a given filter condition. They are supported in filter conditions of [Select](#select), [Update](#update) and [Delete](#delete) statements.