Explain the tier-naming axis: `Manual` means external-origin, not hand-entered
Mantenedores costumam responder em até 4 dias
@dimitri-yatsenko já está trabalhando nisso.
Desde 20/8/2026.
Avaliação
Esta issue ainda não foi avaliada.
Descrição
The problem
The two most-used tier names describe opposite axes, and each one names the axis the other actually means:
Manualnames the writer ("a person"), but the tier means the origin (data from outside the pipeline).Importednames the origin ("from elsewhere"), but the tier means the writer (the table's ownmake()).
The docs are consistent and correct about what the tiers mean. It is the class names that cross over, and a reader who reasons from the names alone will land in the wrong place.
The docs already explain Manual in different words than its name
- Table Declaration §1.2 —
Manualis "Data inserted at runtime from outside the pipeline (users, instruments, ingestion scripts)". Two of the three examples are automated. - Computation Model — "Manual and Lookup tables are not auto-populated; they are the entry points where a pipeline's data originates."
- Fan-Out Ingestion — "inserts into several entry-point tables (
ManualorImported)".
So the concept is already named "entry point" throughout the prose. Only the class is called Manual.
The failure mode this produces
A designer building an automated feed reasons, reasonably: "this table isn't filled manually — a sync script fills it — so it isn't Manual. It comes from outside, so it's Imported." They declare dj.Imported.
But Imported is defined as "populated by make()", and this table has no make() — it's filled by insert from elsewhere. So the insert is refused, and the fix that presents itself is allow_direct_insert=True rather than a corrected tier.
The result is a recognizable and diagnosable shape:
- an
Importedtable with nomake(), which reads to every later reader as a table whosemake()was forgotten; populate()on it silently doing nothing rather than erroring;- a permanent
allow_direct_insert=Truesuppressing a guard that was reporting a real problem; - the pipeline's actual boundary with the outside world drawn one table away from where it is.
Every step of that reasoning is sound except the premise that "manual" means "by hand."
Suggested docs changes (the near-term ask)
- State the axis explicitly, once, where tiers are introduced: the tier says how rows arrive, not who causes them to arrive. Rows inserted from outside the table →
Manual; rows produced by the table's ownmake()→Imported(reads an external source) orComputed(derives from other tables). - Say plainly that "manual" means external-origin, not hand-entered — an automated ingestion script inserts into a
Manualtable. The reference table hints at this with "ingestion scripts"; it deserves a sentence, not a parenthetical. - Add the failure mode as a short "common mistake" callout — an
Importedtable with nomake(), andallow_direct_insertas its tell. It is cheap to check and hard to spot by eye. - Consider a small 2×2 (origin: external / derived × writer: inserted /
make()) — it makesLookupandPartsit naturally alongside the other three and shows why only four of the cells are populated.
Forward-looking: a better name
dj.Entry would name the thing itself — a table where data enters the pipeline, by whatever hand — and it matches the vocabulary the explanation pages already use. It carries no implication about who or what does the writing, which is the whole source of the confusion.
That is a datajoint-python change, not a docs change, so it needs a decision there. Filing it here because the explanation is the fix available now and the naming question follows from it. If it were taken up, the obvious shape is dj.Entry as the primary name with dj.Manual kept permanently as a backward-compatible alias — no deprecation, no migration, existing pipelines and tutorials keep working, and new material can teach the clearer name. Renaming Imported is a harder call and probably not worth it; once the axis is stated, Imported reads correctly as "imported by this table."
Happy to open a PR for items 1–3 if the framing looks right.
- Linguagem predominante
- Jupyter Notebook
- Estrelas
- 7
- Forks
- 12
- Merge médio
- 3d 16h
- PRs com merge (30d)
- 15
Preparar o ambiente
- Inclui um Dockerfile ou arquivo Docker Compose
- Sem modelo de pull request
- Sem guia de contribuição
Primeiros passos
- Leia a issue inteira e depois o guia de contribuição do projeto.
- Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
- Faça um fork do repositório e trabalhe em uma branch.
- Abra um pull request que referencie o número da issue.
Mais de datajoint/datajoint-docs
-
documentation
Dificuldade 3/5 1-2 dias Facilidade para iniciantes 45/100
datajoint/datajoint-docs#301 ·
Mantenedores costumam responder em até 4 dias
-
Dificuldade 3/5 Meio dia Facilidade para iniciantes 55/100
datajoint/datajoint-docs#300 ·
Mantenedores costumam responder em até 4 dias
-
Dificuldade 3/5 Meio dia Facilidade para iniciantes 52/100
datajoint/datajoint-docs#299 · 1 comentário ·
Mantenedores costumam responder em até 4 dias
-
Dificuldade 3/5 1-2 dias Facilidade para iniciantes 55/100
datajoint/datajoint-docs#298 ·
Mantenedores costumam responder em até 4 dias
-
documentation
Dificuldade 3/5 1-2 dias Facilidade para iniciantes 45/100
datajoint/datajoint-docs#292 ·
Mantenedores costumam responder em até 4 dias