Doc: improve description for sort order fields in spec #2201
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
rdblue
reviewed
Feb 2, 2021
| | _optional_ | _required_ | **`sort-orders`**| A list of sort orders, stored as full sort order objects. | | ||
| | _optional_ | _required_ | **`default-sort-order-id`**| Default sort order id of the table. Note that this could be used by writers, but is not used when reading because reads use the specs stored in manifest files. | | ||
| | _optional_ | _required_ | **`sort-orders`**| A list of sort orders, stored as full sort order objects. Note that this field is optional when v2 is reading because v1 metadata is still valid, but a v2 writer must always write this field. | | ||
| | _optional_ | _required_ | **`default-sort-order-id`**| Default sort order id of the table. Note that this could be used by writers, but is not used when reading because reads use the specs stored in manifest files. Also note that this field is optional when v2 is reading because v1 metadata is still valid, but a v2 writer must always write this field. | |
There was a problem hiding this comment.
I think this information should be covered in a more general section about how to interpret the optional and required columns. V2 readers should be able to read v1 metadata, which means anything that is omitted or missing in v1 is optional when reading for v2. The required here always refers to the writer, and we don't need to include an extra sentence explaining that in each row.
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.
This PR is for the followup in #2055 (comment)