Skip to content

Supplier lookup in a reference table

The invoice says who the supplier is, but your ERP wants the supplier code. A field with x-dx.source.kind: lookup is not read from the document: it is matched against a versioned reference table (names normalized, legal suffixes and punctuation ignored) and comes back with the row it matched, its table version and the score.

The documents are synthetic (invented names, amounts and accounts), generated by scripts/docs_examples.py:

The graph

parse → extract

The full version body (graph and schemas), as the API takes it:

{
  "graph": {
    "nodes": [
      {
        "id": "parse",
        "type": "parse"
      },
      {
        "id": "extract",
        "type": "extract",
        "config": {
          "schema_id": "invoice"
        }
      }
    ],
    "edges": [
      {
        "source": "parse",
        "target": "extract"
      }
    ]
  },
  "schemas": {
    "invoice": {
      "type": "object",
      "properties": {
        "invoice_number": {
          "type": "string"
        },
        "supplier_name": {
          "type": "string"
        },
        "supplier_code": {
          "type": "string",
          "x-dx": {
            "source": {
              "kind": "lookup",
              "table_id": "suppliers",
              "match_on": [
                "supplier_name"
              ],
              "returns": "code"
            }
          }
        },
        "total": {
          "type": "number"
        }
      }
    }
  }
}

Create it and run it

Set DX_BASE_URL and DX_API_KEY (see the quickstart), cd to docs/examples/gallery/supplier-lookup/ and run any of the three. They do the same.

Python

# SPDX-License-Identifier: Apache-2.0
# expect: "status": "succeeded"
"""Supplier lookup in a reference table: create the workflow, run it on the document and print what comes back."""

import json
import os
import secrets
from pathlib import Path

import httpx

api = httpx.Client(
    base_url=os.environ["DX_BASE_URL"],
    headers={"Authorization": f"Bearer {os.environ['DX_API_KEY']}"},
    timeout=120,
)
name = f"supplier-lookup-{secrets.token_hex(3)}"  # unique, so the example can run again

# 0. Upload the reference table (a CSV; every upload is an immutable version).
api.post(
    "/v1/lookup-tables",
    data={"name": "suppliers", "key_column": "code"},
    files={"file": ("suppliers.csv", Path("suppliers.csv").read_bytes(), "text/csv")},
).raise_for_status()

# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
workflow = api.post("/v1/workflows", json={"name": name}).raise_for_status().json()
version = (
    api.post(
        f"/v1/workflows/{workflow['id']}/versions",
        json=json.loads(Path("workflow.json").read_text()),
    )
    .raise_for_status()
    .json()
)
api.post(f"/v1/workflow-versions/{version['id']}:publish", json={}).raise_for_status()
api.put(
    f"/v1/workflows/{workflow['id']}/aliases/prod", json={"version_id": version["id"]}
).raise_for_status()

# 2. Run it on the document and wait for the result.
run = (
    api.post(
        "/v1/runs",
        data={"workflow": f"{name}@prod"},
        files=[("files", ("invoice.pdf", Path("invoice.pdf").read_bytes(), "application/pdf"))],
    )
    .raise_for_status()
    .json()
)
run = api.get(f"/v1/runs/{run['id']}", params={"wait": 60}).raise_for_status().json()
result = api.get(f"/v1/runs/{run['id']}/result").raise_for_status().json()

node = result["outputs"]["extractions"]["extract"]
view = {
    "status": run["status"],
    "data": node["data"],
    "citations": [
        {"path": f["path"], "page": f["evidence"][0]["page"], "quote": f["evidence"][0]["quote"]}
        for f in node["fields"]
        if f["evidence"] and "[" not in f["path"]
    ],
}
print(json.dumps(view, indent=2))

TypeScript

// SPDX-License-Identifier: Apache-2.0
// expect: "status": "succeeded"
// Supplier lookup in a reference table: create the workflow, run it on the document and print what comes back.
// Node 22+: node --experimental-strip-types create.ts
import { readFileSync } from "node:fs";

const base = process.env.DX_BASE_URL as string;
const auth = { Authorization: `Bearer ${process.env.DX_API_KEY}` };
const name = `supplier-lookup-${Math.random().toString(16).slice(2, 8)}`; // unique, so it can run again

async function call(path: string, init: RequestInit = {}): Promise<any> {
  const response = await fetch(base + path, { ...init, headers: { ...auth, ...init.headers } });
  if (!response.ok) throw new Error(`${response.status} ${path}: ${await response.text()}`);
  return response.json();
}
const json = (body: unknown): RequestInit => ({
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(body),
});

// 0. Upload the reference table (a CSV; every upload is an immutable version).
const table = new FormData();
table.append("name", "suppliers");
table.append("key_column", "code");
table.append("file", new Blob([readFileSync("suppliers.csv")], { type: "text/csv" }), "suppliers.csv");
await call("/v1/lookup-tables", { method: "POST", body: table });

// 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
const workflow = await call("/v1/workflows", json({ name }));
const version = await call(
  `/v1/workflows/${workflow.id}/versions`,
  json(JSON.parse(readFileSync("workflow.json", "utf8"))),
);
await call(`/v1/workflow-versions/${version.id}:publish`, json({}));
await call(`/v1/workflows/${workflow.id}/aliases/prod`, {
  ...json({ version_id: version.id }),
  method: "PUT",
});

// 2. Run it on the document and wait for the result.
const form = new FormData();
form.append("workflow", `${name}@prod`);
form.append("files", new Blob([readFileSync("invoice.pdf")], { type: "application/pdf" }), "invoice.pdf");
const started = await call("/v1/runs", { method: "POST", body: form });
const run = await call(`/v1/runs/${started.id}?wait=60`);
const result = await call(`/v1/runs/${run.id}/result`);

const node = result.outputs.extractions["extract"];
const view = {
  status: run.status,
  data: node.data,
  citations: node.fields
    .filter((f: any) => f.evidence.length > 0 && !f.path.includes("["))
    .map((f: any) => ({ path: f.path, page: f.evidence[0].page, quote: f.evidence[0].quote })),
};
console.log(JSON.stringify(view, null, 2));

curl

#!/usr/bin/env bash
# SPDX-License-Identifier: Apache-2.0
# expect: "status": "succeeded"
# Supplier lookup in a reference table: create the workflow, run it on the document and print what comes back.
# Needs curl and jq; DX_BASE_URL and DX_API_KEY in the environment.
set -euo pipefail
api() { curl -sS --fail-with-body -H "Authorization: Bearer $DX_API_KEY" "$@"; }
JSON='Content-Type: application/json'
NAME="supplier-lookup-$RANDOM$RANDOM"  # unique, so the example can run again

# 0. Upload the reference table (a CSV; every upload is an immutable version).
api -X POST "$DX_BASE_URL/v1/lookup-tables" -F name=suppliers -F key_column=code -F file=@suppliers.csv > /dev/null

# 1. Create the workflow, add the version (graph + schemas), publish it, point `prod` at it.
WORKFLOW=$(api -X POST "$DX_BASE_URL/v1/workflows" -H "$JSON" -d "{\"name\": \"$NAME\"}" | jq -r .id)
VERSION=$(api -X POST "$DX_BASE_URL/v1/workflows/$WORKFLOW/versions" -H "$JSON" -d @workflow.json | jq -r .id)
api -X POST "$DX_BASE_URL/v1/workflow-versions/$VERSION:publish" -H "$JSON" -d '{}' > /dev/null
api -X PUT "$DX_BASE_URL/v1/workflows/$WORKFLOW/aliases/prod" -H "$JSON" \
  -d "{\"version_id\": \"$VERSION\"}" > /dev/null

# 2. Run it on the document and wait for the result.
RUN=$(api -X POST "$DX_BASE_URL/v1/runs" -F "workflow=$NAME@prod" -F "[email protected]" | jq -r .id)
STATUS=$(api "$DX_BASE_URL/v1/runs/$RUN?wait=60" | jq -r .status)
api "$DX_BASE_URL/v1/runs/$RUN/result" | jq --arg status "$STATUS" '{status: $status, data: .outputs.extractions["extract"].data, citations: [.outputs.extractions["extract"].fields[] | select((.evidence | length) > 0 and (.path | contains("[") | not)) | {path, page: .evidence[0].page, quote: .evidence[0].quote}]}'

Response

Produced by running the script above against a server with the fake model and these documents; make docs runs all the examples again and fails if an answer changes.

{
  "status": "succeeded",
  "data": {
    "invoice_number": "INV-2026-0310",
    "supplier_code": "S-001",
    "supplier_name": "NORTHWIND COMPONENTS, LTD.",
    "total": 210
  },
  "citations": [
    {
      "path": "invoice_number",
      "page": 1,
      "quote": "INV-2026-0310"
    },
    {
      "path": "supplier_code",
      "page": null,
      "quote": "code=S-001"
    },
    {
      "path": "supplier_name",
      "page": 1,
      "quote": "NORTHWIND COMPONENTS, LTD."
    },
    {
      "path": "total",
      "page": 1,
      "quote": "210.00"
    }
  ]
}