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
}

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