LlamaIndexllama-index-core 0.14 · Python 3.10+
Dashboard
0%
1
Curious builder0 XP earned · 300 to level 2
0 daysFinish a lesson to begin
Badge collection0 of 6 unlocked
30 small wins to finish your pathNext lesson →

Updating documents: refresh and delete

refresh_ref_docs is a call that re-processes only the documents whose content changed, and delete_ref_doc removes one from the index.

Last updated: 28 Sep, 2026 · LlamaIndex 0.14

Policies change. An index must pick up edited files and drop deleted ones without a full rebuild, or it keeps quoting old rules.

Refreshing and deleting by document id

Loading with filename_as_id=True gives each document a stable id from its file name. That id is what lets the index recognise an edited file as the same document, and what you pass to delete one.

python
def load():
    return SimpleDirectoryReader("help", file_metadata=only_name,
                                 filename_as_id=True).load_data()

changed = index.refresh_ref_docs(load())     # re-process changed files
index.delete_ref_doc(doc_id, delete_from_docstore=True)   # remove one document

Editing a file, then refreshing

Change the refund policy on disk, then call refresh_ref_docs with a fresh load. It returns, per document, whether it changed.

python
with open("help/refunds.md", "w") as f:
    f.write("# Refunds\n\nYou can get a full refund within 60 days of delivery.\n")

changed = index.refresh_ref_docs(load())
print("changed:", changed)
Project files used on this pageThis lesson builds on a project from earlier lessons. The code below imports these files. Click a file to see its code, or follow the link to the lesson that wrote it. To run the code yourself, keep them in the same folder.
View the code here
help/lamps.md
# Lamps

The LMP-204 desk lamp has a known cable fault. Stop using a lamp with a damaged cable and we will replace it free of charge.

All lamps come with a two year guarantee against electrical faults.

Bulbs are not covered by the refund policy once they have been used.

The LMP-310 floor lamp needs a bulb with an E27 fitting, which is sold separately.
help/refunds.md
# Refunds

You can get a full refund within 30 days of delivery. The money goes back to the card you paid with within 5 working days of us receiving the item.

Items bought in a sale can be refunded too, but the delivery charge is not returned.

To start a refund, open the order in your account and choose Return an item. Print the label and drop the parcel at any post office.

Personalised items cannot be refunded unless they arrive damaged.
help/delivery.md
# Delivery

Standard delivery takes 3 to 5 working days and is free on orders over 40.

Express delivery arrives the next working day if you order before 2pm. It costs 6.

We deliver to the mainland only. Parcels to islands take 2 extra working days.

If a parcel has not arrived after 10 working days, contact us and we will send a replacement.

Refreshing after an edit

The whole program builds the index, edits the refund file, refreshes, and retrieves. The old 30-day text is gone.

Example
# --- refresh after an edit ---
with open("help/refunds.md", "w") as f:
    f.write("# Refunds\n\nYou can get a full refund within 60 days of delivery.\n")

changed = index.refresh_ref_docs(load())
print("changed:", changed)
retriever = index.as_retriever(similarity_top_k=1)
print(retriever.retrieve("How long do I have to ask for a refund?")[0].get_content().replace("\n", " "))

# --- delete a document ---
lamp_id = next(doc.doc_id for doc in load() if doc.metadata["file_name"] == "lamps.md")
index.delete_ref_doc(lamp_id, delete_from_docstore=True)
print([n.metadata["file_name"] for n in index.as_retriever(similarity_top_k=3).retrieve("LMP-204 cable fault")])

What refresh and delete changed

  • [False, False, True] means only the refund file changed, so only it was re-processed.
  • The retrieved text is now the 60-day policy, so the edit reached the index.
  • After the delete, the lamp question retrieves only unrelated files, because every chunk from the lamp document was removed.

With a cutoff from Refusing when nothing fits: similarity cutoffs, a lamp question after the delete becomes a refusal instead of an outdated answer.

Rebuild vs refresh and delete

ChangeFull rebuildrefresh / delete
One file editedRe-embeds everythingRe-embeds only that file
One file removedRe-embeds everythingDrops that document's chunks

When you refresh or delete

  • A scheduled sync that picks up edited help articles.
  • Removing a document the source system no longer has.
  • Deleting a record for legal reasons, which must leave the index too.
Watch out. Without filename_as_id=True, each load gives documents fresh ids, so refresh_ref_docs cannot match an edited file to the one already indexed and re-adds it as new. Set the id, or the index fills with duplicates.
Try it yourself
  • Add a new file to help and call refresh_ref_docs. What does it return for the new file?
  • Call refresh_ref_docs twice without changes and read both results.
  • Delete a document, then persist and reload the index, and check the chunks are gone.
PreviousPersisting an index: not embedding twice

You understood something today that you didn't yesterday.