HHH-17355 Rename array_contains_any to array_overlaps

documentation/src/main/asciidoc/userguide/chapters/query/hql/QueryLanguage.adoc

@@ -1118,17 +1118,15 @@ The following functions deal with SQL array types, which are not supported on ev
 | Function | Purpose
 
 | `array()` | Creates an array based on the passed arguments
-| `array_contains()` | Whether an array contains an element
-| `array_contains_null()` | Whether an array contains a null
 | `array_position()` | Determines the position of an element in an array
 | `array_length()` | Determines the length of an array
 | `array_concat()` | Concatenates array with each other in order
 | `array_prepend()` | Prepends element to array
 | `array_append()` | Appends element to array
-| `array_contains_all()` | Determines if one array holds all elements of another array
-| `array_contains_all_nullable()` | Determines if one array holds all elements of another array, supporting null elements
-| `array_contains_any()` | Determines if one array holds at least one element of another array
-| `array_contains_any_nullable()` | Determines if one array holds at least one element of another array, supporting null elements
+| `array_contains()` | Whether an array contains element(s)
+| `array_contains_nullable()` | Whether an array contains element(s), supporting `null` elements
+| `array_overlaps()` | Whether an array holds at least one element of another array
+| `array_overlaps_nullable()` | Whether an array holds at least one element of another array, supporting `null` elements
 | `array_get()` | Accesses the element of an array by index
 | `array_set()` | Creates array copy with given element at given index
 | `array_remove()` | Creates array copy with given element removed
