Skip to content

LearnIngest & extract

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
A table with merged cells, flattened by dropping spans versus filling themThe source table has columns Scope, Case, and FY27 split into Rev and Margin. Scope and Case span both header rows, and Company spans two rows: plan, $43.0M, 20%; and forecast, $48.2M, 24%. London forecast is $6.5M and 18%. The answer to "forecast FY27 margin for the company" is the cell 24%. Flattened by dropping spans, four empty cells appear, and the forecast row reads only "forecast, $48.2M, 24%", with no scope and no column names. Flattened by filling spans, the header becomes FY27 Rev and FY27 Margin, Company is copied into the forecast row, and a chunk of that row reads "Scope: Company, Case: forecast, FY27 Rev: $48.2M, FY27 Margin: 24%".Source tablemerged cells: 3 row spans, 1 column spanScopeCaseFY27RevMarginCompanyplan$43.0M20%forecast$48.2M24%Londonforecast$6.5M18%Spans droppedpipe table: value kept in its first cellScopeCaseFY27RevMarginCompanyplan$43.0M20%forecast$48.2M24%Londonforecast$6.5M18%Spans filledvalues copied into every cell they coverScopeCaseFY27 RevFY27 MarginCompanyplan$43.0M20%Companyforecast$48.2M24%Londonforecast$6.5M18%QUESTIONForecast FY27 margin, company?Answer: 24%, read with 3 headersCHUNK FOR THE FORECAST ROW| | forecast | $48.2M | 24% |no scope, no column namesCHUNK FOR THE FORECAST ROWScope: Company · Case: forecastFY27 Rev: $48.2M · FY27 Margin: 24%
A cell only means something next to its headers, so flattening must keep them attached. Dropping the spans leaves empty cells (hatched), and a chunk of the forecast row no longer says which scope or which number is the margin. Filling the spans copies "Company" down and joins the stacked headers, so every row answers on its own.

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

  1. 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.
  2. 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.
  3. 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).

Sources

Jump to