# Backends

`excelminer` uses a small pipeline of extractors (“backends”). Each backend can decide whether it can handle a given file (`can_handle`) and, if so, can add nodes/edges into a shared `WorkbookGraph`.

## OOXMLZipBackend (default)

- Purpose: Structural extraction via `.xlsx/.xlsm` OOXML ZIP contents.
- No Excel installation required.
- Typical outputs:
  - `sheet` nodes
  - `defined_name` nodes
  - `chart` nodes (when defined names are referenced in chart formulas)
  - `connection` and `source` nodes

Notes:
- Connection strings are sanitized (see [Security](SECURITY.md)).

## OpenpyxlBackend (default)

- Purpose: Extract formula text (not evaluated) and basic dependencies.
- Requires: `openpyxl` (included in base install).
- Runs when `include_formulas=True` or `include_cells=True`.

Outputs:
- `formula_cell` nodes (only when `include_formulas=True`)
- `contains` edges from `sheet` → `formula_cell`

Note:
- `include_cells=True` does not create cell blocks in this backend; it is used by the calamine backend.
- Formula scanning can switch to XML-only mode for large sheets (`formula_scan_mode` and `formula_large_sheet_cells`).
- Formula scans can be scoped by name/index and can skip pivot ranges (`formula_sheet_names`, `formula_sheet_indexes`, `formula_skip_pivot_cells`).

## CalamineBackend (optional)

- Purpose: Fast used-range discovery and cell sampling (“value blocks”).
- Requires: `excelminer[calamine]` (pandas + python-calamine).
- Runs only when `include_cells=True`.

Outputs:
- `cell_block` nodes
- `contains` edges from `sheet` → `cell_block`

## ComBackend (optional, Windows)

- Purpose: Enrichment via Microsoft Excel automation.
- Requires: Windows + Microsoft Excel + `excelminer[com]`.

Safety:
- Opt-in for modern formats (`include_com=True` for `.xlsx/.xlsm/.xltx/.xltm`).
- For legacy formats (`.xls/.xlsb/.xlt`), the COM backend may run without `include_com=True` (because OOXML parsing may not apply).
- Tests are opt-in because some environments can crash when Excel COM is invoked.

Outputs (when enabled):
- `sheet`, `defined_name`, `connection`, `source`, `formula_cell` nodes

If you don’t need COM-only artifacts, prefer OOXML + openpyxl for stability and portability.

## PowerQueryZipBackend (default)

- Purpose: Parse `xl/queries/*.xml` (when present) and emit `powerquery` nodes.
- Controlled by: `AnalysisOptions.include_powerquery`.

It also scans M code for common external source patterns (SQL/file/web/sharepoint/ODBC) and emits `source` nodes + `uses_source` edges. Each M script is emitted as an `m_script` node linked via `has_script`.

Mashup containers:

- Some workbooks store Power Query definitions in binary “mashup” parts (for example `xl/mashup/mashup.bin`) and may not include `xl/queries/*.xml`.
- In those cases, `excelminer` attempts a best-effort M script extraction. If extraction fails, it emits a synthetic `powerquery` node with `mashup_container=True` and basic part metadata.
- If `include_connections=True` and an OOXML `connection` node exists with the same `connection_id`, `excelminer` links `powerquery -> connection` via `uses_connection`.

## PivotZipBackend (default)

- Purpose: Parse pivot tables (`xl/pivotTables/*.xml`) and pivot cache definitions (`xl/pivotCache/*.xml`).
- Controlled by: `AnalysisOptions.include_pivots`.

Outputs:

- `pivot_table` nodes (with best-effort measures + grouping fields)
- `pivot_cache` nodes (with best-effort source reference)
- edges: `sheet -> pivot_table (contains)` and `pivot_table -> pivot_cache (uses_cache)`

## VbaZipBackend (default for macro-enabled OOXML)

- Purpose: Detect embedded VBA projects in macro-enabled OOXML workbooks (`.xlsm/.xltm/.xlam`).
- Controlled by: `AnalysisOptions.include_vba`.

Outputs:

- `vba_project` nodes (includes VBA module text when available)
