Metadata-Version: 2.4
Name: drb-iceberg
Version: 0.2.0
Summary: DRB Iceberg add-on
Author: GAEL Systems
Author-email: drb-python@gael.fr
License: LGPLv3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Environment :: Plugins
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENCE.txt
Requires-Dist: drb<3,>=2.2
Requires-Dist: drb-metadata<2,>=1.4
Requires-Dist: drb-extractor~=1.3.0
Dynamic: license-file

# drb-iceberg

**Purpose:** Turn a product topic's `iceberg:` ontological configuration into a declarative `IcebergMapping` that describes table name, partitions, column extractors, and derived sub-tables. The add-on performs planning only — no Iceberg catalog I/O.

## Contract

`IcebergAddon.apply(node, topic=None, **kwargs)` returns an `IcebergMapping` object containing:
- `table`: main table name (string)
- `ingestible`: ingestion enabled (boolean)
- `ingest_priority`: optional priority level (int or None)
- `identifier`: unique key extractor (XQuery-based, not executed)
- `partitions`: list of partition field definitions
- `columns`: column schema with row extractors (delegated to `drb-metadata`)
- `derived`: list of derived (sub-)table definitions

The mapping is declarative: extractors are not executed by the add-on. A separate consumer processes the plan and executes row extraction/table writes.

## Dependencies

- `drb>=2.2,<3`
- `drb-metadata>=1.4,<2` — provides column extraction via `extract_for_class(class_uri, graph)`

## The `iceberg:` vocabulary

Attached to a product topic at namespace `http://www.gael.fr/iceberg#`:

| Term | Cardinality | Type | Meaning |
|---|---|---|---|
| `ingestible` | 1 | xs:boolean | Enables ingestion for this topic. |
| `targetTable` | 1 | string | Main table name, e.g. `sentinel1.products`. |
| `ingestPriority` | 0..1 | xs:int | Ingestion priority. |
| `identifier` | 1 | XQuery | Unique key of the product row. |
| `partitionStrategy` | 0..n | PartitionStrategy | Partition field/transform/order. |
| `derivedTable` | 0..n | DerivedTable | Sub-table definition. |

### PartitionStrategy

- `partitionField` (string) — field name
- `partitionTransform` (string: `identity`, `year`, `month`, `day`, etc.)
- `partitionOrder` (xs:int) — sort order

### DerivedTable

- `tableName` (string) — suffix appended to main table with a dot
- `entityListExtractor` (XQuery) — yields the list of row nodes
- `entityClass` (resource) OR `entityMetadataExtractor` (XQuery) — column source (`entityClass` wins if both present)
- `entityIdentifier` (XQuery) — unique key per row
