How to Extract Tables from Large PDFs and Verify the Numbers

When handling complex PDF documents—such as multi-page equipment inspection reports or financial statements—uniform, clean text is the exception rather than the rule. In real-world enterprise documents, digital pages mingle with scanned sheets, tables lack clear grid borders, and critical metrics are often hidden in dense footnotes.

Feeding such files directly into a multimodal model and writing the output straight to a production database is risky. Because foundation models remain probabilistic systems, a dependable extraction pipeline cannot rely on blind trust. Instead, it must be engineered around deliberate schema design, gathering contextual audit hints, and rigorous post-extraction verification against the visual original.

---

1. Data Schema: Fixing Fields and Permitting Nulls

The Gemini Structured Outputs mechanism guarantees that model responses strictly adhere to a declared schema, producing syntactically valid JSON. If a property is declared as numeric, extraneous conversational text will not contaminate the value.

However, syntactic schema compliance guards only against structural errors—it does not ensure semantic truth:

• A model can mix up adjacent rows or transpose columns in dense, borderless tables;
• On degraded scans, the digit 8 can easily be misread as 3, and decimal points frequently get lost;
• When a metric is missing or obscured, a model that is not explicitly allowed to omit values may attempt to fabricate a plausible number.

To mitigate hallucination risks, schemas should declare fields as nullable (Optional or null), accompanied by explicit prompt instructions to return null whenever a number cannot be deciphered with high confidence. While permitting null values significantly reduces the pressure to guess, it does not provide an absolute guarantee against hallucinations on its own.

---

2. File Ingestion: When to Choose the Files API

According to the official Gemini document processing documentation, operational limits are set at up to 50 MB or up to 1,000 pages per PDF file (both file size and page count constraints apply simultaneously, with no guarantee that both maximums can be achieved together—processing halts at whichever limit is reached first).

The optimal transmission method depends on document size and operational pattern:

• Inline data passing is best suited for small documents and one-off extraction calls.
• The Files API (client.files.upload) is designed for larger files and multi-turn workflows where the same document is queried across consecutive operations (e.g., initial section classification followed by targeted table extraction). Using the Files API avoids re-uploading the entire document payload for every call.

---

3. Querying Data: Schema, Citation Hints, and Hypothetical Response

To make extracted data auditable, prompt the model to return auxiliary metadata alongside target values: an approximate page number (page_number) and a brief, verbatim citation snippet (evidence_quote).

Crucial Distinction: page_number and evidence_quote are not factual proofs; they are strictly heuristic search hints. Because the model generates these fields itself, quotation snippets may contain OCR artifacts or merge adjacent lines, and the reported visual page number may diverge from the physical sheet index of the PDF container.

Hypothetical Problem Setup

Consider a hypothetical problem setup (no actual PDF was provided, uploaded, or analyzed, and no live API query was executed): modeling the extraction of summary metrics from a hypothetical pump inspection report. In this illustrative example, we examine a hypothetical two-row table:

Identifier	Pressure (MPa)	Vibration (mm/s)	Status	Notes
Н-101-А	1.45	2.1	Normal (В норме)	Scheduled inspection
Н-102-В	(illegible)	7.8	Attention (Внимание)	Increased play

Below is an example schema defined with Pydantic alongside the invocation syntax for the official SDK:

from google import genai
from pydantic import BaseModel, Field
from typing import List, Optional

class PumpRecord(BaseModel):
    unit_id: str = Field(
        description="Идентификатор агрегата точно как в таблице"
    )
    inlet_pressure_mpa: Optional[float] = Field(
        default=None,
        description="Давление в МПа. Если значение неразборчиво или отсутствует — null"
    )
    vibration_mms: Optional[float] = Field(
        default=None,
        description="Уровень вибрации в мм/с. При отсутствии данных — null"
    )
    status: str = Field(
        description="Статус узла (например, 'В норме', 'Внимание')"
    )
    page_number: Optional[int] = Field(
        default=None,
        description="Оценочный номер страницы документа (подсказка для аудитора, не подтверждена)"
    )
    evidence_quote: Optional[str] = Field(
        default=None,
        description="Короткий фрагмент строки (до 10 слов), откуда взяты числа (подсказка, не подтверждена)"
    )

class InspectionPayload(BaseModel):
    records: List[PumpRecord]

client = genai.Client()

uploaded_file = client.files.upload(file="hypothetical_inspection.pdf")

response = client.interactions.create(
    model="gemini-3.8-flash",
    input=[
        {
            "type": "document",
            "uri": uploaded_file.uri,
            "mime_type": uploaded_file.mime_type,
        },
        {
            "type": "text",
            "text": (
                "Извлеки показатели агрегатов в соответствии со схемой. "
                "Если число неразборчиво или отсутствует, возвращай null. "
                "Для каждой записи заполни номер страницы и короткую цитату-подтверждение."
            ),
        },
    ],
    response_format={
        "type": "text",
        "mime_type": "application/json",
        "schema": InspectionPayload.model_json_schema(),
    },
)

