(arrow-rs) branch master updated: Minor: improve filter documentation (#6317)

[alamb]

This is an automated email from the ASF dual-hosted git repository.

alamb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/arrow-rs.git


The following commit(s) were added to refs/heads/master by this push:
     new 69e5e5f059 Minor: improve filter documentation (#6317)
69e5e5f059 is described below

commit 69e5e5f059783a4b98bd8dacb7e1487a6ae7e77b
Author: Andrew Lamb <and...@nerdnetworks.org>
AuthorDate: Sat Aug 31 08:41:23 2024 -0400

    Minor: improve filter documentation (#6317)
    
    * Minor: improve filter documentation
    
    * less space
---
 arrow-select/src/filter.rs | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/arrow-select/src/filter.rs b/arrow-select/src/filter.rs
index d72794b3e3..c51f44a977 100644
--- a/arrow-select/src/filter.rs
+++ b/arrow-select/src/filter.rs
@@ -153,7 +153,10 @@ pub fn prep_null_mask_filter(filter: &BooleanArray) -> 
BooleanArray {
     BooleanArray::new(mask, None)
 }
 
-/// Filters an [Array], returning elements matching the filter (i.e. where the 
values are true).
+/// Returns a filtered `values` [Array] where the corresponding elements of
+/// `predicate` are `true`.
+///
+/// See also [`FilterBuilder`] for more control over the filtering process.
 ///
 /// # Example
 /// ```rust
@@ -170,7 +173,10 @@ pub fn filter(values: &dyn Array, predicate: 
&BooleanArray) -> Result<ArrayRef,
     filter_array(values, &predicate)
 }
 
-/// Returns a new [RecordBatch] with arrays containing only values matching 
the filter.
+/// Returns a filtered [RecordBatch] where the corresponding elements of
+/// `predicate` are true.
+///
+/// This is the equivalent of calling [filter] on each column of the 
[RecordBatch].
 pub fn filter_record_batch(
     record_batch: &RecordBatch,
     predicate: &BooleanArray,
@@ -178,6 +184,7 @@ pub fn filter_record_batch(
     let mut filter_builder = FilterBuilder::new(predicate);
     if record_batch.num_columns() > 1 {
         // Only optimize if filtering more than one column
+        // Otherwise, the overhead of optimization can be more than the benefit
         filter_builder = filter_builder.optimize();
     }
     let filter = filter_builder.build();