SimpleDirectoryReader: loading a folder of documents

SimpleDirectoryReader is a reader that turns every file in a folder into a Document, and the metadata it attaches travels with every chunk from then on.

Last updated: 28 Sep, 2026 · LlamaIndex 0.14

So far the documents were typed into the code. Real help pages live in files, so this lesson loads the shop's help folder from disk, which is where the running example gets its content for the rest of the course.

The help-centre folder

The help folder holds three Markdown files. Here is one; the other two follow the same pattern, with delivery times and the shop's two lamps:

# 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.

Loading the folder

Point the reader at the folder and call load_data:

from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader("help").load_data()

# 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.

# 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.

Loading the folder into Documents

from llama_index.core import SimpleDirectoryReader

documents = SimpleDirectoryReader("help").load_data()
print(len(documents))
print(sorted(documents[0].metadata))

3
['creation_date', 'file_name', 'file_path', 'file_size', 'file_type', 'last_modified_date']

Reading the loaded documents

• Three Documents come back, one per file in the folder.
• The reader fills in metadata by itself: the file's name, type, size and dates, and its full path on your computer.
• That path is the problem: unless a key is excluded, its value goes into the embedded text and the model's prompt, so a machine path would leak into both.

Choosing the metadata with a function

Give the reader a file_metadata function that decides what each document carries. This one keeps the file name and drops everything else:

import os


def only_name(path):
    return {"file_name": os.path.basename(path)}

Keeping only the file name

import os

from llama_index.core import SimpleDirectoryReader


def only_name(path):
    return {"file_name": os.path.basename(path)}


documents = SimpleDirectoryReader("help", file_metadata=only_name).load_data()

print(len(documents))
for document in documents:
    print(document.metadata)

3
{'file_name': 'delivery.md'}
{'file_name': 'lamps.md'}
{'file_name': 'refunds.md'}

Reading the trimmed metadata

• Each document now carries its file name and nothing about the machine it was loaded on.
• file_metadata is called with each file's path and returns the metadata dictionary for that file.
• The order follows the folder listing, so the files come back sorted by name.

Default metadata vs a metadata function

When to pass a metadata function

• Any time documents are loaded from a real path, so machine paths do not reach the model.
• When you want a stable key such as a document id or a section name for filtering later.
• When the folder mixes formats and you want the same metadata shape for all of them.

Related

• Previous: VectorStoreIndex: searching documents by meaning
• Next: Chunking documents with SentenceSplitter
• Reference: Loading data