payload = InspectionPayload.model_validate_json(response.output_text)

Illustrative JSON Response from the Model

The following JSON illustrates a hypothetical model response to this request. We emphasize: this output serves as a hypothetical structural illustration, not the result of an actual API run or real physical measurement:

{
  "records": [
    {
      "unit_id": "Н-101-А",
      "inlet_pressure_mpa": 1.45,
      "vibration_mms": 2.1,
      "status": "В норме",
      "page_number": 12,
      "evidence_quote": "Н-101-А 1.45 2.1 В норме"
    },
    {
      "unit_id": "Н-102-В",
      "inlet_pressure_mpa": null,
      "vibration_mms": 7.8,
      "status": "Внимание",
      "page_number": 12,
      "evidence_quote": "Н-102-В [пятно] 7.8 Внимание"
    }
  ]
}

In this hypothetical response, both page_number: 12 instances and both evidence_quote values carry the status of unverified hints. While the model correctly emitted null for the illegible pressure figure on the second unit, none of the extracted attributes are considered confirmed facts a priori.

---

4. Reconciling with the Visual Original and Export Rules

Extracted records cannot be written directly to downstream databases without validation. An end-to-end audit comparing each field against the visual rendering of the source PDF page is required.

Important Clarification Regarding the Example: The two-row table, page 12, the physical 14th-sheet offset, the compressor department, and the visual verification workflow represent an exclusively hypothetical illustration of the process. No real PDF document was provided or inspected, and the steps described below reflect what a reviewer would verify in practice, formulating conditional decisions should visual rendering confirm the stated values.

Step-by-Step Record Verification: What a Reviewer Would Check

1. Unit Н-101-А:

   • Page and Localization: The model returned the hint page_number: 12. The reviewer would inspect the visual rendering of page 12 (or sheet 14 if front matter created a physical offset) and locate the target compressor department table.
   • Identifier: In the first column, the reviewer would check the identifier Н-101-А for an exact match.
   • Pressure and Units: Under the inlet pressure column, the reviewer would verify that the value 1.45 is clearly legible and that the engineering units match schema expectations (МПа / MPa).
   • Vibration and Units: Under vibration, the reviewer would check for 2.1 and verify the unit denomination (мм/с / mm/s).
   • Status: Under operational condition, the reviewer would confirm the presence of the status В норме (Normal).
   • Conditional Decision: If the rendered page validates all fields, values, and physical units, the row would be approved for export (Export / Accepted).

2. Unit Н-102-В:

   • Page and Localization: In the same hypothetical table, the reviewer would proceed to the second row.
   • Identifier: The reviewer would confirm the presence of identifier Н-102-В.
   • Vibration and Status: The reviewer would cross-check the vibration value 7.8 and status Внимание (Warning / Attention) against the visual layer.
   • Pressure: The model returned null. The reviewer would examine the corresponding cell on the page rendering: if a dark, smeared smudge (a scanning defect) is observed in place of a reading, this validates the model’s decision to return null, yet a vital physical measurement remains absent.
   • Conditional Decision: Because visual confirmation establishes that a critical pressure reading is missing, the row would be blocked from automated export and placed on manual review (Hold for manual review), requiring an operational re-scan or cross-referencing against backup maintenance logs.

Checked Output After Verification

The summary table details exactly what the reviewer would inspect and what conditional routing decision the validation pipeline would trigger upon visual confirmation:

Unit	Pressure (MPa)	Vibration (mm/s)	Status	What the Reviewer Would Check (Hypothetical Verification)	Pipeline Conditional Decision (If Rendering Confirms Values)
Н-101-А	1.45	2.1	В норме (Normal)	Would verify identifier match, numerical values, and units (MPa, mm/s) against rendering	Export approved (Ready for ingestion)—conditioned on complete visual confirmation of all fields
Н-102-В	null (omitted)	7.8	Внимание (Warning)	Would confirm scan defect (smudge) in the pressure cell and cross-check vibration value	Held for manual review (Operator triage)—due to confirmed absence of a critical metric

Architectural Validation Pattern

A robust document ingestion pipeline routes processed records into two separate streams:

• Green Corridor (Verified Export): Reserved exclusively for rows where every mandatory field is visually corroborated against the source page rendering and all physical units are normalized to schema standards.
• Review Queue (Quarantine): Any records containing null in critical fields, conflicting measurement units, or ambiguous citations are quarantined for manual human operator review.

---

Official Documentation and Guides

• Document processing with Gemini API (limits and supported formats)
• Structured outputs (schema enforcement and validation)