implement array_sample

diesel/src/pg/expression/functions.rs

@@ -1432,7 +1432,7 @@ define_sql_function! {
     /// # Example
     ///
     // This function requires postgres >= 16.0
-    // which we cannot expect to be widly used at the
+    // which we cannot expect to be widely used at the
     // point of writing this comment, so we skip running this test
     /// ```rust,no_run
     /// # include!("../../doctest_setup.rs");
@@ -1455,6 +1455,48 @@ define_sql_function! {
     fn array_shuffle<Arr: ArrayOrNullableArray + SingleValue>(array: Arr) -> Arr;
 }
 
+#[cfg(feature = "postgres_backend")]
+define_sql_function! {
+    /// Returns an array of n items randomly selected from array.
+    /// n may not exceed the length of the array.
+    ///
+    /// # Example
+    ///
+    // This function requires postgres >= 16.0
+    // which we cannot expect to be widely used at the
+    // point of writing this comment, so we skip running this test
+    /// ```rust,no_run
+    /// # include!("../../doctest_setup.rs");
+    /// #
+    /// # fn main() {
+    /// #     run_test().unwrap();
+    /// # }
+    /// #
+    /// # fn run_test() -> QueryResult<()> {
+    /// #     use diesel::dsl::array_sample;
+    /// #     use diesel::sql_types::{Array, Integer, Nullable};
+    /// #     let connection = &mut establish_connection();
+    ///
+    /// let vec = vec![1,2,3,4,5];
+    /// let sampled = diesel::select(array_sample::<Array<Integer>, _, _>(vec.clone(),3))
+    ///     .get_result::<Vec<i32>>(connection)?;
+    /// assert_eq!(3, sampled.len());
+    /// assert!(sampled.iter().all(|x| vec.contains(x)));
+    ///
+    /// let vec: Vec<i32> = Vec::new();
+    /// let sampled = diesel::select(array_sample::<Array<Integer>, _, _>(vec,0))
+    ///     .get_result::<Vec<i32>>(connection)?;
+    /// assert_eq!(0, sampled.len());
+    ///
+    /// let sampled = diesel::select(array_sample::<Nullable<Array<Integer>>, _, _>(None::<Vec<i32>>,1))
+    ///     .get_result::<Option<Vec<i32>>>(connection)?;
+    /// assert!(sampled.is_none());
+    /// #     Ok(())
+    /// # }
+    /// ```
+    fn array_sample<Arr: ArrayOrNullableArray + SingleValue>(array: Arr, n: Integer) -> Arr;
+}
+
 #[cfg(feature = "postgres_backend")]
 define_sql_function! {
     /// Converts any SQL value to json

diesel/src/pg/expression/helper_types.rs

@@ -467,6 +467,11 @@ pub type array_ndims<A> = super::functions::array_ndims<SqlTypeOf<A>, A>;
 #[cfg(feature = "postgres_backend")]
 pub type array_shuffle<A> = super::functions::array_shuffle<SqlTypeOf<A>, A>;
 
+/// Return type of [`array_sample(array,n)`](super::function::array_sample())
+#[allow(non_camel_case_types)]
+#[cfg(feature = "postgres_backend")]
+pub type array_sample<A, N> = super::functions::array_sample<SqlTypeOf<A>, A, N>;
+
 /// Return type of [`to_json(element)`](super::functions::to_json())
 #[allow(non_camel_case_types)]
 #[cfg(feature = "postgres_backend")]

diesel_derives/tests/auto_type.rs

@@ -433,6 +433,7 @@ fn postgres_functions() -> _ {
         array_positions(pg_extras::array, pg_extras::id),
         array_ndims(pg_extras::array),
         array_shuffle(pg_extras::array),
+        array_sample(pg_extras::array, pg_extras::id),
         to_json(pg_extras::id),
     )
 }