Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

Explain the tier-naming axis: `Manual` means external-origin, not hand-entered

Fechada
#267 9 comentários 0 reações 1 responsável Ver no GitHub

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:

  • Manual names the writer ("a person"), but the tier means the origin (data from outside the pipeline).
  • Imported names the origin ("from elsewhere"), but the tier means the writer (the table's own make()).

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 — Manual is "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 (Manual or Imported)".

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 Imported table with no make(), which reads to every later reader as a table whose make() was forgotten;
  • populate() on it silently doing nothing rather than erroring;
  • a permanent allow_direct_insert=True suppressing 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)

  1. 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 own make() → Imported (reads an external source) or Computed (derives from other tables).
  2. Say plainly that "manual" means external-origin, not hand-entered — an automated ingestion script inserts into a Manual table. The reference table hints at this with "ingestion scripts"; it deserves a sentence, not a parenthetical.
  3. Add the failure mode as a short "common mistake" callout — an Imported table with no make(), and allow_direct_insert as its tell. It is cheap to check and hard to spot by eye.
  4. Consider a small 2×2 (origin: external / derived × writer: inserted / make()) — it makes Lookup and Part sit 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

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de datajoint/datajoint-docs

Todas as issues de datajoint/datajoint-docs

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.