docs/RELEASE_NOTES_NEXT/Architecture/queued-ingest.adoc

   1 == Queued Ingest ==
   2
   3 This feature allows for the separation of bib and authority record
   4 updates and the search (and other) indexing that occurs when a record is
   5 modified in some way. Prior to this feature, bib and authority records
   6 would be indexed immediately upon an update.
   7
   8 While individual record ingest has not become a problem with regard to
   9 system performance or interface usability, there exist several batch
  10 operations which aggregate many inserts or updates and whose aggregate
  11 ingest time cost can be significant.  These include, but are not
  12 limited to, reingest caused by authority control propagation, reingest
  13 required by the addition or modification of indexing configuration,
  14 cataloging and acquisitions record import and overlay from the staff
  15 interface, and upgrade-time reingest required by structural changes
  16 to the underlying indexing and search system.
  17
  18 === New Utility ===
  19
  20 When Queued Ingest is enabled, a new control script, `ingest_ctl`, is
  21 available to perform several functions:
  22
  23 * Run in the background to process the queues of indexing requests
  24 * Display statistics of queued ingest activity
  25 * Specify that a set of records should be reindexed.
  26
  27 Here are some examples of how it is used:
  28
  29 [source,bash]
  30 ------------------------------------------------------------------------------------
  31 # Enqueue records 1-500000 for reingest later, just one worker for the queue
  32 /openils/bin/ingest_ctl --queue-threads 1
  33     --queue-type biblio
  34     --queue-run-at tomorrow
  35     --queue-owner admin
  36     --queue-name "slowly updating records due to new RDA attributes"
  37     --start-id 1 --end-id 500000
  38
  39 # Start the background worker
  40 /openils/bin/ingest_ctl --coordinator --max-child 20
  41
  42 # Stop the background worker
  43 /openils/bin/ingest_ctl --coordinator --stop
  44
  45 # Process whatever you can Right Now
  46 /openils/bin/ingest_ctl --max-child 20
  47
  48 # Process a single queue Right Now
  49 /openils/bin/ingest_ctl --queue 1234 --max-child 20
  50
  51 # Stats on Queued Ingest processing so far today
  52 /openils/bin/ingest_ctl --stats --since today --totals-only
  53 ------------------------------------------------------------------------------------
  54
  55 This script also requires the following switches (or environment
  56 variables) in order to connect to the database:
  57
  58 * `--db_user` (or environment variable `PGUSER`)
  59 * `--db` (or environment variable `PGDATABASE`)
  60 * `--dbpw` (or environment variable `PGPASSWORD`)
  61 * `--db_port` (or environment variable `PGPORT`)
  62
  63 === New Settings ===
  64
  65 This feature adds several new global flags:
  66
  67
  68 |===
  69 | Global Flag | Enabled
  70
  71 | Queued Ingest: Abort transaction on ingest error rather than simply logging an error | no
  72 | Queued Ingest: Queue all bib record updates on authority change propagation, even if bib queuing is not generally enabled | no
  73 | Queued Ingest: Use Queued Ingest for bib record ingest on insert and undelete | no
  74 | Queued Ingest: Use Queued Ingest for authority record ingest on insert and undelete | no
  75 | Queued Ingest: Use Queued Ingest for bib record ingest on update | no
  76 | Queued Ingest: Use Queued Ingest for authority record ingest on update | no
  77 | Queued Ingest: Use Queued Ingest for bib record ingest on delete | no
  78 | Queued Ingest: Use Queued Ingest for authority record ingest on delete | no
  79 | Queued Ingest: Maximum number of database workers allowed for queued ingest processes | yes; default value 20
  80 | Queued Ingest: Use Queued Ingest for all bib record ingest | no
  81 | Queued Ingest: Use Queued Ingest for all bib and authority record ingest | no
  82 | Queued Ingest: Do NOT use Queued Ingest when creating a new bib, or undeleting a bib, via the MARC editor | yes
  83 | Queued Ingest: Use Queued Ingest for all authority record ingest | no
  84 | Queued Ingest: Do NOT Use Queued Ingest when editing bib records via the MARC Editor | yes
  85 |===
  86
  87 This feature does not add any new library settings or permissions.
  88
  89 === Upgrade Notes ===
  90
  91 Queued Ingest is not automatically turned on upon upgrade. to enable it,
  92 at minimum the following actions should be taken:
  93
  94 * Enable at least the "Use Queued Ingest for all bib and authority record
  95   ingest" global flag
  96 * Ensure that `ingest_ctl` is running with the `--coordinator` flag.