Back to Blog
Stacked printed documents representing complex PDFs parsed before RAG ingestion

RAG Document Parsing: Handling Complex PDFs and Tables

10 min read

RAG document parsing can fail long before retrieval or generation. A PDF parser may return fluent text while mixing two columns, separating table values from their headers, or skipping an image-only page. The ingestion job can finish and produce embeddings anyway. Later, the answer cites a source whose indexed evidence no longer matches the page.

The fix is not a larger chunk window. Put a parsing gate before chunking and embedding. Route each document through an appropriate extraction method, preserve its structure and source coordinates, reject suspicious output, and test representative documents as fixtures. This guide shows the implementation sequence and the checks that tell you whether the indexed text still means what the source meant.

Why clean extracted text can still be wrong

PDF is a page-description format, not a promise that text is stored in reading order. A page can contain individually positioned characters, images, text layers from OCR, forms, and tables. Extracting every visible token does not reconstruct the relationships among those tokens. The practical failures described in Unstract's analysis of PDF extraction for RAG include reading-order errors, tables, scans, and documents that need several extraction methods.

The damage usually appears in one of four forms:

  1. A two-column report becomes alternating lines from the left and right columns.
  2. A table's header, row label, and value land in separate chunks, so the retrieved value has no meaning.
  3. A scan has no useful native text layer, or an embedded diagram contains the only explanation of a process.
  4. Headings, list nesting, footnotes, and captions become flat paragraphs. The chunker can no longer see the original boundaries.

These are parsing failures, not model failures. Running an evaluator only after answer generation makes diagnosis expensive because the bad answer is several stages removed from the damaged source. Inspect and gate the parsed representation before it reaches the embedding queue.

Define a parsed document contract

Give every parser the same output contract instead of accepting arbitrary Markdown or plain text. A compact internal schema can preserve meaning and provenance without coupling the rest of the pipeline to one extraction library.

A useful element record includes:

  • a stable document ID and source version
  • page number and element sequence
  • element type, such as title, heading, paragraph, list item, table, caption, or image description
  • normalized text
  • source coordinates or another source-span locator when the parser provides one
  • parent heading path
  • extraction method and parser version
  • confidence or warning fields where available
  • a content hash for replay and deduplication

The Microsoft Document Intelligence layout model returns document structure that includes text and tables across PDF, image, and Office formats. Docling similarly exposes page layout, reading order, tables, code, formulas, images, and OCR in a structured document representation. Those capabilities are most useful when you retain them instead of immediately flattening the result into one string.

Keep the original file immutable and link every element back to it. A citation should be able to identify the source document, version, page, and element span. This makes visual inspection possible when a retrieval result looks suspicious. It also prevents a later parser upgrade from silently changing the meaning of an existing chunk under the same identity.

Route by document and page, not file extension alone

A .pdf suffix says little about extraction difficulty. One file may contain clean digital text, another may be a scan, and a third may combine both. Inspect first, then choose the route from properties you can observe.

Check at least these signals:

  • whether the file has a usable text layer
  • characters and words per page
  • image coverage per page
  • font, block, and coordinate availability
  • signs of multiple columns
  • detected tables or forms
  • encoding errors and replacement characters
  • large disagreement between rendered content and extracted text

Use native extraction for simple digital documents when it preserves order and structure. Add layout analysis for multi-column pages, forms, tables, and positioned content. Use OCR for pages without a dependable text layer. Mixed documents should be routed page by page rather than forcing one mode across the whole file.

The Unstructured partitioning documentation makes this distinction explicit for PDFs with fast, hi_res, and ocr_only strategies, plus table-structure inference. Treat these as routing choices with different costs and failure modes, not quality levels where the most expensive option always wins.

A routing policy can remain small: 

inspect(document)
for page in document.pages:
    if page.native_text_is_complete and page.layout_is_simple:
        elements = native_extract(page)
    elif page.needs_layout_reconstruction:
        elements = layout_extract(page)
    else:
        elements = ocr_extract(page)

    validate_page(page, elements)
    persist(elements, parser_name, parser_version)

Record the selected route and the reason beside the parser output rather than burying the choice inside a vendor SDK call. If an update changes the output, the routing record identifies the fixtures and indexed documents that need replay.

Preserve tables as relationships

Tables often fail because pipelines treat them as visually aligned paragraphs. A useful table representation must keep the header path attached to each value. For a simple table, serialize each row with explicit column names. For grouped headers, carry both levels. For split tables across pages, retain the repeated header and a shared table identity.

Store two views when useful:

  • a structured table object for deterministic inspection and downstream tools
  • a retrieval-oriented text form that repeats the row and column context around each value

A twenty-page financial table is too large to embed as one unit, but fixed character splits destroy its structure. Partition it by logical row groups. Repeat the table title, headers, units, and relevant section heading in each retrieval unit. Keep dependent rows together and record that grouping in chunk metadata.

