Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

Add a hidden `_prov` attribute for extrinsic provenance at pipeline boundaries

Aperta
#1,547 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Funzionalità
Chiarezza
Da chiarire
Stato di attività
Attiva
Stack tecnologico
mysql, postgresql, python

Direzione di ricerca

Leggi src/datajoint/adapters/base.py e i percorsi degli adapter MySQL e PostgreSQL per capire come vengono dichiarati e resi persistenti gli attributi nascosti job*. Poi esamina il comportamento di inserimento di Entry, Ingest e del fan-out per determinare dove potrebbe essere applicato uno slot _prov. Per considerarlo completato, è necessario risolvere le domande aperte e definire il comportamento di implementazione, migrazione, validazione e propagazione.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

The gap

Intrinsic provenance is structural: a Compute table's row cannot exist unless its declared upstream exists and is correct, so the foreign-key graph is the lineage. Nothing needs to be recorded for that to hold.

At the boundary, the structure runs out. Rows arrive from outside the pipeline — an Entry table filled by a person or a feed, an Ingest table's make() reading a file the workflow does not track, or a fan-out write into Entry tables that carry no foreign key back to the writer. For those rows the framework has no way to say where they came from, and today each pipeline invents its own: a source_file column here, a notes varchar there, an ingestion log somewhere else, or nothing at all.

That is the one place where DataJoint's provenance story depends entirely on the workflow author's diligence, with no shape to conform to.

The precedent this should follow

The mechanism already exists in the codebase. config.jobs.add_job_metadata adds hidden attributes to Computed/Imported tables at declaration:

_job_start_time  datetime(3)
_job_duration    float
_job_version     varchar(64)

(src/datajoint/adapters/base.py, and per-adapter in mysql.py / the PostgreSQL path.) These are per-row, hidden from heading, written by populate, and durable on the table itself rather than in the job queue. That is the right shape and the right place — it just covers the automated side, where provenance is already intrinsic, and not the boundary, where it is not.

Proposal

A hidden _prov attribute, JSON-typed, on tables that take rows from outside the pipeline.

_prov  json  DEFAULT NULL   # extrinsic provenance for a row that entered from outside
  • Where: available on Entry and Ingest tables. A Compute table has no use for it, since its provenance is entailed.
  • Who writes it: the workflow author, at the point of entry — insert on an Entry table, or a fan-out write from inside a make(). The framework provides the slot and the shape; it cannot infer content it did not produce.
  • What it holds: at minimum the agent, the external source and record identifier, the time, and by what means. A conventional key set matters more than a rigid schema — the point is that two pipelines answering "where did this row come from" answer it in the same shape.
  • Master carries it; parts inherit. Consistent with how the master/part relationship works elsewhere.
  • Fan-out: inside make(), the intrinsic record of the ingesting table (its key, its _job_version) is available to propagate into each extrinsic destination, which is what makes a fanned-out row traceable without a foreign key.

Even when the source offers nothing useful — a nightly sync against a colony-management API — the author still records "received from PyRat at 02:15". A slot with a weak value beats no slot.

Why in the framework rather than left to each pipeline

Three things follow from having one shape:

  1. Export becomes mechanical. W3C PROV wants wasAttributedTo and wasDerivedFrom on exactly these rows; OpenLineage wants the same content run-centric. With per-pipeline conventions, every export is bespoke.
  2. The boundary becomes inspectable. "Which Entry rows have no recorded origin" turns into a query rather than an audit.
  3. ALCOA+ attributability lands where it belongs. Deployments that must answer attributable and contemporaneous for externally-sourced data currently have nowhere standard to put the answer.

Open questions

  • Default on or off? add_job_metadata defaults to False, and tables declared without it never get the columns — a migration edge worth not repeating. A _prov slot that is absent on most tables is a slot nobody codes against.
  • Validation. Enforce a minimal key set at insert, or accept any JSON and let deployments constrain it? Leaning toward the latter in the framework, with strictness as a deployment concern.
  • Interaction with allow_direct_insert. A direct insert into an Ingest table is already a modeling smell (datajoint-docs#267); should it require _prov?
  • Naming. _prov is short and matches the _job_* convention. _source or _origin would read more plainly to someone who has not met the term.

Related: datajoint-docs#267 (tier names on the entry/ingest axis), and the fan-out ingestion explanation, which currently tells authors to record source identity without giving them a place to record it.

Lingua principale
Python
Stelle
197
Fork
98
Merge medio
6g 7h
PR unite (30g)
1

Guida per i contributori

Apri la guida per i contributori

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di datajoint/datajoint-python

Tutte le issue di datajoint/datajoint-python

Issue simili

Altre issue su Python

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.