Table extraction
Recovering a table's grid of rows, columns, headers and merged cells from a document, so every value stays attached to the row and column that give it meaning.
In DocSlurpIllustrated explainer
On this page
The problem: the answer is in a cell
Page 14 of growth-plan-2027.pdf has a table for the margin plan. Someone asks, “What is the forecast FY2027 margin for the company?” The answer is a single cell: “24%”.
That cell means nothing by itself. It only becomes an answer when it is read together with three headers: the row says “Company” and “forecast”, the column says “Margin”, and above that, “FY27”. Table extraction is the job of keeping every cell attached to the labels that give it meaning, through extraction, conversion, chunking and retrieval.
Three problems in one
- Detection. Where on the page is the table? This is part of layout analysis, and it fails most often on borderless tables, which look like columns of short paragraphs.
- Structure recognition. How many rows and columns are there, which rows are headers, and which cells are merged across rows or columns? Models such as the Table Transformer, trained on the PubTables-1M dataset, predict rows, columns, header cells and spanning cells from the page image.
- Cell content. What text is in each cell? From the text layer if there is one, from OCR if not.
The second step is where most of the damage happens, and merged cells are the usual culprit.
Merged cells, flattened wrong
The table has merged cells. “FY27” spans the Rev and Margin columns, “Scope” and “Case” span both header rows, and “Company” spans two body rows, plan and forecast. A common extractor output, a Markdown pipe table, cannot express either span, so it keeps each merged value in its first cell and leaves the rest empty:
| Scope | Case | FY27 | |
| | | Rev | Margin |
| Company | plan | $43.0M | 20% |
| | forecast | $48.2M | 24% |
| London | forecast | $6.5M | 18% |
It looks fine to a person, who fills in the blanks by eye. A retrieval system does not have eyes. When this table is chunked, the forecast row can easily end up in a chunk on its own, or in an embedding where the blank cell carries no meaning: | | forecast | $48.2M | 24% |. Nothing in that text says “Company”, and nothing says which number is revenue and which is margin. The answer is in the index, and no query can reach it.
Flattened right
There are two honest ways to keep the structure.
Keep the spans. HTML tables can say what Markdown cannot. <td rowspan="2">Company</td> and <th colspan="2">FY27</th> preserve the grid exactly, and language models read HTML tables well.
Fill the spans. Copy each merged value into every cell it covers, and join stacked headers into one:
| Scope | Case | FY27 Rev | FY27 Margin |
| Company | plan | $43.0M | 20% |
| Company | forecast | $48.2M | 24% |
| London | forecast | $6.5M | 18% |
Now every row stands alone. For retrieval you can go one step further and write each row as a record: “Scope: Company; Case: forecast; FY27 Rev: $48.2M; FY27 Margin: 24%”. A chunk containing just that line still answers the question.
Check it by hand with the figure: the original grid has 4 columns and 5 rows (2 header rows, 3 body rows). “Company” covers column 1 of rows 3 and 4; “FY27” covers columns 3 and 4 of row 1. Fill the spans and merge the two header rows into one, and you get 4 rows of 4 cells: 16 cells, none empty.
Where it breaks
- Borderless and whitespace tables. Columns aligned only by spacing are guessed from gaps. One long cell that crosses a gap shifts every value after it into the wrong column.
- Tables across pages. The header repeats on page 13, or doesn’t. Without stitching, the second half is a table with no headers.
- Nested headers. Three header rows with spans at each level make “which headers apply to this cell” a real computation, not a lookup.
- Tables as images. A screenshot of a spreadsheet pasted into a report has no text layer at all. It needs OCR plus structure recognition, or a vision model.
- Plausible errors. A vision-language model can transcribe a table beautifully and still shift one column or invent one value. A wrong number in a well-formed table looks exactly like a right one. Check row and column counts, and totals where the table has them.
- Huge tables. A 2,000-row table won’t fit in one chunk. Split it by rows, and repeat the headers in every piece, or each piece becomes the blank-cell problem again.
Spreadsheets are different
expansion-forecast.xlsx already stores a grid: every value has a sheet and an A1 address, and merged ranges are recorded explicitly. Nothing needs to be detected or recognized. Read the structure from the file instead of rendering it to a picture and recovering it again. See Office file formats.
In DocSlurp
In DocSlurp
Tables are kept as HTML when preservation is on, so rowspan and colspan survive into Markdown (core/worker/src/lib/extracted-markdown.ts). Oversized tables are chunked as cell records labeled with row, column and span, never sliced mid-cell (core/worker/src/pipeline/table-chunking.ts). Table-heavy PDF pages also trigger Unstructured hi_res layout parsing (core/worker/src/stages/extract-markdown.ts).