Skip to content

Conversation

@alamb
Copy link
Contributor

@alamb alamb commented Jun 13, 2025

Which issue does this PR close?

We generally require a GitHub issue to be filed for all bug fixes and enhancements and this helps us generate change logs for our releases. You can link an issue to this PR using the GitHub syntax.

Rationale for this change

Using the parquet APIs came up in #7644 (comment) so I wanted to help contribute some additional documentation / tests

What changes are included in this PR?

Add documentation and tests about Variant, specifically some examples of how to create Variant values

Are there any user-facing changes?

More docs

@github-actions github-actions bot added the parquet Changes to the parquet crate label Jun 13, 2025
@alamb alamb marked this pull request as ready for review June 13, 2025 15:42
@alamb
Copy link
Contributor Author

alamb commented Jun 13, 2025

FYI @mkarbo @superserious-dev @scovich and @PinkCrow007

alamb added a commit that referenced this pull request Jun 16, 2025
# Which issue does this PR close?

- Part of #6736

# Rationale for this change

While making documentation / examples for working with `Variant` in
#7661, I found it was somewhat
awkward to make `Variant` values directly from the metadata and value.
Specifically you have to

```rust
let metadata = [0x01, 0x00, 0x00];
let value = [0x09, 0x48, 0x49];
// parse the header metadata
let metadata = VariantMetadata::try_new(&metadata).unwrap();
// and only then can you make the Variant
Variant::try_new(&metadata, &value).unwrap()
```

I would really like to be able to create `Variant `directly from
`metadata` and `value` without having to make a `VariantMetadata`
structure

# What changes are included in this PR?

This PR proposes a small change to the API so creating a Variant now
looks like:

```rust
let metadata = [0x01, 0x00, 0x00];
let value = [0x09, 0x48, 0x49];
// You can now make the Variant directly from the metadata and value
Variant::try_new(&metadata, &value).unwrap()
```


# Are there any user-facing changes?
Yes, the API for creating APIs is slightly different (and I think
better)
@alamb
Copy link
Contributor Author

alamb commented Jun 17, 2025

I am quite pleased with how this looks now

@alamb
Copy link
Contributor Author

alamb commented Jun 18, 2025

@scovich @PinkCrow007 or @mkarbo , might I trouble one of you for a review of this PR (no code, just docs)?

@alamb alamb added the documentation Improvements or additions to documentation label Jun 18, 2025
Copy link
Contributor

@scovich scovich left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, couple tiny nits

///
/// When stored in Parquet files, Variant fields can also be *shredded*. Shredding
/// refers to extracting some elements of the variant into separate columns for
/// more efficient extraction/filter pushdown. The [Variant Shredding
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Link?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked the rendered version and it seems to be working. I am not sure what you mean here

Screenshot 2025-06-19 at 6 39 22 AM

@alamb
Copy link
Contributor Author

alamb commented Jun 19, 2025

Thank you for the reviews @mkarbo and @scovich

@alamb alamb merged commit fe65b8d into apache:main Jun 19, 2025
12 checks passed
@alamb alamb deleted the alamb/variant_docs branch June 19, 2025 10:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation parquet Changes to the parquet crate

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants