Skip to main content

ERPL-IDoc Quick Start

In this 5-minute tutorial you'll read an IDoc file, decode its opaque SDATA into typed columns, write a byte-valid IDoc back, and convert flat ⇄ IDoc-XML — without a SAP connection.

Prerequisites
  • DuckDB installed (version 1.5.4+)
  • One or more IDoc files (flat or IDoc-XML) — no SAP system needed
  • For typed decode: a segment dictionary (a CSV/Parquet file, table, or view). Generic and XML reads need no dictionary.

Step 1: Install ERPL-IDoc​

INSTALL erpl_idoc FROM community;
LOAD erpl_idoc;
Success check

If installation worked you'll see no errors. erpl_idoc links no SAP libraries and makes no network calls — it's a pure, offline file engine.

Step 2: Read an IDoc file​

-- one row per data record: segment name, hierarchy, and the raw SDATA payload
SELECT segnam, hlevel, sdata
FROM sap_idoc_read('orders.idoc');

-- the envelope (control record) as 36 typed columns
SELECT idoctyp, mestyp, sndprn, rcvprn, credat
FROM sap_idoc_read_control('orders.idoc');

Every reader accepts a single path, a glob, or a LIST of paths, resolved through DuckDB's virtual filesystem — so a whole directory works, including remote stores (s3://…, http(s)://…, gs://…) once httpfs is loaded and a CREATE SECRET is set.

SELECT filename, idoctyp
FROM sap_idoc_read_control('s3://bucket/idocs/*.idoc', filename => true);

Step 3: Decode SDATA into typed columns​

SDATA is opaque fixed-width until you apply a segment dictionary. Point at one and get named, typed columns:

SELECT airlineid, flightdate, customerid, class, passname
FROM sap_idoc_read_segment('booking.idoc', 'E1BPSBONEW', 'flightbooking.dict.parquet');
-- LH | 20260715 | 00000042 | Y | MUELLER

Decode a whole IDoc — all segments, all fields — in one call:

SELECT segnam, field_name, value
FROM sap_idoc_read_fields('order.idoc', 'order_dict.csv');

See The segment dictionary for where a dictionary comes from (hand-authored offline, or fetched from a live system with erpl_rfc).

Step 4: Generate an IDoc file from SQL​

Compose records from your data and write a byte-valid IDoc:

COPY (
  SELECT raw_record
  FROM sap_idoc_read_raw('template.idoc')   -- or build records with the encoders
  ORDER BY record_index
) TO 'outbound.idoc' (FORMAT sap_idoc);

The writer recomputes derived fields (SEGNUM, PSGNUM, HLEVEL, lengths) for you. sap_idoc_read_raw → COPY (FORMAT sap_idoc) reproduces the input byte-for-byte.

Step 5: Convert flat ⇄ IDoc-XML​

-- flat → self-describing XML
SELECT xml FROM sap_idoc_to_xml('orders.idoc', 'orders.dict.parquet');

-- XML → flat (write it out)
COPY (
  SELECT raw_record
  FROM sap_idoc_xml_to_records('orders.xml', 'orders.dict.parquet')
  ORDER BY record_index
) TO 'orders.idoc' (FORMAT sap_idoc);

flat → xml → flat is byte-exact with the dictionary.

Next steps​