Implemented Postgres-specific array Criteria operations

spring-data-relational/src/main/java/org/springframework/data/relational/core/dialect/OracleDialect.java

@@ -28,7 +28,7 @@
  * An SQL dialect for Oracle.
  *
  * @author Jens Schauder
- * @author Mikahil Polivakha
+ * @author Mikhail Polivakha
  * @since 2.1
  */
 public class OracleDialect extends AnsiDialect {

spring-data-relational/src/main/java/org/springframework/data/relational/core/dialect/PostgresDialect.java

@@ -57,6 +57,7 @@ public class PostgresDialect extends AbstractDialect {
 
 	private IdentifierProcessing identifierProcessing = IdentifierProcessing.create(Quoting.ANSI,
 			LetterCasing.LOWER_CASE);
+
 	private IdGeneration idGeneration = new IdGeneration() {
 
 		@Override

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Criteria.java

@@ -53,6 +53,7 @@
  * @author Oliver Drotbohm
  * @author Roman Chigvintsev
  * @author Jens Schauder
+ * @author Mikhail Polivakha
  * @since 2.0
  */
 public class Criteria implements CriteriaDefinition {
@@ -68,7 +69,7 @@ public class Criteria implements CriteriaDefinition {
 	private final @Nullable Object value;
 	private final boolean ignoreCase;
 
-	private Criteria(SqlIdentifier column, Comparator comparator, @Nullable Object value) {
+	public Criteria(SqlIdentifier column, @Nullable Comparator comparator, @Nullable Object value) {
 		this(null, Combinator.INITIAL, Collections.emptyList(), column, comparator, value, false);
 	}
 
@@ -328,13 +329,15 @@ private boolean doIsEmpty() {
 	/**
 	 * @return {@literal true} if this {@link Criteria} is empty.
 	 */
+	@Override
 	public boolean isGroup() {
 		return !this.group.isEmpty();
 	}
 
 	/**
 	 * @return {@link Combinator} to combine this criteria with a previous one.
 	 */
+	@Override
 	public Combinator getCombinator() {
 		return combinator;
 	}
@@ -515,6 +518,10 @@ private static String renderValue(@Nullable Object value) {
 			return joiner.toString();
 		}
 
+		if (value instanceof CriteriaLiteral literal) {
+			return literal.getLiteral();
+		}
+
 		if (value != null) {
 			return String.format("'%s'", value);
 		}
@@ -653,6 +660,12 @@ public interface CriteriaStep {
 		 * @return a new {@link Criteria} object
 		 */
 		Criteria isFalse();
+
+	}
+
+	static interface CriteriaLiteral {
+
+		String getLiteral();
 	}
 
 	/**
@@ -812,7 +825,7 @@ public Criteria isFalse() {
 			return createCriteria(Comparator.IS_FALSE, false);
 		}
 
-		protected Criteria createCriteria(Comparator comparator, @Nullable Object value) {
+        protected Criteria createCriteria(@Nullable Comparator comparator, @Nullable Object value) {
 			return new Criteria(this.property, comparator, value);
 		}
 	}

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/CriteriaDefinition.java

@@ -28,6 +28,7 @@
  *
  * @author Mark Paluch
  * @author Jens Schauder
+ * @author Mikhail Polivakha
  * @since 2.0
  */
 public interface CriteriaDefinition {
@@ -140,7 +141,7 @@ enum Combinator {
 	enum Comparator {
 		INITIAL(""), EQ("="), NEQ("!="), BETWEEN("BETWEEN"), NOT_BETWEEN("NOT BETWEEN"), LT("<"), LTE("<="), GT(">"), GTE(
 				">="), IS_NULL("IS NULL"), IS_NOT_NULL("IS NOT NULL"), LIKE(
-						"LIKE"), NOT_LIKE("NOT LIKE"), NOT_IN("NOT IN"), IN("IN"), IS_TRUE("IS TRUE"), IS_FALSE("IS FALSE");
+						"LIKE"), NOT_LIKE("NOT LIKE"), NOT_IN("NOT IN"), IN("IN"), IS_TRUE("IS TRUE"), IS_FALSE("IS FALSE"), ARRAY_CONTAINS("@>");
 
 		private final String comparator;
 

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/OngoingArrayCriteria.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.data.relational.core.query;
+
+/**
+ * An Ongoing Criteria builder for {@link java.sql.Types#ARRAY SQL Array} related operations.
+ * Used by intermediate builder objects returned from the {@link Criteria}.
+ *
+ * @author Mikhail Polivakha
+ */
+public interface OngoingArrayCriteria {
+
+	/**
+	 * Builds a {@link Criteria} where the pre-defined array must contain given values.
+	 *
+	 * @param values values to be present in the array
+	 * @return built {@link Criteria}
+	 */
+	Criteria contains(Object... values);
+}

spring-data-relational/src/main/java/org/springframework/data/relational/core/query/Postgres.java

@@ -0,0 +1,103 @@
+/*
+ * Copyright 2020-2025 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.data.relational.core.query;
+
+import static org.springframework.data.relational.core.query.Criteria.*;
+
+import java.sql.JDBCType;
+import java.util.StringJoiner;
+
+import org.jetbrains.annotations.NotNull;
+import org.springframework.core.ResolvableType;
+import org.springframework.data.relational.core.sql.SqlIdentifier;
+import org.springframework.data.util.TypeInformation;
+import org.springframework.util.Assert;
+
+/**
+ * PostgreSQL-specific {@link Criteria} conditions.
+ *
+ * @author Mikhail Polivakha
+ */
+public class Postgres {
+
+	/**
+	 * Custom {@link Criteria} condition builder to check if the column of an {@link java.sql.Types#ARRAY ARRAY} sql type
+	 * matches specific conditions. Samples of usage is:
+	 * <p>
+	 * <pre class="code">
+	 * // Code below produces the SQL: "my_column" @> ARRAY['A', 'B']
+	 * Postgres.whereArray("my_column").contains("A", "B")
+	 * </pre>
+	 * Code above produces the SQL:
+	 * <pre class="code">
+	 *   "my_column" @> ARRAY['A', 'B']
+	 * </pre>
+	 *
+	 * @param arrayName the name of an ARRAY column to match against
+	 * @return the {@link OngoingArrayCriteria} to chain future condition
+	 */
+	public static OngoingArrayCriteria array(String arrayName) {
+		return new PostgresCriteriaArray(arrayName);
+	}
+
+	public static class PostgresCriteriaArray implements OngoingArrayCriteria {
+
+		private final String arrayColumnName;
+
+		public PostgresCriteriaArray(String arrayColumnName) {
+			this.arrayColumnName = arrayColumnName;
+		}
+
+		@NotNull
+		@Override
+		public Criteria contains(Object... values) {
+			Assert.notNull(values, "values array cannot be null");
+
+			return new Criteria(SqlIdentifier.quoted(arrayColumnName), CriteriaDefinition.Comparator.ARRAY_CONTAINS, new CriteriaLiteral() {
+
+				@Override
+				public String getLiteral() {
+					boolean quoted = true;
+
+					if (values.length > 0) {
+						quoted = !Number.class.isAssignableFrom(values[0].getClass());
+					}
+
+					return toArrayLiteral(quoted, values);
+				}
+			});
+		}
+
+		@SafeVarargs
+		public final <T> String toArrayLiteral(boolean quoted, T... values) {
+			StringJoiner accumulator = new StringJoiner(",", "ARRAY[", "]");
+
+			for (T value : values) {
+				if (value != null) {
+					if (quoted) {
+						accumulator.add("'" + value + "'");
+					} else {
+						accumulator.add(value.toString());
+					}
+				} else {
+					accumulator.add(JDBCType.NULL.name());
+				}
+			}
+			return accumulator.toString();
+		}
+	}
+}

spring-data-relational/src/test/java/org/springframework/data/relational/core/query/CriteriaUnitTests.java

@@ -21,6 +21,7 @@
 
 import java.util.Arrays;
 
+import org.assertj.core.api.InstanceOfAssertFactories;
 import org.junit.jupiter.api.Test;
 import org.springframework.data.relational.core.sql.SqlIdentifier;
 
@@ -30,6 +31,7 @@
  * @author Mark Paluch
  * @author Jens Schauder
  * @author Roman Chigvintsev
+ * @author Mikhail Polivakha
  */
 class CriteriaUnitTests {
 
@@ -95,6 +97,27 @@ void andChainedCriteria() {
 		assertThat(criteria.getValue()).isEqualTo("bar");
 	}
 
+	@Test // DATAJDBC-513
+	void andChainedCriteriaWithDialectCriteriaCondition() {
+
+		Criteria criteria = where("foo").is("bar").and(Postgres.array("baz").contains("first", "second"));
+		var previous = criteria.getPrevious();
+
+		assertSoftly(softAssertions -> {
+			softAssertions.assertThat(criteria.getGroup().get(0).getColumn()).isEqualTo(SqlIdentifier.quoted("baz"));
+			softAssertions.assertThat(criteria.getComparator()).isNull();
+			softAssertions.assertThat(criteria.getValue()).isNull();
+			softAssertions.assertThat(criteria.getPrevious()).isNotNull();
+			softAssertions.assertThat(criteria.getCombinator()).isEqualTo(Criteria.Combinator.AND);
+			softAssertions.assertThat(criteria.toString()).isEqualTo("foo = 'bar' AND (baz @> ARRAY['first','second'])");
+
+			softAssertions.assertThat(previous.getColumn()).isEqualTo(SqlIdentifier.unquoted("foo"));
+			softAssertions.assertThat(previous.getComparator()).isEqualTo(CriteriaDefinition.Comparator.EQ);
+			softAssertions.assertThat(previous.getValue()).isEqualTo("bar");
+			softAssertions.assertThat(previous.toString()).isEqualTo("foo = 'bar'");
+		});
+	}
+
 	@Test // DATAJDBC-513
 	void andGroupedCriteria() {
 
@@ -116,6 +139,26 @@ void andGroupedCriteria() {
 		assertThat(grouped).hasToString("foo = 'bar' AND (foo = 'baz' OR bar IS NOT NULL)");
 	}
 
+	@Test // DATAJDBC-1953
+	void andGroupedCriteriaWithDialectCriteriaCondition() {
+
+		Criteria grouped = where("foo").is("bar").and(where("foo").is("baz").or(Postgres.array("bar").contains("electronics")));
+		Criteria previous = grouped.getPrevious();
+
+		assertSoftly(softAssertions -> {
+			softAssertions.assertThat(grouped.isGroup()).isTrue();
+			softAssertions.assertThat(grouped.getGroup()).hasSize(1);
+			softAssertions.assertThat(grouped.getGroup().get(0).getGroup().get(0).getColumn()).isEqualTo(SqlIdentifier.unquoted("\"bar\""));
+			softAssertions.assertThat(grouped.getCombinator()).isEqualTo(Criteria.Combinator.AND);
+			softAssertions.assertThat(grouped).hasToString("foo = 'bar' AND (foo = 'baz' OR (bar @> ARRAY['electronics']))");
+
+			softAssertions.assertThat(previous).isNotNull();
+			softAssertions.assertThat(previous.getColumn()).isEqualTo(SqlIdentifier.unquoted("foo"));
+			softAssertions.assertThat(previous.getComparator()).isEqualTo(CriteriaDefinition.Comparator.EQ);
+			softAssertions.assertThat(previous.getValue()).isEqualTo("bar");
+		});
+	}
+
 	@Test // DATAJDBC-513
 	void orChainedCriteria() {
 
@@ -179,6 +222,25 @@ void shouldBuildNotEqualsCriteria() {
 		assertThat(criteria.getValue()).isEqualTo("bar");
 	}
 
+	@Test // DATAJDBC-1953
+	void shouldBuildSimplePredefinedDialectCriteriaCondition() {
+
+		Object[] values = { 1, 2, 3 };
+		Criteria criteria = Postgres.array("foo").contains(values);
+
+		assertSoftly(softAssertions -> {
+			softAssertions.assertThat(criteria.getColumn()).isEqualTo(SqlIdentifier.quoted("foo"));
+			softAssertions.assertThat(criteria.getComparator()).isEqualTo(Comparator.ARRAY_CONTAINS);
+			softAssertions.assertThat(criteria.getValue()).isInstanceOf(CriteriaLiteral.class);
+			softAssertions
+					.assertThat(criteria.getValue())
+					.asInstanceOf(InstanceOfAssertFactories.type(CriteriaLiteral.class))
+					.extracting(CriteriaLiteral::getLiteral)
+					.isEqualTo("ARRAY[1,2,3]");
+			softAssertions.assertThat(criteria.toString()).isEqualTo("foo @> ARRAY[1,2,3]");
+		});
+	}
+
 	@Test // DATAJDBC-513
 	void shouldBuildInCriteria() {