docs: First pass at documenting schema evolution features #1259
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
Updates some existing concepts pages to add docs on new schema evolution features. Also adds a new concepts page on evolutions, and a new guide outlining how to handle some common schema evolution scenarios.
|
psFried
force-pushed
the
phil/schema-docs
branch
from
51c76c0 to
9b662f7
Compare
| * **In the Flow web app,** [edit the materialization](./edit-data-flows.md#edit-a-materialization), find the affected binding, and click **Show Fields**. | ||
| * **Using flowctl,** add the field to `fields.include` in the materialization specification as shown [here](../concepts/materialization.md#projected-fields). | ||
|
|
||
| ### A field's data type has changed |
There was a problem hiding this comment.
@psFried would the UI show that schema evolution dialog option (like with the changed key & projections) in this case?
There was a problem hiding this comment.
Technically, it depends on whether or not the connector permits the change. If the connector says it's OK, then we won't show any errors or an evolution dialog. But if the connector rejects the change, then we will. It can be a little nuanced, but some general guidelines are:
- materializations to S3 or webhooks will generally tolerate most any change
- database materializations will generally reject most changes to materialized columns, except for dropping
NOT NULLconstraints - If a given field isn't part of the field selection, then any change will be allowed by the connector (even if it's not a good idea for other reasons)
But yeah, probably the most common scenario would be that changing a field type would result in the UI showing the schema evolution dialog.
psFried
commented
Nov 3, 2023
psFried
commented
Nov 3, 2023
oliviamiannone
approved these changes
Nov 6, 2023
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.
Updates some existing concepts pages to add docs on new schema evolution features. Also adds a new concepts page on evolutions, and a new guide outlining how to handle some common schema evolution scenarios.
Keeping this as a draft for now, so we can look at the preview and iterate.
This change is