@@ -1148,25 +1146,6 @@ include::{array-example-dir-hql}/ArrayConstructorTest.java[tags=hql-array-exampl
 ----
 ====
 
-[[hql-array-contains-functions]]
-===== `array_contains()` and `array_contains_null()`
-
-Both functions return `null` if the first argument, the array, is null, yet the result of the `array_contains` function
-is undefined when the second argument, the element to search, is `null`.
-The `array_contains_null` function only takes a single argument, the array, and will return whether the array contains a `null` element.
-
-[[hql-array-contains-example]]
-====
-[source, JAVA, indent=0]
-----
-include::{array-example-dir-hql}/ArrayContainsTest.java[tags=hql-array-contains-example]
-----
-[source, JAVA, indent=0]
-----
-include::{array-example-dir-hql}/ArrayContainsTest.java[tags=hql-array-contains-null-example]
-----
-====
-
 [[hql-array-position-functions]]
 ===== `array_position()`
 
@@ -1232,49 +1211,63 @@ include::{array-example-dir-hql}/ArrayAppendTest.java[tags=hql-array-append-exam
 ----
 ====
 
-[[hql-array-contains-quantified-functions]]
-===== `array_contains_all()` and `array_contains_any()`
+[[hql-array-contains-functions]]
+===== `array_contains()` and `array_contains_nullable()`
+
+Checks if the first array argument contains the element(s) of the second argument.
+Returns `null` if the first argument is `null`. The result of the `array_contains` function
+is undefined when the second argument, the element to search, is `null`.
+
+[[hql-array-contains-example]]
+====
+[source, JAVA, indent=0]
+----
+include::{array-example-dir-hql}/ArrayContainsTest.java[tags=hql-array-contains-example]
+----
+====
 
-Checks if the first array argument contains all or any of the elements of the second array argument.
-Returns `null` if either of the arguments is `null`. The result of the functions
-is undefined when the second array argument contains a `null`.
+The second argument may be an array of the same type as the first argument.
+The result of `array_contains` is undefined when the second argument is an array that contains a `null` element.
 
-[[hql-array-contains-all-example]]
+[[hql-array-contains-array-example]]
 ====
 [source, JAVA, indent=0]
 ----
 include::{array-example-dir-hql}/ArrayContainsAllTest.java[tags=hql-array-contains-all-example]
 ----
 ====
 
-[[hql-array-contains-any-example]]
+To search for `null` elements, the `array_contains_nullable` function must be used with an array argument.
+
+[[hql-array-contains-array-nullable-example]]
 ====
 [source, JAVA, indent=0]
 ----
-include::{array-example-dir-hql}/ArrayContainsAnyTest.java[tags=hql-array-contains-any-example]
+include::{array-example-dir-hql}/ArrayContainsAllTest.java[tags=hql-array-contains-all-nullable-example]
 ----
 ====
 
-[[hql-array-contains-quantified-functions]]
-===== `array_contains_all_nullable()` & `array_contains_any_nullable()`
+[[hql-array-overlaps-functions]]
+===== `array_overlaps()` and `array_overlaps_nullable()`
 
-Checks if the first array argument contains all or any of the elements of the second array argument.
-Returns `null` if either of the arguments is `null`. Contrary to `array_contains_all()` and `array_contains_any()`,
-these functions use the `distinct from` operator to also support searching for `null` elements.
+Checks if the first array argument any of the elements of the second array argument.
+Returns `null` if either of the arguments is `null`. The result of `array_overlaps`
+is undefined when the second array argument contains a `null` array element.
+Only `array_overlaps_nullable` is guaranteed to produce correct results for `null` array elements.
 
-[[hql-array-contains-all-nullable-example]]
+[[hql-array-overlaps-example]]
 ====
 [source, JAVA, indent=0]
 ----
-include::{array-example-dir-hql}/ArrayContainsAllTest.java[tags=hql-array-contains-all-nullable-example]
+include::{array-example-dir-hql}/ArrayOverlapsTest.java[tags=hql-array-overlaps-example]
 ----
 ====
 
-[[hql-array-contains-any-nullable-example]]
+[[hql-array-overlaps-nullable-example]]
 ====
 [source, JAVA, indent=0]
 ----
-include::{array-example-dir-hql}/ArrayContainsAnyTest.java[tags=hql-array-contains-any-nullable-example]
+include::{array-example-dir-hql}/ArrayOverlapsTest.java[tags=hql-array-overlaps-nullable-example]
 ----
 ====
 

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/CockroachLegacyDialect.java

@@ -471,9 +471,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_postgresql();
 		functionFactory.arrayAppend_postgresql();
 		functionFactory.arrayContainsAll_operator();
-		functionFactory.arrayContainsAny_operator();
+		functionFactory.arrayOverlaps_operator();
 		functionFactory.arrayContainsAllNullable_operator();
-		functionFactory.arrayContainsAnyNullable_operator();
+		functionFactory.arrayOverlapsNullable_unnest();
 		functionFactory.arrayGet_bracket();
 		functionFactory.arraySet_unnest();
 		functionFactory.arrayRemove();

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/H2LegacyDialect.java

@@ -379,9 +379,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 				functionFactory.arrayPrepend_operator();
 				functionFactory.arrayAppend_operator();
 				functionFactory.arrayContainsAll_h2();
-				functionFactory.arrayContainsAny_h2();
+				functionFactory.arrayOverlaps_h2();
 				functionFactory.arrayContainsAllNullable_h2();
-				functionFactory.arrayContainsAnyNullable_h2();
+				functionFactory.arrayOverlapsNullable_h2();
 				functionFactory.arrayGet_h2();
 				functionFactory.arraySet_h2();
 				functionFactory.arrayRemove_h2();

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/HSQLLegacyDialect.java

@@ -257,9 +257,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_operator();
 		functionFactory.arrayAppend_operator();
 		functionFactory.arrayContainsAll_hsql();
-		functionFactory.arrayContainsAny_hsql();
+		functionFactory.arrayOverlaps_hsql();
 		functionFactory.arrayContainsAllNullable_hsql();
-		functionFactory.arrayContainsAnyNullable_hsql();
+		functionFactory.arrayOverlapsNullable_unnest();
 		functionFactory.arrayGet_unnest();
 		functionFactory.arraySet_hsql();
 		functionFactory.arrayRemove_hsql();

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/OracleLegacyDialect.java

@@ -293,9 +293,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_oracle();
 		functionFactory.arrayAppend_oracle();
 		functionFactory.arrayContainsAll_oracle();
-		functionFactory.arrayContainsAny_oracle();
+		functionFactory.arrayOverlaps_oracle();
 		functionFactory.arrayContainsAllNullable_oracle();
-		functionFactory.arrayContainsAnyNullable_oracle();
+		functionFactory.arrayOverlapsNullable_oracle();
 		functionFactory.arrayGet_oracle();
 		functionFactory.arraySet_oracle();
 		functionFactory.arrayRemove_oracle();

hibernate-community-dialects/src/main/java/org/hibernate/community/dialect/PostgreSQLLegacyDialect.java

@@ -591,9 +591,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_postgresql();
 		functionFactory.arrayAppend_postgresql();
 		functionFactory.arrayContainsAll_operator();
-		functionFactory.arrayContainsAny_operator();
+		functionFactory.arrayOverlaps_operator();
 		functionFactory.arrayContainsAllNullable_operator();
-		functionFactory.arrayContainsAnyNullable_operator();
+		functionFactory.arrayOverlapsNullable_unnest();
 		functionFactory.arrayGet_bracket();
 		functionFactory.arraySet_unnest();
 		functionFactory.arrayRemove();

hibernate-core/src/main/java/org/hibernate/dialect/CockroachDialect.java

@@ -458,9 +458,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_postgresql();
 		functionFactory.arrayAppend_postgresql();
 		functionFactory.arrayContainsAll_operator();
-		functionFactory.arrayContainsAny_operator();
+		functionFactory.arrayOverlaps_operator();
 		functionFactory.arrayContainsAllNullable_operator();
-		functionFactory.arrayContainsAnyNullable_operator();
+		functionFactory.arrayOverlapsNullable_unnest();
 		functionFactory.arrayGet_bracket();
 		functionFactory.arraySet_unnest();
 		functionFactory.arrayRemove();

hibernate-core/src/main/java/org/hibernate/dialect/H2Dialect.java

@@ -318,9 +318,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_operator();
 		functionFactory.arrayAppend_operator();
 		functionFactory.arrayContainsAll_h2();
-		functionFactory.arrayContainsAny_h2();
+		functionFactory.arrayOverlaps_h2();
 		functionFactory.arrayContainsAllNullable_h2();
-		functionFactory.arrayContainsAnyNullable_h2();
+		functionFactory.arrayOverlapsNullable_h2();
 		functionFactory.arrayGet_h2();
 		functionFactory.arraySet_h2();
 		functionFactory.arrayRemove_h2();

hibernate-core/src/main/java/org/hibernate/dialect/HSQLDialect.java

@@ -197,9 +197,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_operator();
 		functionFactory.arrayAppend_operator();
 		functionFactory.arrayContainsAll_hsql();
-		functionFactory.arrayContainsAny_hsql();
+		functionFactory.arrayOverlaps_hsql();
 		functionFactory.arrayContainsAllNullable_hsql();
-		functionFactory.arrayContainsAnyNullable_hsql();
+		functionFactory.arrayOverlapsNullable_unnest();
 		functionFactory.arrayGet_unnest();
 		functionFactory.arraySet_hsql();
 		functionFactory.arrayRemove_hsql();

hibernate-core/src/main/java/org/hibernate/dialect/OracleArrayJdbcType.java

@@ -307,10 +307,10 @@ public void addAuxiliaryDatabaseObjects(
 		);
 		database.addAuxiliaryDatabaseObject(
 				new NamedAuxiliaryDatabaseObject(
-						arrayTypeName + "_contains_any",
+						arrayTypeName + "_overlaps",
 						database.getDefaultNamespace(),
 						new String[]{
-								"create or replace function " + arrayTypeName + "_contains_any(haystack in " + arrayTypeName +
+								"create or replace function " + arrayTypeName + "_overlaps(haystack in " + arrayTypeName +
 										", needle in " + arrayTypeName + ", nullable in number) return number deterministic is begin " +
 										"if haystack is null or needle is null then return null; end if; " +
 										"if needle.count = 0 then return 1; end if; " +
@@ -322,7 +322,7 @@ public void addAuxiliaryDatabaseObjects(
 										"return 0; " +
 										"end;"
 						},
-						new String[] { "drop function " + arrayTypeName + "_contains_any" },
+						new String[] { "drop function " + arrayTypeName + "_overlaps" },
 						emptySet(),
 						false
 				)

hibernate-core/src/main/java/org/hibernate/dialect/OracleDialect.java

@@ -322,9 +322,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_oracle();
 		functionFactory.arrayAppend_oracle();
 		functionFactory.arrayContainsAll_oracle();
-		functionFactory.arrayContainsAny_oracle();
+		functionFactory.arrayOverlaps_oracle();
 		functionFactory.arrayContainsAllNullable_oracle();
-		functionFactory.arrayContainsAnyNullable_oracle();
+		functionFactory.arrayOverlapsNullable_oracle();
 		functionFactory.arrayGet_oracle();
 		functionFactory.arraySet_oracle();
 		functionFactory.arrayRemove_oracle();

hibernate-core/src/main/java/org/hibernate/dialect/PostgreSQLDialect.java

@@ -639,9 +639,9 @@ public void initializeFunctionRegistry(FunctionContributions functionContributio
 		functionFactory.arrayPrepend_postgresql();
 		functionFactory.arrayAppend_postgresql();
 		functionFactory.arrayContainsAll_operator();
-		functionFactory.arrayContainsAny_operator();
+		functionFactory.arrayOverlaps_operator();
 		functionFactory.arrayContainsAllNullable_operator();
-		functionFactory.arrayContainsAnyNullable_operator();
+		functionFactory.arrayOverlapsNullable_unnest();
 		functionFactory.arrayGet_bracket();
 		functionFactory.arraySet_unnest();
 		functionFactory.arrayRemove();

hibernate-core/src/main/java/org/hibernate/dialect/function/CommonFunctionFactory.java

@@ -40,7 +40,7 @@
 import org.hibernate.dialect.function.array.OracleArrayConcatElementFunction;
 import org.hibernate.dialect.function.array.OracleArrayConcatFunction;
 import org.hibernate.dialect.function.array.OracleArrayContainsAllFunction;
-import org.hibernate.dialect.function.array.OracleArrayContainsAnyFunction;
+import org.hibernate.dialect.function.array.OracleArrayOverlapsFunction;
 import org.hibernate.dialect.function.array.OracleArrayGetFunction;
 import org.hibernate.dialect.function.array.OracleArrayLengthFunction;
 import org.hibernate.dialect.function.array.OracleArrayPositionFunction;
@@ -2768,39 +2768,39 @@ public void arrayContainsAll_oracle() {
 	}
 
 	/**
-	 * H2 array_contains_any() function
+	 * H2 array_overlaps() function
 	 */
-	public void arrayContainsAny_h2() {
+	public void arrayOverlaps_h2() {
 		functionRegistry.register(
-				"array_contains_any",
+				"array_overlaps",
 				new H2ArrayContainsQuantifiedEmulation( typeConfiguration, false, false )
 		);
 	}
 
 	/**
-	 * HSQL array_contains_any() function
+	 * HSQL array_overlaps() function
 	 */
-	public void arrayContainsAny_hsql() {
+	public void arrayOverlaps_hsql() {
 		functionRegistry.register(
-				"array_contains_any",
+				"array_overlaps",
 				new ArrayContainsQuantifiedUnnestFunction( typeConfiguration, false, false )
 		);
 	}
 
 	/**
-	 * CockroachDB and PostgreSQL array contains any operator
+	 * CockroachDB and PostgreSQL array overlaps operator
 	 */
-	public void arrayContainsAny_operator() {
-		functionRegistry.register( "array_contains_any", new ArrayContainsQuantifiedOperatorFunction( typeConfiguration, false, false ) );
+	public void arrayOverlaps_operator() {
+		functionRegistry.register( "array_overlaps", new ArrayContainsQuantifiedOperatorFunction( typeConfiguration, false, false ) );
 	}
 
 	/**
-	 * Oracle array_contains_any() function
+	 * Oracle array_overlaps() function
 	 */
-	public void arrayContainsAny_oracle() {
+	public void arrayOverlaps_oracle() {
 		functionRegistry.register(
-				"array_contains_any",
-				new OracleArrayContainsAnyFunction( typeConfiguration, false )
+				"array_overlaps",
+				new OracleArrayOverlapsFunction( typeConfiguration, false )
 		);
 	}
 
@@ -2845,42 +2845,32 @@ public void arrayContainsAllNullable_oracle() {
 	}
 
 	/**
-	 * H2 array_contains_any_nullable() function
+	 * H2 array_overlaps_nullable() function
 	 */
-	public void arrayContainsAnyNullable_h2() {
+	public void arrayOverlapsNullable_h2() {
 		functionRegistry.register(
-				"array_contains_any_nullable",
+				"array_overlaps_nullable",
 				new H2ArrayContainsQuantifiedEmulation( typeConfiguration, false, true )
 		);
 	}
 
 	/**
-	 * HSQL array_contains_any_nullable() function
+	 * HSQL, CockroachDB and PostgreSQL array_overlaps_nullable() function
 	 */
-	public void arrayContainsAnyNullable_hsql() {
+	public void arrayOverlapsNullable_unnest() {
 		functionRegistry.register(
-				"array_contains_any_nullable",
+				"array_overlaps_nullable",
 				new ArrayContainsQuantifiedUnnestFunction( typeConfiguration, false, true )
 		);
 	}
 
 	/**
-	 * CockroachDB and PostgreSQL array contains any nullable operator
+	 * Oracle array_overlaps_nullable() function
 	 */
-	public void arrayContainsAnyNullable_operator() {
+	public void arrayOverlapsNullable_oracle() {
 		functionRegistry.register(
-				"array_contains_any_nullable",
-				new ArrayContainsQuantifiedOperatorFunction( typeConfiguration, false, true )
-		);
-	}
-
-	/**
-	 * Oracle array_contains_any_nullable() function
-	 */
-	public void arrayContainsAnyNullable_oracle() {
-		functionRegistry.register(
-				"array_contains_any_nullable",
-				new OracleArrayContainsAnyFunction( typeConfiguration, true )
+				"array_overlaps_nullable",
+				new OracleArrayOverlapsFunction( typeConfiguration, true )
 		);
 	}