CenterForDigitalHumanities / CenterForDigitalHumanities/rerum_server_nodejs

Atlas Search index definitions are not in the repository

Aperta
#308 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
Lingua principale
JavaScript
Stelle
3
Fork
6
Merge medio
2g 47m
PR unite (30g)
4

Descrizione

## Summary

`/search` depends on two Atlas Search indexes, `presi3AnnotationText` and `presi2AnnotationText` (`controllers/search.js:84,153`). Their definitions exist only in the Atlas UI. Nothing in this repository describes which fields are indexed, with which analyzers, or how the two differ.

The consequence is that the current search behavior is not reviewable, not reproducible, and not diffable from source. A field path in `controllers/search.js` that the index does not cover fails silently — it simply matches nothing — and there is no artifact to check it against.

Small issue, no runtime change, and a genuine prerequisite for #309. Worth doing on its own merits regardless of what happens to that one.

## Why this matters

**The proposed fix cannot be reviewed without them.** #309 proposes a single combined index covering both vocabularies. Reviewing that proposal means comparing the new definition against the two it replaces. Right now that comparison can only happen by two people looking at the same browser tab.

**Search behavior can change with no commit.** An index edit in the Atlas UI changes what `/search` returns, with no diff, no review, and no record. When someone later asks why results changed, there is nothing to bisect.

**The pipelines assert paths nothing verifies.** `buildDualIndexQueries()` names specific paths — `body.value`, `bodyValue`, `resource.chars`, `resource.cnt:chars`, and several `embeddedDocument` traversals through `items.annotations.items`, `resources`, `otherContent`, and `sequences.canvases.otherContent.resources`. A path the index does not cover contributes zero matches and raises no error. With the definitions checked in, a reviewer can see the mismatch. Without them, only a targeted probe finds it.

**Environment drift is invisible.** Dev and production each have their own indexes. Whether they are actually identical is currently unknown and unknowable from source.

## Affected lines

| File | Line | Current |
|------|------|---------|
| `controllers/search.js` | 84 | `index: "presi3AnnotationText"` — defined only in Atlas |
| `controllers/search.js` | 153 | `index: "presi2AnnotationText"` — defined only in Atlas |
| `controllers/search.js` | 82-222 | `buildDualIndexQueries()` asserts field paths nothing in the repo verifies |

## Proposed change

Export both index definitions as JSON and commit them. `openapi/` is the existing precedent for a checked-in contract that describes something outside the code, so a sibling location under it, or a `database/` subdirectory, both fit; pick whichever matches how the team thinks about it rather than adding a new top-level directory.

Include for each index:

- The full JSON definition as Atlas reports it, exported from the UI or via the Atlas Admin API.
- Which deployment it was exported from, and on what date.
- A short README noting that these are a record of Atlas state, not something the application applies at startup, and how to re-export them.

Then check whether dev and production actually match, and record the answer. If they have drifted, that is worth its own issue.

Optionally, add a test that reads the checked-in definitions and asserts every path named in `buildDualIndexQueries()` is covered by the corresponding index. That turns the definitions from documentation into a guard, and it is the thing that would have caught a silently dead path. It is a nice-to-have, not a requirement for closing this.

## Notes

- No runtime change. Nothing depends on this landing, and #309 depends on it having landed.
- Checked-in definitions are a record, not a deployment mechanism. Applying them automatically would need the Atlas Admin API and credentials in CI, which is a larger decision and explicitly out of scope here.
- Related: [the detailed report on #306](https://github.com/CenterForDigitalHumanities/rerum_server_nodejs/issues/306#issuecomment-5529634333) raises this under Notes as "arguably worth doing first, independently of this issue".

## Acceptance criteria

- [ ] Both index definitions are committed as JSON, exactly as Atlas reports them
- [ ] Each records the deployment it came from and the date of export
- [ ] A README explains that these record Atlas state rather than being applied by the app, and documents how to re-export
- [ ] Dev and production definitions are compared and any drift is recorded

Guida per i contributori

Apri la guida per i contributori

Direzione di ricerca

Inizia da controllers/search.js:84,153 e buildDualIndexQueries() alle righe 82-222 per comprendere gli indici e i percorsi dei campi referenziati. Esporta entrambe le definizioni di Atlas Search dall’Atlas UI o dall’Admin API, confronta dev e production e segui il precedente di openapi/ nella scelta di una posizione registrata nel repository. Il lavoro è completato quando entrambe le definizioni JSON e un README riportano la fonte, le date di esportazione, il processo di riesportazione, lo stato di non deployment e qualsiasi divergenza tra gli ambienti.

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

Valutazione

Stack tecnologico
javascript
Ambito
documentation, search
Tipo di issue
Documentazione
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Attiva
Chiarezza
Specificata chiaramente
Idoneità per principianti
72/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.