The Microsoft layout model and Docling both document table extraction as part of layout understanding. That does not remove the need for application-level verification. Test merged cells, blank cells, repeated headers, wrapped values, footnotes, and tables continued on later pages. A parser can detect a table correctly while your serializer still destroys its relationships.

Chunk from semantic elements

Chunking should consume the normalized element tree, not raw parser text. Assemble chunks under heading paths and keep atomic structures intact. A caption should stay with its figure or table. A list should not lose its introductory sentence. A paragraph should not cross into the next section because a character counter had room left.

Set size limits as constraints after semantic grouping. If a section exceeds the model budget, split at paragraph or list boundaries and repeat enough heading context to make each part understandable. Record the ordered element IDs included in every chunk. That gives you a reversible path from retrieval result to parsed source.

This design also makes reprocessing safer. A parser upgrade can produce a new element tree, and a diff can show which source spans changed before you replace embeddings. Unchanged elements can retain stable identities. Changed or deleted elements can follow the update and tombstone process used by the index freshness pipeline.

Add quality gates before embedding

A successful parser call only means the program returned. Run inexpensive checks on every page and document, then quarantine output outside the expected bounds. The gate should keep the source and report a reason so an operator can review it.

Useful checks include:

  • empty output from a non-empty rendered page
  • implausibly low text coverage
  • replacement-character or control-character bursts
  • duplicated lines caused by overlapping text layers
  • a sudden reading-order jump between distant page regions
  • table rows with inconsistent cell counts
  • headings with no following content
  • OCR confidence below your accepted threshold
  • a large page-count mismatch
  • output that changes sharply when replayed with the same parser version

Thresholds must come from your own corpus. A slide deck, contract, and invoice have different expected densities. Start by labeling a representative fixture set, measure the signals, and set document-class-specific rules. Keep a review queue for ambiguous pages. Automatic rejection without a repair path turns visible parser defects into invisible coverage gaps.

Parser implementations also change. The current Docling pull request on threaded PDF pipeline feature parity is a concrete reminder that alternate execution paths may not expose identical features. Pin parser versions, save route metadata, and run fixtures before changing a parser, OCR engine, concurrency mode, or layout model.

Build a fixture suite that catches structural damage

A good fixture suite is small enough to run in CI and varied enough to expose the failures your production corpus contains. Include documents you are allowed to retain that represent:

  • clean digital text
  • two or more columns
  • scanned pages
  • mixed native and scanned pages
  • tables with merged cells and units
  • repeated headers and footnotes
  • forms and selection marks
  • rotated pages
  • diagrams with meaningful captions
  • malformed or password-protected inputs

For each fixture, assert structure rather than the entire parser output byte for byte. Exact snapshots become noisy across harmless parser changes. Better assertions check that a named heading precedes its section, a known table value remains attached to its row and column headers, a scanned page contains required text, and every expected page has at least one retained element or an explicit quarantine record.

Then test retrieval. Create queries whose answers depend on the structures most likely to break. A table fixture should include a question that needs both a row label and a unit. A two-column fixture should include a question whose evidence becomes nonsense if columns interleave. Require the retrieved chunks to contain the expected element IDs and source spans before involving a language model.

Handle failures without poisoning the index

Run parsing like a versioned build. Write elements and chunks to staging, validate them there, and publish a document version only after every required page passes or receives an approved quarantine disposition. If the job stops halfway through, the previous indexed version stays active.

Separate retryable failures from document defects. A temporary OCR service error can retry within a bounded policy. An unsupported encryption scheme, unreadable scan, or structurally invalid table needs review or a different parser. Repeating the same call will not repair the file.

Keep these states explicit: received, inspected, parsing, quarantined, validated, published, and superseded. Attach reason codes to failures. Operators should be able to answer which documents are absent from retrieval, why they are absent, and which parser route produced every published chunk.

Verify the pipeline before rollout

Run the full fixture set through inspection, routing, parsing, normalization, chunking, and retrieval. Verify five things:

  1. Every source page is represented by validated elements or a visible quarantine decision.
  2. Reading order remains correct for multi-column and mixed-layout fixtures.
  3. Table values retain titles, headers, units, and row context.
  4. Retrieved chunks map back to stable document versions and exact source spans.
  5. A failed or partial parse cannot replace the last valid indexed version.

Review a sample in a side-by-side tool that shows the rendered page beside normalized elements and proposed chunks. Human inspection is especially useful when establishing fixtures and thresholds. Once the assertions describe the real defects, CI can catch regressions without requiring a person to reread every document.

Start with ten to twenty representative files from the actual corpus. Define the parsed element contract and route metadata, then write one structural assertion for each known failure mode. Do this before tuning embeddings or answer prompts. Downstream RAG work cannot recover source relationships that the parser already discarded.

References

About Fire In Belly: Independent senior engineering from Tallinn, Estonia. We design and build AI workflow automation with the parser routing, structural provenance, and fixture-based quality gates described above, at published fixed prices. Schedule a call to discuss your next project.