Enrich Functions

Enrich functions perform semantic search against collections to add contextual information to your data. They're useful for looking up reference data, adding context from knowledge bases, or matching against existing records.

When to Use

Use an Enrich function when you need to:

• Look up vendor information from a master list
• Match extracted data against existing records
• Add context from a knowledge base or documentation
• Find similar items in a collection
• Validate data against reference sources

Prerequisites

Before creating an Enrich function, you need:

1. A Collection with your reference data
2. Items added to the collection with searchable content

See the Collections API for creating and populating collections.

Configuration Fields

Required Fields

Optional Fields

Enrich Config

The config object contains:

Example

Vendor Lookup

Enrich invoice data with vendor information from a master vendor list:

{
  "functionName": "vendor-enricher",
  "type": "enrich",
  "displayName": "Vendor Information Lookup",
  "config": {
    "collectionName": "vendor-master-list"
  },
  "tags": ["vendor", "lookup"]
}

Product Matching

Match extracted product names against a product catalog:

{
  "functionName": "product-matcher",
  "type": "enrich",
  "displayName": "Product Catalog Matcher",
  "config": {
    "collectionName": "product-catalog"
  },
  "tags": ["products", "matching"]
}

Workflow Pattern

Enrich functions typically follow Transform functions:

Document
    │
    ▼
┌───────────┐
│ Transform │  Extract raw data
└───────────┘
    │
    ▼
┌───────────┐
│  Enrich   │  Add context from collection
└───────────┘
    │
    ▼
Enriched Output

Example Flow

1. Transform extracts vendor name "Acme Corp" from invoice
2. Enrich searches vendor collection for "Acme Corp"
3. Output includes matched vendor ID, address, payment terms

Setting Up Collections

Before using Enrich functions, create a collection and add items to it. Each item carries a data field that can be either a string or an arbitrary JSON object — the data is embedded asynchronously, and POST /v3/collections/items returns immediately with status: "pending" and an eventID you can correlate with webhook notifications once embedding completes.

# Create the collection
curl -X POST https://api.bem.ai/v3/collections \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BEM_API_KEY" \
  -d '{
    "collectionName": "vendor_master_list"
  }'

# Add items (mix of string and object payloads)
curl -X POST https://api.bem.ai/v3/collections/items \
  -H "Content-Type: application/json" \
  -H "x-api-key: $BEM_API_KEY" \
  -d '{
    "collectionName": "vendor_master_list",
    "items": [
      { "data": "Acme Corporation - primary supplier for office supplies" },
      {
        "data": {
          "vendorID": "V001",
          "name": "Acme Corporation",
          "paymentTerms": "Net 30"
        }
      }
    ]
  }'

Collection names must contain only letters, digits, underscores, and dots — each segment must start with a letter or underscore — and dot notation is meaningful: customers.premium.vip is a child of customers.premium. Texts above the embedding model's 8,192-token limit are rejected; check sizes with POST /v3/collections/token-count before bulk uploads.

Related