You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@seatunnel.apache.org by "yzeng1618 (via GitHub)" <gi...@apache.org> on 2026/01/04 01:34:58 UTC

[PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

yzeng1618 opened a new pull request, #10266:
URL: https://github.com/apache/seatunnel/pull/10266

   <!--
   
   Thank you for contributing to SeaTunnel! Please make sure that your code changes
   are covered with tests. And in case of new features or big changes
   remember to adjust the documentation.
   
   Feel free to ping committers for the review!
   
   ## Contribution Checklist
     - Make sure that the pull request corresponds to a [GITHUB issue](https://github.com/apache/seatunnel/issues).
     - Name the pull request in the form "[Feature] [component] Title of the pull request", where *Feature* can be replaced by `Hotfix`, `Bug`, etc.
     - Minor fixes should be named following this pattern: `[hotfix] [docs] Fix typo in README.md doc`.
   -->
   
   ### Purpose of this pull request
   
   <!-- Describe the purpose of this pull request. For example: This pull request adds checkstyle plugin.-->
   
   This PR introduces a new sink option `file_exists_mode` for File connectors to control what happens when the target file already exists during commit (rename temp -> target): `OVERWRITE` (default) / `SKIP` / `FAIL`. It also ensures `FAIL` mode fails the job on commit, updates the EN/ZH docs, and adds unit + HDFS E2E coverage
   
   ### Does this PR introduce _any_ user-facing change?
   Yes. New optional config `file_exists_mode` (default `OVERWRITE`, so behavior is unchanged unless configured).
   <!--
   Note that it means *any* user-facing change including all aspects such as the documentation fix.
   If yes, please clarify the previous behavior and the change this PR proposes - provide the console output, description and/or an example to show the behavior difference if possible.
   If possible, please also clarify if this is a user-facing change compared to the released SeaTunnel versions or within the unreleased branches such as dev.
   If no, write 'No'.
   If you are adding/modifying connector documents, please follow our new specifications: https://github.com/apache/seatunnel/issues/4544.
   -->
   
   
   ### How was this patch tested?
   
   - Unit tests: `HadoopFileSystemProxyRenameFileTest`, `FileSinkAggregatedCommitterFileExistsModeTest`
   - E2E: `HdfsFileIT` with `fake_to_hdfs_file_exists_mode_*` configs
   
   <!--
   If tests were added, say they were added here. Please make sure to add some test cases that check the changes thoroughly including negative and positive cases if possible.
   If it was tested in a way different from regular unit tests, please clarify how you tested step by step, ideally copy and paste-able, so that other reviewers can test and check, and descendants can verify in the future.
   If tests were not added, please describe why they were not added and/or why it was difficult to add.
   If you are adding E2E test cases, maybe refer to https://github.com/apache/seatunnel/blob/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/connector-cdc-mysql-e2e/src/test/resources/mysqlcdc_to_mysql.conf, here is a good example.
   -->
   
   
   ### Check list
   
   * [ ] If any new Jar binary package adding in your PR, please add License Notice according
     [New License Guide](https://github.com/apache/seatunnel/blob/dev/docs/en/contribution/new-license.md)
   * [*] If necessary, please update the documentation to describe the new feature. https://github.com/apache/seatunnel/tree/dev/docs
   * [ ] If necessary, please update `incompatible-changes.md` to describe the incompatibility caused by this PR.
   * [ ] If you are contributing the connector code, please check that the following files are updated:
     1. Update [plugin-mapping.properties](https://github.com/apache/seatunnel/blob/dev/plugin-mapping.properties) and add new connector information in it
     2. Update the pom file of [seatunnel-dist](https://github.com/apache/seatunnel/blob/dev/seatunnel-dist/pom.xml)
     3. Add ci label in [label-scope-conf](https://github.com/apache/seatunnel/blob/dev/.github/workflows/labeler/label-scope-conf.yml)
     4. Add e2e testcase in [seatunnel-e2e](https://github.com/apache/seatunnel/tree/dev/seatunnel-e2e/seatunnel-connector-v2-e2e/)
     5. Update connector [plugin_config](https://github.com/apache/seatunnel/blob/dev/config/plugin_config)


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "LiJie20190102 (via GitHub)" <gi...@apache.org>.
LiJie20190102 commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3712687757

   > `DataSaveMode`
   
   +1, @yzeng1618,  Could you explain the difference between `file_exists_mode`, `DataSaveMode`, and `SchemaSaveMode`? Does the combined functionality of `DataSaveMode` and `SchemaSaveMode` include `file_exists_mode`?


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "chl-wxp (via GitHub)" <gi...@apache.org>.
chl-wxp commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3712921998

   > `OVERWRITE` (default) / `SKIP` / `FAIL`
   
   Why should we do this in the submission phase? I think what `OVERWRITE (default) / SKIP / FAIL` does is consistent with the final behavior of `DataSaveMode`.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3736587836

   Then let's close this PR for now, and we can resubmit it when there's a need later.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3712851506

   > This looks functionally redundant with the existing SaveMode design. For file connectors, SeaTunnel already has: `DataSaveMode` to control how existing data (files) is handled `SchemaSaveMode` to control how the target path / directory is handled File existence is a data-level concern and should be covered by DataSaveMode. Introducing a separate file_exists_mode duplicates this responsibility and fragments behavior control, making the File connector inconsistent with other sinks. It would be preferable to reuse or extend the existing SaveMode mechanism rather than adding a new, connector-specific option.
   
   SchemaSaveMode/DataSaveMode are executed pre-write and work at a directory (“table”) level via the Catalog: create/drop/truncate the target path or check whether the directory already contains data files. file_exists_mode is applied at the 2PC commit stage, when we rename/move a temp file under tmp_path to the final target file. It specifically controls the behavior when the final target file name already exists (e.g., single_file_mode, fixed file_name_expression, or binary with relativePath). So it’s not duplicating the existing SaveMode; it complements a commit-time, single-file conflict that SaveMode currently can’t express.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "chl-wxp (via GitHub)" <gi...@apache.org>.
chl-wxp commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3709459225

   This looks functionally redundant with the existing SaveMode design.
   For file connectors, SeaTunnel already has:
   `DataSaveMode` to control how existing data (files) is handled
   `SchemaSaveMode` to control how the target path / directory is handled
   File existence is a data-level concern and should be covered by DataSaveMode. Introducing a separate file_exists_mode duplicates this responsibility and fragments behavior control, making the File connector inconsistent with other sinks.
   It would be preferable to reuse or extend the existing SaveMode mechanism rather than adding a new, connector-specific option.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 closed pull request #10266: [Feature] [connector-file] Support file_exists_mode for file sink commit
URL: https://github.com/apache/seatunnel/pull/10266


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3712983852

   > > `DataSaveMode`
   > 
   > +1, @yzeng1618, Could you explain the difference between `file_exists_mode`, `DataSaveMode`, and `SchemaSaveMode`? Does the combined functionality of `DataSaveMode` and `SchemaSaveMode` include `file_exists_mode`?
   
   
   
   > > `OVERWRITE` (default) / `SKIP` / `FAIL`
   > 
   > Why should we do this in the submission phase? I think what `OVERWRITE (default) / SKIP / FAIL` does is consistent with the final behavior of `DataSaveMode`.
   
   The reason file_exists_mode is placed at the commit phase (2PC rename/move of temporary files to the final path) is that only at this phase will the "temporary files" be finalized as "final filenames" in the target directory. Therefore, name conflicts occur at the file level, and deterministic decisions of OVERWRITE/SKIP/FAIL can only be made during the rename operation.
   Here is an example to illustrate:
   Scenario Initialization
   Source directory: /tmp/source contains test1.txt and test2.txt.
   Target directory: /tmp/target already has an existing test1.txt (old file), while test2.txt does not exist.
   Configuration: path=/tmp/target (the write destination directory). Writes are first persisted to tmp_path, then renamed to /tmp/target/... during commit.
   
   1. Observing only data_save_mode (Takes effect before task starts, directory-level)
   
   - DROP_DATA: Clear/recreate /tmp/target before task startup (the old test1.txt will be deleted) → No conflicts occur when writing test1.txt and test2.txt during commit → Result: The target directory contains the new test1.txt + test2.txt.
   
   - APPEND_DATA: Do not modify /tmp/target before task startup (the old test1.txt remains) → A conflict "the test1.txt to be written already exists" will be encountered during commit, but APPEND_DATA itself does not define how to handle single-file name conflicts → The decision to overwrite/skip/fail depends on file_exists_mode.
   
   - ERROR_WHEN_DATA_EXISTS: Check /tmp/target before task startup; fail if any data files exist (there is currently test1.txt) → Fail directly without proceeding to the write/commit phase.
   
   2.  Observing only file_exists_mode (Takes effect during commit, file-level; assuming data_save_mode=APPEND_DATA)
   
   - OVERWRITE: When renaming test1.txt during commit and detecting the existing old file → Delete the old test1.txt first, then rename the temporary file to overwrite it; test2.txt is committed normally → Result: The target directory contains the new test1.txt + test2.txt.
   
   - SKIP: When detecting the existing test1.txt during commit → Retain the old test1.txt, delete the temporary test1.txt, and mark the commit as successful; test2.txt is committed normally → Result: The target directory contains the old test1.txt + new test2.txt.
   
   - FAIL: When detecting the existing test1.txt during commit → Throw an error and fail immediately (used to explicitly prevent overwrites).


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "yzeng1618 (via GitHub)" <gi...@apache.org>.
yzeng1618 commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3712853694

   > > `DataSaveMode`
   > 
   > +1, @yzeng1618, Could you explain the difference between `file_exists_mode`, `DataSaveMode`, and `SchemaSaveMode`? Does the combined functionality of `DataSaveMode` and `SchemaSaveMode` include `file_exists_mode`?
   
   Differences:
   
   - SchemaSaveMode: directory/path-level, executed pre-write (create/recreate/error/ignore).
   
   - DataSaveMode: data-in-directory-level, executed pre-write (truncate directory, append, or fail if the directory already has data files).
   
   - file_exists_mode: commit-time, single-target-file-level behavior when renaming a temp file to the final file name (SKIP/OVERWRITE/FAIL on name collision).
   
   So SchemaSaveMode + DataSaveMode does not include file_exists_mode; they don’t cover commit-time rename conflicts for a specific final file name.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Feature] [connector-file] Support file_exists_mode for file sink commit [seatunnel]

Posted by "TyrantLucifer (via GitHub)" <gi...@apache.org>.
TyrantLucifer commented on PR #10266:
URL: https://github.com/apache/seatunnel/pull/10266#issuecomment-3719240632

   -1, From my perspective, the design of this feature is too customized. In actual production scenarios, the path written for each task is different, and the previously existing save mode feature can fully cover the requirements. The community version of the connector needs to have sufficiently universal functionality.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: commits-unsubscribe@seatunnel.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org