Extract Fields

Run ade extract to pull the fields you name from a document you have already parsed. A schema defines those fields, and the result comes back shaped like the schema, with a record of where each value was found. Each extraction is its own job item, and it references the parse it ran against rather than copying it. For a worked example, see the Quickstart. For the files a run saves, see CLI Concepts.

Choose Your Input

Extract from a completed parse, from a document path, or from Markdown you hold yourself.

Input	What happens
A parse job item ID	Extracts against the stored parse. This is the most common case.
A document path	Reuses the latest parse of that file if there is one. Otherwise it parses first.
Your own Markdown	Extracts from a Markdown file you supply rather than a parse. With no document behind it, the result has no page locations.

ade extract 8d1ec099 --schema schema.json              # a completed parse
ade extract -d invoice.pdf --schema schema.json        # a document path
ade extract --markdown notes.md --schema schema.json   # your own Markdown

Write a Schema

A schema is a JSON Schema object naming each field, its type, and a description the model uses to recognize it. Build one visually in the Playground and download the JSON, or write it by hand following Extraction Schema (JSON). Pass a file path or an inline JSON object. Changing a schema changes the run, so the next extraction is a new job item that consumes credits.

ade extract 8d1ec099 --schema '{"type":"object","properties":{"total":{"type":"number"}}}'

Require Every Field

By default, a field the model cannot extract is skipped, and the run reports schema_violation_error. Add --strict to make the request fail instead. For everything strict mode covers, see Extract Input Parameters.

ade extract 8d1ec099 --schema schema.json --strict

Read the Result

The extracted values come back under extraction, shaped exactly like your schema. For the three-field schema in the Quickstart, that looks like this:

{
  "balance_due": 89.52,
  "medical_record_number": "MRN-100-55-3821",
  "patient_name": "Ada M. Rensford"
}

Check Which Values Are Grounded

A grounded value is one the model read from a specific place on the page. To see where a value came from, open the extraction in the viewer, which highlights the spot on the page each field was read from. Find, Crop, and View covers the viewer, local search, and cropping evidence images. Three signals tell you where each field stands.

Signal	What it tells you
`fields`	How many leaf fields the schema asked for.
`ungroundable`	Fields with a value the model could not tie to a location on the page. The value may still be correct, but nothing quotes it.
`empty_fields`	Fields with no value at all, so there was nothing to ground.

Use the Values in a Script

Add --json to print the whole payload, then select the extraction key with a JSON tool such as jq.

ade extract 8d1ec099 --schema schema.json --json | jq .extraction

Choose a Service Tier

Parse and Extract use async jobs, and each submitted job sends a service tier. The CLI defaults to priority, the fast lane, which consumes credits at the full rate. The standard tier runs in a slower lane and consumes half the credits. That default differs from the API, where a job that sends no service_tier runs on standard. If you are moving a workload from the API to the CLI, pass --tier standard to keep consumption the same. For the rates, see Credit Consumption. For how the two lanes differ, see Sync vs Async. Set the tier per run:

ade extract 8d1ec099 --schema schema.json --tier standard

Stale Extractions

An extraction points at the parse it ran against. If you later re-run that parse with --force, the extraction keeps its old result, and ade history list marks it stale. Re-run the extraction to update it.

Get Started

Use the CLI

Reference

Choose Your Input

Write a Schema

Require Every Field

Read the Result

Check Which Values Are Grounded

Use the Values in a Script

Choose a Service Tier

Stale Extractions

Next Steps

Find, Crop, and View

Scripting and Automation

​Choose Your Input

​Write a Schema

​Require Every Field

​Read the Result

​Check Which Values Are Grounded

​Use the Values in a Script

​Choose a Service Tier

​Stale Extractions

​Next Steps

Find, Crop, and View

Scripting and Automation

Choose Your Input

Write a Schema

Require Every Field

Read the Result

Check Which Values Are Grounded

Use the Values in a Script

Choose a Service Tier

Stale Extractions

Next Steps