Skip to main content
Version: 3.5

XLSXToDocument

Converts Excel files into documents.

Most common position in a pipelineBefore PreProcessors or right at the beginning of an indexing pipeline
Mandatory run variablessources: File paths or ByteStream objects
Output variablesdocuments: A list of documents
API referenceConverters
GitHub linkhttps://github.com/deepset-ai/haystack/blob/main/haystack/components/converters/xlsx.py
Package namehaystack-ai

Overview​

The XLSXToDocument component converts XLSX files into Haystack Documents with a CSV (default) or Markdown format. It takes a list of file paths or ByteStream objects as input and outputs the converted result as a list of documents. Optionally, you can attach metadata to the documents through the meta input parameter.

To see the additional parameters that you can specify with the component initialization, check out the API Reference.

Missing values​

When neither keep_default_na nor na_values is supplied in read_excel_kwargs, XLSXToDocument uses keep_default_na=False and na_values=[""]. This preserves literal strings such as "NA", "N/A", "NULL", and "None" while treating empty cells as missing. Missing values are rendered as blank cells unless you set table_format_kwargs={"na_rep": "<missing>"} for CSV or table_format_kwargs={"missingval": "<missing>"} for Markdown.

If you supply either option, the converter passes your NA settings to pandas unchanged and adds neither default. For example, read_excel_kwargs={"na_values": ["foo"]} treats "foo" and pandas' built-in NA strings as missing. Setting read_excel_kwargs={"keep_default_na": False} preserves those strings and keeps empty cells as empty strings unless you explicitly include "" in na_values. Setting na_filter=False disables missing-value detection entirely.

To restore pandas' previous default NA parsing, which also treats strings such as "NA" and "NULL" as missing, set read_excel_kwargs={"keep_default_na": True}.

Usage​

First, install the pandas, openpyxl, and tabulate packages to start using this converter:

shell
pip install pandas openpyxl
pip install tabulate

On its own​

python
from haystack.components.converters import XLSXToDocument

converter = XLSXToDocument()
results = converter.run(
sources=["sample.xlsx"],
meta={"date_added": datetime.now().isoformat()},
)
documents = results["documents"]
print(documents[0].content)
# ",A,B\n1,col_a,col_b\n2,1.5,test\n"

In a pipeline​

python
from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.converters import XLSXToDocument
from haystack.components.preprocessors import DocumentCleaner
from haystack.components.preprocessors import DocumentSplitter
from haystack.components.writers import DocumentWriter

document_store = InMemoryDocumentStore()

pipeline = Pipeline()
pipeline.add_component("converter", XLSXToDocument())
pipeline.add_component("cleaner", DocumentCleaner())
pipeline.add_component(
"splitter",
DocumentSplitter(split_by="sentence", split_length=5),
)
pipeline.add_component("writer", DocumentWriter(document_store=document_store))
pipeline.connect("converter", "cleaner")
pipeline.connect("cleaner", "splitter")
pipeline.connect("splitter", "writer")

pipeline.run({"converter": {"sources": file_names}})