How to Fix Messy Table Extraction in an Unstructured Ingestion Pipeline
Table extraction in Unstructured fails in a predictable shape: cell text survives but row and column structure collapses into one long string per table. The fix is three things together — hi_res strategy, the table inference model, and keeping text_as_html instead of the plain text field.
Do only one of those and you get halfway results. Unstructured needs all three for tables that are actually queryable.
Why do tables come out as one blob of text?
Because the default text layer of a PDF has no concept of rows. It stores characters with coordinates, and a naive extractor reads them in reading order, which walks across a row and then into the next row — but a merged cell or a two-line header breaks that walk.
The fast strategy reads the text layer directly and inherits the flaw. hi_res runs a layout model that draws boxes around tables first, then treats each box as a unit. That box is what preserves structure.
What settings actually change table output?
strategy="hi_res"— non-negotiable for tables.infer_table_structure=True— the flag that generatestext_as_html. Without it, tables come back as plain text only.pdf_infer_table_structure=Trueon older releases — the same idea under the previous parameter name. Check your version; recent versions use the unified name.languages=["eng"]— narrower language sets improve OCR speed on scans, but omitting your actual language degrades character recognition noticeably.
A working call:
els = partition(
filename="filing.pdf",
strategy="hi_res",
infer_table_structure=True,
languages=["eng"],
)
tables = [e for e in els if e.category == "Table"]
Expect roughly 20–40% slower runtime with table inference on. On a 200-page filing that is a few extra minutes, not hours.
How do you keep table structure in your chunks?
Treat each table as one atomic chunk. Two rules:
- Chunk on
text_as_html, never ontext. The HTML keeps row and cell tags so an LLM can read rows later. - Store the table’s page number and the nearest
Titleelement text with the chunk. Retrieval without a section label returns tables nobody can cite.
Some pipelines size chunks by character count. A big financial table can exceed 4,000 characters and gets split mid-row. Raise the ceiling for table chunks specifically, or exclude tables from the standard chunker and handle them in a separate branch.
What does a good versus bad extraction look like?
Bad output has rows merged: “Revenue 2024 2025 Q1 12.4 13.1 Q2 12.9 14.0” as one string. You cannot split that reliably — the delimiters are spaces and the values are ambiguous.
Good output is a table element whose text is roughly aligned and whose text_as_html has 5 row elements with 3 cells each. Spot-check by counting row tags against the visual row count in the source page.
| Symptom | Likely cause | Fix |
|---|---|---|
| One string per table | fast strategy |
Switch to hi_res |
| No HTML in output | Missing infer_table_structure |
Add the flag |
| Columns shifted | Ruling lines missing | Try image-based OCR fallback |
| Rows split across chunks | Chunker size too low | Exempt tables from chunking |
Which documents still break the parser?
Four categories, in order of how often they bite:
Rotated or landscape pages. A 90-degree rotated table confuses box detection. Pre-rotate in a preprocessing step.
Tables with no ruling lines. Whitespace-separated tables are detected less reliably than bordered ones. If your corpus is full of them, test 20 pages before promising anything downstream.
Nested tables inside a main table. Rare in business docs, common in regulatory filings. Expect flattening.
Hand-annotated corrections. Overprinted text and handwriting produce duplicated or garbled cells.
Scanned tables add a fourth variable: OCR quality. At 200 DPI the numbers are usually right; at 150 DPI decimal points drop out. Render scans at 300 DPI before they reach the pipeline.
When is Unstructured the wrong tool for tables?
If tables are the only thing you care about, a dedicated table extractor will beat a general document parser on accuracy. Unstructured’s advantage is doing prose, lists, and tables in one pass so your chunks stay consistent.
For a pipeline that is 90% tables — invoices, bank statements, lab results — the schema-based tools are the better fit. Schema-based extraction knows what an invoice looks like; Unstructured does not.
Good fit: mixed-content corpora where tables sit inside narrative documents, and teams that need one parser for PDFs, DOCX, and HTML.
Poor fit: table-only workloads, heavy nested-table corpora, and anyone who cannot afford a few minutes per hundred pages.
Quick Summary
- Tables need
hi_resplusinfer_table_structure=True— one without the other gives half the fix. - Always chunk on
text_as_html, not the plain text field. - Table inference adds roughly 20–40% runtime; plan for it.
- Rotated pages and borderless tables remain weak spots — test 20 pages per new source.
- If tables are 90% of your corpus, a schema-based extractor wins.
