Table evidence: cell coordinates, headers and reading order

Last updated: 7 Oct 20265 min read

tutorial

A cell means little without its row and column headers. Preserve that structure before a model searches, extracts or summarizes the table.

Represent coordinates before prose

A runbook table might list service, region and retry ceiling. The value “47” is not a useful claim until it is tied to the gateway row and the retry-ceiling column. Store table ID, row index, column index, header path, raw cell text and document revision. Flattening cells into a single paragraph can attach a value to the wrong service. Document sections delimit which heading and table caption apply to a cell.

Handle multi-level and repeated headers

A wide table may group two columns under “Before change” and two under “After change.” The leaf header alone may repeat “Limit.” Record the full header path for each value. A row may have a merged service name that visually spans several lines; fill that context only when the source layout supports it, and mark the fill as inferred. Page breaks can repeat headers. Do not mistake a repeated header for a data row or merge two similarly formatted tables into one.

Keep the original reading order

For a scanned page, OCR boxes provide text and geometry but may scramble columns. Preserve coordinates and a proposed row grouping so a reviewer can trace an extracted fact to its cell. When geometry is uncertain, return a review state rather than inventing a value. OCR geometry preserves the connection between recognized characters and page location. Store the image or source document revision alongside every parsed table.

Evaluate facts, not just cell text

Measure header assignment, row alignment, value extraction and final question-answer correctness separately. A system can read every character correctly and still report the retry ceiling from the wrong region. Include blank cells, merged headers, footnotes, repeated page headers and tables with similar service names. Ask reviewers to inspect the exact source cell and its header path. The table evidence project makes those checks part of release.

Implementation

def table_facts(table_id, headers, rows, revision):
    if not table_id or not revision or len(set(headers)) != len(headers):
        raise ValueError("table identity, revision and unique headers are required")
    facts = []
    for row_index, cells in enumerate(rows):
        if len(cells) != len(headers):
            raise ValueError("row width differs from header width")
        for column_index, value in enumerate(cells):
            facts.append({"table_id": table_id, "row": row_index,
                          "column": column_index, "header": headers[column_index],
                          "raw_value": value, "source_revision": revision})
    return facts

facts = table_facts("limits-47", ["service", "retry ceiling"],
                    [["gateway-west", "47"], ["worker-east", "82"]], "r3")
assert facts[1]["header"] == "retry ceiling" and facts[1]["raw_value"] == "47"

Performance and operating cost

Constructing facts from r rows and c columns takes O(r × c) time and space. A production parser must also resolve merged cells and layout uncertainty, which can dominate the simple conversion. Keep table-coordinate lineage so a wrong answer can be traced to a row assignment rather than dismissed as a language-model error.

Common Mistakes

Flattening a table into prose before preserving cell coordinates.
Using a leaf header without its parent group.
Treating a repeated page header as a data row.
Calling OCR accurate when values are assigned to wrong rows.