feat: add support for regexFind and regexFindAll Pipeline expressions (#2310)

Author: dlarocque

google-cloud-firestore/src/main/java/com/google/cloud/firestore/pipeline/expressions/Expression.java

@@ -1228,6 +1228,134 @@ public static BooleanExpression regexContains(String fieldName, String pattern)
     return regexContains(field(fieldName), constant(pattern));
   }
 
+  /**
+   * Creates an expression that returns the first substring of a string expression that matches a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param string The expression representing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} representing the regular expression find function.
+   */
+  @BetaApi
+  public static Expression regexFind(Expression string, Expression pattern) {
+    return new FunctionExpression("regex_find", ImmutableList.of(string, pattern));
+  }
+
+  /**
+   * Creates an expression that returns the first substring of a string expression that matches a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param string The expression representing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} representing the regular expression find function.
+   */
+  @BetaApi
+  public static Expression regexFind(Expression string, String pattern) {
+    return regexFind(string, constant(pattern));
+  }
+
+  /**
+   * Creates an expression that returns the first substring of a string field that matches a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param fieldName The name of the field containing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} representing the regular expression find function.
+   */
+  @BetaApi
+  public static Expression regexFind(String fieldName, Expression pattern) {
+    return regexFind(field(fieldName), pattern);
+  }
+
+  /**
+   * Creates an expression that returns the first substring of a string field that matches a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param fieldName The name of the field containing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} representing the regular expression find function.
+   */
+  @BetaApi
+  public static Expression regexFind(String fieldName, String pattern) {
+    return regexFind(field(fieldName), constant(pattern));
+  }
+
+  /**
+   * Creates an expression that evaluates to a list of all substrings in a string expression that
+   * match a specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param string The expression representing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} that evaluates to a list of matched substrings.
+   */
+  @BetaApi
+  public static Expression regexFindAll(Expression string, Expression pattern) {
+    return new FunctionExpression("regex_find_all", ImmutableList.of(string, pattern));
+  }
+
+  /**
+   * Creates an expression that evaluates to a list of all substrings in a string expression that
+   * match a specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param string The expression representing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} that evaluates to a list of matched substrings.
+   */
+  @BetaApi
+  public static Expression regexFindAll(Expression string, String pattern) {
+    return regexFindAll(string, constant(pattern));
+  }
+
+  /**
+   * Creates an expression that evaluates to a list of all substrings in a string field that match a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param fieldName The name of the field containing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} that evaluates to a list of matched substrings.
+   */
+  @BetaApi
+  public static Expression regexFindAll(String fieldName, Expression pattern) {
+    return regexFindAll(field(fieldName), pattern);
+  }
+
+  /**
+   * Creates an expression that evaluates to a list of all substrings in a string field that match a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param fieldName The name of the field containing the string to search.
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} that evaluates to a list of matched substrings.
+   */
+  @BetaApi
+  public static Expression regexFindAll(String fieldName, String pattern) {
+    return regexFindAll(field(fieldName), constant(pattern));
+  }
+
   /**
    * Creates an expression that checks if a string field matches a specified regular expression.
    *
@@ -3872,6 +4000,36 @@ public final BooleanExpression regexContains(Object pattern) {
     return regexContains(this, toExprOrConstant(pattern));
   }
 
+  /**
+   * Creates an expression that returns the first substring of a string expression that matches a
+   * specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} representing the regular expression find function.
+   */
+  @BetaApi
+  public final Expression regexFind(Object pattern) {
+    return regexFind(this, toExprOrConstant(pattern));
+  }
+
+  /**
+   * Creates an expression that evaluates to a list of all substrings in a string expression that
+   * match a specified regular expression.
+   *
+   * <p>This expression uses the [RE2](https://github.com/google/re2/wiki/Syntax) regular expression
+   * syntax.
+   *
+   * @param pattern The regular expression to search for.
+   * @return A new {@link Expression} that evaluates to a list of matched substrings.
+   */
+  @BetaApi
+  public final Expression regexFindAll(Object pattern) {
+    return regexFindAll(this, toExprOrConstant(pattern));
+  }
+
   /**
    * Creates an expression that checks if this string expression matches a specified regular
    * expression.

google-cloud-firestore/src/test/java/com/google/cloud/firestore/it/ITPipelineTest.java

@@ -1046,6 +1046,56 @@ public void testRegexContains() throws Exception {
     assertThat(data(results)).hasSize(5);
   }
 
+  @Test
+  public void testRegexFind() throws Exception {
+    assumeFalse(
+        "Regexes are not supported against the emulator",
+        isRunningAgainstFirestoreEmulator(firestore));
+
+    List<PipelineResult> results =
+        firestore
+            .pipeline()
+            .createFrom(collection)
+            .select(field("title").regexFind("^\\w+").as("firstWordInTitle"))
+            .sort(field("firstWordInTitle").ascending())
+            .limit(3)
+            .execute()
+            .get()
+            .getResults();
+
+    assertThat(data(results))
+        .isEqualTo(
+            Lists.newArrayList(
+                map("firstWordInTitle", "1984"),
+                map("firstWordInTitle", "Crime"),
+                map("firstWordInTitle", "Dune")));
+  }
+
+  @Test
+  public void testRegexFindAll() throws Exception {
+    assumeFalse(
+        "Regexes are not supported against the emulator",
+        isRunningAgainstFirestoreEmulator(firestore));
+
+    List<PipelineResult> results =
+        firestore
+            .pipeline()
+            .createFrom(collection)
+            .select(field("title").regexFindAll("\\w+").as("wordsInTitle"))
+            .sort(field("wordsInTitle").ascending())
+            .limit(3)
+            .execute()
+            .get()
+            .getResults();
+
+    assertThat(data(results))
+        .isEqualTo(
+            Lists.newArrayList(
+                map("wordsInTitle", Lists.newArrayList("1984")),
+                map("wordsInTitle", Lists.newArrayList("Crime", "and", "Punishment")),
+                map("wordsInTitle", Lists.newArrayList("Dune"))));
+  }
+
   @Test
   public void testRegexMatches() throws Exception {
     assumeFalse(

samples/preview-snippets/src/main/java/com/example/firestore/PipelineSnippets.java

@@ -1257,6 +1257,32 @@ void regexContainsFunction() throws ExecutionException, InterruptedException {
     System.out.println(result.getResults());
   }
 
+  void regexFindFunction() throws ExecutionException, InterruptedException {
+    // [START regex_find]
+    Pipeline.Snapshot result =
+        firestore
+            .pipeline()
+            .collection("documents")
+            .select(regexFind(field("email"), "@[A-Za-z0-9.-]+").as("domain"))
+            .execute()
+            .get();
+    // [END regex_find]
+    System.out.println(result.getResults());
+  }
+
+  void regexFindAllFunction() throws ExecutionException, InterruptedException {
+    // [START regex_find_all]
+    Pipeline.Snapshot result =
+        firestore
+            .pipeline()
+            .collection("documents")
+            .select(regexFindAll(field("comment"), "@[A-Za-z0-9_]+").as("mentions"))
+            .execute()
+            .get();
+    // [END regex_find_all]
+    System.out.println(result.getResults());
+  }
+
   void regexMatchFunction() throws ExecutionException, InterruptedException {
     // [START regex_match]
     Pipeline.Snapshot result =