Repository navigation
DOCS: Improve Documentation on Write Support #1008
Description
Feature Request / Improvement
We currently have Write support through two modes:
- through the Table API
- through the Transaction API
We also have support for different modes of writes like:
- append
- overwrite
- delete
Which make use of different arg parameters.
It would be great to update our docs to describe each of these operations and API modes explicitly in detail as separate subsections, and pad in any missing details (like the use of overwrite_filter in overwrite)
Activity
guitcastro commentedon Aug 7, 2024
@sungwy When using overwrite how can we compare fields between source and target? like:
kevinjqliu commentedon Aug 9, 2024
someone asked about merge/upserts use cases in the slack channel as well, similar to
overwrite_filterkevinjqliu commentedon Aug 13, 2024
Examples of
overwrite_filteriamvyshnavi commentedon Feb 5, 2025
Hi, I am new to open source and would love to contribute to this issue. Can I work on this?
shrutisachan08 commentedon Feb 6, 2025
Hii, I would like to work on this. I can update documentation by adding separate subsections for each write mode(append, overwrite, delete). I can insert some examples like including about overwrite_filter usage. Please let me know if there are any formatting details you would like me to include. Please assign me this issue.
github-actions commentedon Aug 6, 2025
This issue has been automatically marked as stale because it has been open for 180 days with no activity. It will be closed in next 14 days if no further activity occurs. To permanently prevent this issue from being considered stale, add the label 'not-stale', but commenting on the issue is preferred when possible.
pramila-bishnoi commentedon Nov 15, 2025
Hi! I am new to contributing to PyIceberg and would like to pick up this documentation task to add sections for append, overwrite, and upsert functionality as mentioned by the previous contributors. I will start setting up my environment now. Please consider assigning this to me.
pramila-bishnoi commentedon Nov 16, 2025
Hi ,
I had asked earlier about taking on this documentation issue but didn't hear back, so I went ahead and completed the main task to keep things moving.
The core documentation (adding all write operations to api.md) is now finished.
api.md
(attached file)
I included the full documentation blocks for overwrite(), delete(), dynamic_partition_overwrite(), upsert(), and the Transaction API.
Could you please review the changes I made in the attached api.md file? I want to make sure the content is correct before proceeding.
Proposed Final Change:- I haven't done this yet, but I recommend adding cross-links from the headings (like append()) to the relevant Python API reference documentation. This greatly improves user experience and navigation.
Should I add these cross-links??
Is there anything else you think I should add or change in the file?
Once confirmed, i'll create a new branch, and open a formal PR.
Thanks !
pramila-bishnoi commentedon Nov 16, 2025
@kevinjqliu
kevinjqliu commentedon Nov 18, 2025
hey @pramila-bishnoi feel free to open a PR so its easier to review the changes.
pramila-bishnoi commentedon Nov 23, 2025
Hi @kevinjqliu , just checking in on this PR. Is there anything else I can provide on my end, or any ETA on when it might be reviewed? Thanks!
docs: improve Write to a table section (apache#1008)
github-actions commentedon Jun 13, 2026
This issue has been automatically marked as stale because it has been open for 180 days with no activity. It will be closed in next 14 days if no further activity occurs. To permanently prevent this issue from being considered stale, add the label 'not-stale', but commenting on the issue is preferred when possible.
Zhuoxi2000 commentedon Jul 10, 2026
Opened #3647 restructuring the write docs into per-operation subsections + documenting the Transaction write mode
iSparshP commentedon Aug 18, 2026
Hi, I would like to pick this up.
Looks like #3647 took a run at this, but got auto-closed by the stale bot for inactivity, so I don't think anyone's actively on it right now. @Zhuoxi2000 @pramila-bishnoi if either of you is still working on it let me know, otherwise happy to take it forward.
I am going to document the Table API and Transaction API write paths as separate subsections, cover append / overwrite / delete under each, and fill in overwrite_filter since that's the one that's underdocumented today. I will reuse the structure from #3647 where it holds up and open a PR for review.
pramila-bishnoi commentedon Aug 18, 2026
Hi @iSparshP, I was working on this earlier and had opened PR #2770, but it wasn't reviewed and was eventually closed due to inactivity. I'm not actively working on it anymore, so please feel free to take it forward. Thanks!
iSparshP commentedon Aug 19, 2026
Thanks @pramila-bishnoi, appreciate the handoff. I will go through #2770 and #3647 to reuse what's already there and build on top. Will open a PR.