Improve array builder documentation (#3949) #3951
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
tustvold
added a commit
to tustvold/arrow-rs
that referenced
this pull request
Mar 26, 2023
tustvold
added a commit
to tustvold/arrow-rs
that referenced
this pull request
Mar 26, 2023
tustvold
added a commit
to tustvold/arrow-rs
that referenced
this pull request
Mar 26, 2023
tustvold
commented
Mar 27, 2023
arrow-array/src/builder/mod.rs
Outdated
Comment on lines
113
to
119
| //! match &row.i32_list { | ||
| //! Some(list) => { | ||
| //! list.iter().for_each(|v| self.i32_list.values().append_option(*v)); | ||
| //! self.i32_list.append(true); | ||
| //! } | ||
| //! None => self.i32_list.append(false), | ||
| //! } |
There was a problem hiding this comment.
#3954 should simplify this
alamb
approved these changes
Mar 28, 2023
arrow-array/src/builder/mod.rs
Outdated
Comment on lines
83
to
84
| //! It is common to have a statically defined row representation, and to want to convert | ||
| //! this to an arrow representation. An example of this can be seen below |
There was a problem hiding this comment.
Suggested change
| //! It is common to have a statically defined row representation, and to want to convert | |
| //! this to an arrow representation. An example of this can be seen below | |
| //! It is common to have a collection of objects that you want to | |
| //! convert to Arrow arrays. An example of doing so is below |
arrow-array/src/builder/mod.rs
Outdated
| //! )) | ||
| //! ``` | ||
| //! | ||
| //! # Row Conversion |
There was a problem hiding this comment.
Suggested change
| //! # Row Conversion | |
| //! # Converting other objects to Arrow Arrays |
I was confused at first about the term "Row" as it is over loaded. What do you think about talking about "objects" instead?
arrow-array/src/builder/mod.rs
Outdated
| //! use arrow_schema::{DataType, Field}; | ||
| //! use std::sync::Arc; | ||
| //! /// A representation of a row | ||
| //! struct Row { |
There was a problem hiding this comment.
Maybe it could be called "MyRow" to emphasize it is defined in user code
arrow-array/src/builder/mod.rs
Outdated
| //! use arrow_array::{ArrayRef, RecordBatch, StructArray}; | ||
| //! use arrow_schema::{DataType, Field}; | ||
| //! use std::sync::Arc; | ||
| //! /// A representation of a row |
There was a problem hiding this comment.
Suggested change
| //! /// A representation of a row | |
| //! /// A representation of a row (defined in code elsewhere) |
arrow-array/src/builder/mod.rs
Outdated
| //! i32_list: ListBuilder<Int32Builder>, | ||
| //! } | ||
| //! | ||
| //! impl<'a> Extend<&'a Row> for RowBuilder { |
There was a problem hiding this comment.
I know "extend" is probably more idomatic, but I think it obscures the key use of the builders
I suggest refactoring just the "append one row" code into its own function for clarity
impl RowBuilder {
pub fn append_row(&mut self, row: &Row) {
...
}
}| //! } | ||
| //! | ||
| //! impl RowBuilder { | ||
| //! /// Note: returns StructArray to allow nesting within another array if desired |
There was a problem hiding this comment.
Maybe it is also worth mentioning (or adding a function that does so) that it could return a 4 column RecordBatch as well
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Which issue does this PR close?
Part of #3949
Rationale for this change
It isn't immediately clear how to use the builders to construct arrays,
I want to improve the ergonomics of building arrays using the builders, but first it is important to document the current state of play
What changes are included in this PR?
Are there any user-facing changes?