-
Notifications
You must be signed in to change notification settings - Fork 4.9k
docs: expand Snowflake v4 migration guide with detailed instructions #69729
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 1 commit
705d340
2e8bdd5
0735277
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -24,7 +24,17 @@ If you _only_ interact with the raw tables, enable the `Disable Final Tables` op | |
|
|
||
| 2. Open your **Snowflake** connector. | ||
|
|
||
| 3. <!-- Devin: fill out the rest of these steps to use Disable Final Tables from Snowflake v3 --> | ||
| 3. Click **Edit configuration**. | ||
|
|
||
| 4. Open the **Advanced** section. | ||
|
|
||
| 5. Turn on **Disable Final Tables**. | ||
|
|
||
| 6. Click **Save**. | ||
|
|
||
| :::note | ||
| After upgrading to version 4, this setting appears as **Legacy raw tables** and should remain enabled. | ||
|
||
| ::: | ||
|
|
||
| #### If you interact with both raw and final tables | ||
|
|
||
|
|
@@ -34,25 +44,62 @@ If you interact with both the raw _and_ final tables, this use case is no longer | |
|
|
||
| 2. For each Snowflake destination you have, add an identical second Snowflake destination. | ||
|
|
||
| 3. Ensure each pair of Snowflake connectors have opposite settings for <!-- Devin: fill out the rest of this step to use Disable Final Tables from Snowflake v3 --> | ||
| 3. Ensure each pair of Snowflake connectors have opposite settings for **Disable Final Tables** (in version 3) or **Legacy raw tables** (in version 4). One connector should have this setting enabled, and the other should have it disabled. | ||
|
||
|
|
||
| 4. Configure distinct default schemas for each destination to avoid table name collisions. | ||
|
||
|
|
||
| 5. Update your connections to point to the appropriate destination: | ||
| - Connections that need raw tables only should target the destination with **Disable Final Tables** or **Legacy raw tables** enabled. | ||
|
||
| - Connections that need final tables should target the destination with this setting disabled. | ||
|
||
|
|
||
| 4. <!-- Devin: fill out the rest of this process --> | ||
| 6. Run test syncs on both destinations to verify outputs: | ||
| - The raw-only destination should write only to the internal schema (default `airbyte_internal`). | ||
| - The standard destination should write only final tables to the target schema. | ||
|
|
||
| 7. After verifying that both destinations work correctly, continue running both connections in parallel going forward. | ||
|
|
||
| <MigrationGuide /> | ||
|
|
||
| ### Optional: clean up legacy raw tables | ||
|
|
||
| The version 4.0 connector doesn't automatically remove tables created by earlier versions. After upgrading to version 4 and verifying your data, you can optionally remove the old raw tables. | ||
|
|
||
| For most users, You can find the raw tables <!-- Devin: where? -->. The names match the pattern <!-- Devin: what are the tables and schemas called? --> | ||
| For most users, you can find the raw tables in the schema configured as **Airbyte Internal Table Dataset Name** (which defaults to `airbyte_internal`). If you customized this setting, look in that schema instead. | ||
|
|
||
| The table names match these patterns depending on which version created them: | ||
|
|
||
| - **Version 2/3 (Typing and Deduping)**: `raw_{namespace}__{stream}` (for example, `airbyte_internal.raw_public__users`) | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🚫 [vale] reported by reviewdog 🐶 |
||
| - **Version 4 (Legacy raw tables mode)**: `{namespace}_raw__stream_{stream}` (for example, `airbyte_internal.public_raw__stream__users`) | ||
|
|
||
| Note: The number of underscores between `raw` and `stream` may vary depending on the longest underscore sequence in your namespace and stream names. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
|
|
||
| :::note | ||
| Version 4 of the Snowfalke destination uses the `airbyte_internal` database for temporary scratch space (for example, streams running in dedup mode, truncate refreshes, and overwrite syncs). Dropping the entire `airbyte_internal database` can interrupt active syncs and cause data loss. Only drop the specific raw tables you no longer need. | ||
| Version 4 of the Snowflake destination uses the `airbyte_internal` schema for temporary scratch space (for example, streams running in dedup mode, truncate refreshes, and overwrite syncs). Dropping the entire `airbyte_internal` schema can interrupt active syncs and cause data loss. Only drop the specific raw tables you no longer need. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 🚫 [vale] reported by reviewdog 🐶 |
||
| ::: | ||
|
|
||
| To remove the old raw tables: | ||
|
|
||
| <!-- Devin: SQL query to delete a raw table in Snowflake --> | ||
| 1. **Pause or allow active syncs to complete** before dropping any tables to avoid interrupting data transfers. | ||
|
|
||
| 2. **List candidate raw tables** to identify which tables to remove: | ||
|
|
||
| ```sql | ||
| -- For Version 2/3 raw tables: | ||
| SHOW TABLES IN SCHEMA <DATABASE>.<INTERNAL_SCHEMA> LIKE 'RAW\_%'; | ||
|
|
||
| -- For Version 4 legacy raw tables: | ||
| SHOW TABLES IN SCHEMA <DATABASE>.<INTERNAL_SCHEMA> LIKE '%_RAW__STREAM_%'; | ||
| ``` | ||
|
|
||
| Replace `<DATABASE>` with your Snowflake database name and `<INTERNAL_SCHEMA>` with your internal schema name (default `airbyte_internal`). | ||
|
|
||
| 3. **Drop specific raw tables** you no longer need: | ||
|
|
||
| ```sql | ||
| DROP TABLE IF EXISTS <DATABASE>.<INTERNAL_SCHEMA>.<TABLE_NAME>; | ||
| ``` | ||
|
|
||
| Replace `<TABLE_NAME>` with the specific table name you want to remove. Use fully qualified names (database.schema.table) to avoid ambiguity. | ||
|
|
||
| ## Upgrading to 3.0.0 | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can you check these UI steps? They don't appear to be correct to me.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for catching this! I based the UI steps on the v4 spec placement, but I don't have access to verify the exact v3 UI flow. Could you confirm:
I can update the steps once I know the correct v3 UI flow, or I can make them more location-agnostic if the exact path varies.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the clarification! I've updated the steps to:
disable_type_dedupefield had"group": "advanced")The updated steps are now:
Pushing this change now.