[SPARK-28503][SQL] Return null result on cast an out-of-range value to a integral type

docs/sql-migration-guide-hive-compatibility.md

@@ -165,3 +165,12 @@ Below are the scenarios in which Hive and Spark generate different results:
 * `SQRT(n)` If n < 0, Hive returns null, Spark SQL returns NaN.
 * `ACOS(n)` If n < -1 or n > 1, Hive returns null, Spark SQL returns NaN.
 * `ASIN(n)` If n < -1 or n > 1, Hive returns null, Spark SQL returns NaN.
+
+### Incompatible data type conversion
+
+For type conversion, if the value is too big to fit in the target integral data type, Spark will return `null`,
+while Hive always returns lower-order bits. The related integral data types are:
+* Byte
+* Short
+* Int
+* Long

docs/sql-migration-guide-upgrade.md

@@ -23,6 +23,8 @@ license: |
 {:toc}
 
 ## Upgrading From Spark SQL 2.4 to 3.0
+  - Since Spark 3.0, for type conversion, if the value is too big to fit in the target `Long`/`Int`/`Short`/`Byte` data type, Spark will return `null`. In Spark version 2.4 and earlier, Spark always returns the lower-order bits of the out-of-range value. For example, the result of `Cast(257, ByteType)` will be `null`, instead of `1`.
+
   - Since Spark 3.0, we reversed argument order of the trim function from `TRIM(trimStr, str)` to `TRIM(str, trimStr)` to be compatible with other databases.
 
   - Since Spark 3.0, PySpark requires a Pandas version of 0.23.2 or higher to use Pandas related functionality, such as `toPandas`, `createDataFrame` from Pandas DataFrame, etc.