Splitting multi-document files
A single input file often contains several logical documents — for example a packet that holds a bank statement followed by an invoice. When you enable splitting, Amazon Textract Insights detects these boundaries, processes each sub-document on its own, and matches each one to a blueprint independently.
When splitting applies
Splitting is controlled by the project's SplitterConfiguration, which has
a single State field (ENABLED or DISABLED). Two
conditions must hold for it to take effect:
-
The project (or job) must provide blueprints. Splitting takes effect only when blueprints are present.
-
Splitting applies to custom extraction. Each detected sub-document is matched to a blueprint and gets its own custom extraction results.
If you enable splitting on a project that has no blueprints, there is nothing for the splitter to act on.
Enable splitting on a project
Set SplitterConfiguration.State to ENABLED in the project
configuration, alongside the blueprints you want to match against.
aws textract create-project \ --project-name "packet-processing" \ --extraction-configuration '{ "BoundingBox": { "State": "ENABLED" }, "Granularity": { "Types": ["DOCUMENT", "ELEMENT"] }, "OutputFormat": {"TextFormat": {"Types": ["MARKDOWN"]}, "AdditionalFileFormat": {"State": "DISABLED"}} }' \ --splitter-configuration '{"State": "ENABLED"}' \ --custom-configuration '{ "Blueprints": [ { "BlueprintArn": "arn:aws:textract:us-east-1:aws:blueprint/public-invoice" }, { "BlueprintArn": "arn:aws:textract:us-east-1:aws:blueprint/public-bank-statement" } ] }' \ --region us-east-1
See Working with projects for the full set of configuration blocks.
How a packet is split
The following example uses a four-page file that contains a bank statement followed by a three-page invoice, processed with the public invoice and bank-statement blueprints and splitting enabled. Amazon Textract Insights produced two sub-documents:
Sub-document |
Pages |
Matched blueprint |
|---|---|---|
|
|
|
|
|
|
Each sub-document is numbered by <n> and gets its own extraction
results under extraction/<n>/ and its own custom extraction results
under custom/<n>/.
Reading the job metadata
On a successful job, job_metadata.json lists the output for each
sub-document. The following is the metadata for the split packet described earlier, with the bucket
name replaced by a placeholder.
{ "job_id": "0df791a4-ef8e-4c8e-a99f-6d0022bd30d1", "job_status": "PROCESSED", "output_metadata": [ { "asset_id": 0, "segment_metadata": [ { "extraction_path": "s3://amzn-s3-demo-destination-bucket/output/<job-id>/0/extraction/0/result.json", "custom_path": "s3://amzn-s3-demo-destination-bucket/output/<job-id>/0/custom/0/result.json", "custom_status": "MATCH" }, { "extraction_path": "s3://amzn-s3-demo-destination-bucket/output/<job-id>/0/extraction/1/result.json", "custom_path": "s3://amzn-s3-demo-destination-bucket/output/<job-id>/0/custom/1/result.json", "custom_status": "MATCH" } ] } ] }
output_metadata[].segment_metadata[] has one entry per sub-document. Each
entry points to that sub-document's extraction results (extraction_path)
and custom extraction results (custom_path), and reports
custom_status (MATCH when a blueprint matched). The leading
0 in each path is the asset_id of the input file.
The job_status field in job_metadata.json reads
PROCESSED and is not the authoritative job state. Rely on the
Status returned by GetDocumentInsights (IN_PROGRESS,
SUCCEEDED, or FAILED), not on this field.
Which pages belong to each sub-document
Each sub-document's custom result.json records the input pages it covers
in split_document.page_indices. For the preceding invoice sub-document:
{ "matched_blueprint": { "arn": "arn:aws:textract:us-east-1:aws:blueprint/public-invoice", "name": "Invoice", "confidence": 1 }, "document_class": { "type": "Invoice" }, "split_document": { "page_indices": [1, 2, 3] } }
Page indices are zero-based and refer to pages of the original input file. For how a sub-document is matched to a blueprint and what happens when none matches, see Blueprint matching and fallback blueprints. For the full output layout on disk, see Output location and file structure.