Extract Functions

Extract functions are the most common function type in bem. They pull structured JSON out of unstructured files — PDFs, images, spreadsheets, emails, audio, and video — against a schema you define. The same primitive handles both text-first inputs (where OCR and reasoning are the levers) and visual-first inputs (where layout and appearance carry the signal); the schema and inputType drive the strategy.

When to Use

Use an Extract function when you need to:

• Extract specific fields from invoices, receipts, forms, or contracts
• Parse tabular data from spreadsheets or CSVs
• Pull structured information out of images, scans, or video frames
• Process email content and attachments
• Transcribe and structure audio inputs

Configuration Fields

Required Fields

Optional Fields

Output Schema

The outputSchema field defines the structure of the data you want to extract, using standard JSON Schema syntax.

Best Practices

1. Use descriptive field names — Choose names that clearly indicate what data should be extracted
2. Add descriptions — Include descriptions for complex fields to guide the model
3. Specify required fields — Mark essential fields as required in the schema
4. Use appropriate types — Use number for amounts, string for text, array for lists

Example

{
  "functionName": "invoice-extractor",
  "type": "extract",
  "displayName": "Invoice Data Extractor",
  "outputSchemaName": "Invoice Schema",
  "outputSchema": {
    "type": "object",
    "required": ["invoiceNumber", "totalAmount", "vendor"],
    "properties": {
      "invoiceNumber": {
        "type": "string",
        "description": "The unique invoice number"
      },
      "invoiceDate": {
        "type": "string",
        "description": "Date of the invoice in ISO 8601 format"
      },
      "totalAmount": {
        "type": "number",
        "description": "Total amount due"
      },
      "vendor": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Vendor company name"
          },
          "address": {
            "type": "string",
            "description": "Vendor address"
          }
        }
      },
      "lineItems": {
        "type": "array",
        "description": "Individual line items on the invoice",
        "items": {
          "type": "object",
          "properties": {
            "description": { "type": "string" },
            "quantity": { "type": "number" },
            "unitPrice": { "type": "number" }
          }
        }
      }
    }
  },
  "tags": ["billing", "finance"]
}

Tabular Chunking

For large spreadsheets or CSVs, enable tabularChunkingEnabled to process data in row batches rather than all at once. This improves reliability for documents with many rows.

{
  "functionName": "spreadsheet-processor",
  "type": "extract",
  "outputSchemaName": "Row Data",
  "outputSchema": {
    "type": "object",
    "properties": {
      "productName": { "type": "string" },
      "quantity": { "type": "number" },
      "price": { "type": "number" }
    }
  },
  "tabularChunkingEnabled": true
}

Super Extract

Enable superExtract to improve extraction of items in an array from a long PDF, such as invoice lines or bank transactions. Your output schema must define the array as a top-level field. A direct lineItems field qualifies; invoice.lineItems does not.

This outputSchema qualifies because lineItems is a direct field of the top-level object:

{
  "type": "object",
  "properties": {
    "invoiceNumber": {
      "type": "string",
      "description": "Invoice number printed in the document header."
    },
    "lineItems": {
      "type": "array",
      "description": "Each billed product or service, in document order.",
      "items": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "Product or service named on the line."
          },
          "amount": {
            "type": "number",
            "description": "Amount charged for the line."
          }
        }
      }
    }
  }
}

With this outputSchema, enabling superExtract still uses standard Extract because lineItems is inside invoice:

{
  "type": "object",
  "properties": {
    "invoice": {
      "type": "object",
      "properties": {
        "lineItems": {
          "type": "array",
          "items": { "type": "object" }
        }
      }
    }
  }
}

Short PDFs use standard Extract automatically. Super Extract also has no effect on:

• A long contract whose output schema contains only two string fields, effectiveDate and governingLaw. It has no array at the top level.
• A CSV, Excel, or other non-PDF file. For large tables, use tabularChunkingEnabled.
• A PDF processed by an Extract function with bounding boxes enabled.

Some long PDFs are poor fits even when Super Extract runs:

• Several invoices bundled into one PDF. Super Extract treats the PDF as one document. Use a Split function first so Extract returns one result per invoice.
• A claims file where one claim's details are spread across distant pages. Super Extract processes page groups in parallel and combines their resulting arrays. It cannot combine fragments of one claim from separate groups, so it may miss that claim.

Visual vs. Text-First Inputs

The extract primitive adapts its processing strategy to the input: text-first for documents where OCR plus reasoning is the primary lever (spreadsheets, PDF invoices, contracts, emails with attachments), and visual-first for inputs where layout and appearance carry the signal (slide decks, photos, screenshots, video frames). You don't need to choose a mode — the schema and input type drive the behavior.

Email Integration

Extract functions automatically receive an email address. Forward emails to this address to process them through the function.

The email address is returned in the function response as emailAddress (e.g., eml_xxx@actions.bem.ai).

Related