Graph Revision

Since v17.1, the backend semantic graph (Cadmus.Graph*) was revised, fixing several bugs (some of which caused data loss when updating or deleting the graph), making updates safe for concurrent users, and optimizing the database. The API is backwards compatible. See the graph updating page for the updated description of how the graph is kept in synch with data.

Main changes in behavior:

  • deleting an item or a part no longer deletes nodes still used by other sources or by users (with all their triples in cascade);
  • unique UIDs (ending with ##) no longer change at each save;
  • when a save generates no graph (e.g. all the mapped entries were removed), the graph previously generated from that source gets removed;
  • mapping filters now work as documented (group and title filters were applied in reverse, and flags required the opposite match), and children mappings are no longer run twice as root mappings.

Update

Solutions depending on these packages (API and CLI projects) should:

  1. update all the Cadmus packages to 17.1.0. No code change is required.
  2. databases: existing graph databases are upgraded in place at the first API startup (or with cadmus-tool create-db graph <name>). This only adds missing indexes and replaces a procedure, but on big graphs creating indexes may take some time. If the startup log shows a warning about URIs differing only by case, the unique URI index was not created: lookups still work, but you should merge these duplicate nodes. The upgrade requires the PostgreSQL pg_trgm extension (already required by the index database).
  3. mappings: as filters now work as documented, review the mappings using groupFilter, titleFilter or flagsFilter, and those with filters on values which may be missing (facet, part role, group, title): some of them may now apply to different sources. Any orphan mappings left by previous versions appear as root mappings: you can remove them, or re-import your mappings document after deleting all the mappings.
  4. graph data (optional): previous versions may have left in the graph stale nodes and triples, or nodes with UIDs suffixed by churn. To get a clean graph, you can delete it and rebuild it from data (e.g. with cadmus-tool graph-many), after re-importing mappings and presets. Otherwise, each item or part gets fixed when saved again.
  5. code (optional): use await updater.UpdateAsync(item, part) and await repository.DeleteGraphSetAsync(id) instead of their synchronous versions. Custom EfGraphRepository derived classes should override LockAsync and InsertMissingNodesAsync to be safe for concurrent writers.

Frontend: update @myrmidon/cadmus-api, @myrmidon/cadmus-graph-ui, and @myrmidon/cadmus-graph-ui-ex to get the fixes to the graph service, editors and walker (no code change is required).