Entity: dataImport

Entity Type: Database table

Description: A bulk import batch — created when a user uploads a file (or an automated pipeline ingests one) to create or edit multiple records at once. Referenced directly by the entities it produced (e.g. invoice.importId) rather than through a generic polymorphic join table. Shared across domains: used by Invoice Ingestion, Reading Ingestion, and Gauge Management alike.

Data Attributes Table

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key of the entity.	UUID	Generated in code (app layer)	Yes	Yes	UUID v7	-	Primary Key	018f6e2a-1234-7abc-9def-0123456789ab
tenantId	Tenant this batch belongs to. Collapses EM2's separate client FK — client and tenant are the same concept in EM3.	UUID	-	Yes	No	UUID v7	Foreign Key → tenant; must exist	-	018fa51f-fda1-79f4-8461-2cb8f1cabc10
type	What kind of data this batch contains.	Enum	-	Yes	No	enum	-	-	invoices
sourceType	How this batch was created. New in EM3 — no EM2 equivalent.	Enum	-	Yes	No	enum	-	-	bulkImport
fileId	The originally uploaded source file for this batch (e.g. the XLSX or ISDOC-XML file). One file per batch, not per produced record.	UUID	-	No	No	UUID v7	Foreign Key → file; must exist if set	-	018fa51f-fda4-7e95-88e8-5f5675f0ddf8
statusMessage	Free-text summary of the import outcome.	String	-	No	No	-	-	-	Completed with 2 warnings
reportInfo	Structured outcome of the import — counts and messages, queryable rather than just a flash message. Carried over from EM2's identically-shaped JSON blob.	JSONB	{}	Yes	No	See reportInfo.md	-	-	{"messages":{"success":120,"warning":2,"error":0},"errorRows":[],"backupRows":[]}
createdAt	Timestamp of entity creation. Immutable.	Timestamp with time zone	now()	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	2026-01-15T09:00:00Z
updatedAt	Timestamp of last entity update. Mutable.	Timestamp with time zone	now()	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	-	-	2026-01-15T09:00:00Z
deletedAt	Timestamp of entity soft delete. Once set, immutable.	Timestamp with time zone	-	No	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Immutable once set. Active records: WHERE deletedAt IS NULL	-	null
createdBy	Identifier of the author who created this record.	String	-	Yes	No	type:actor	-	-	user:c2d3f586-1c9a-4f5f-b9ae-45f2c4f69f7e
updatedBy	Identifier of the author who last updated this record.	String	-	Yes	No	type:actor	-	-	system:invoice-import-v1
legacyId	Legacy-system identifier; migration provenance.	String	null	No	No	-	-	UNIQUE (tenantId, legacySource, legacyId) WHERE legacyId IS NOT NULL	3312
legacySource	Which legacy table this batch was migrated from.	String (enum)	null	No	No	enum: data_import	Must equal the listed value, or null	(composite with legacyId above)	data_import

Note. EM2's polymorphic DataImportItem join table (generic itemClass+itemId+import) is not carried over — the entities produced by an import (invoice, reading, gauge) each reference their dataImport directly via importId, which already provides the same association without a generic join table.

Audited fields

Recorded on created (in full) only — no update or delete path exists on this entity: type, sourceType, fileId, statusMessage, reportInfo, legacyId, legacySource.

Excluded: none.

fileId targets file, not document — corrected above; 202608261002-data-import-file-fk.sql retargeted the constraint once file existed, so the earlier "depends on Epic 9.1" note no longer applies.

Not registered for entityName resolution — a batch identified by its type/sourceType/timestamp, not a name a person would type.