Build Metadb query cookbook-style documentation

Owned by Angela Zoss (Old)
Last updated: Feb 28, 2023

proposed structure:

  • Really good title (“Look up details for an item in circulation”, something that works for library analysts and is general enough to extend to similar problems)
  • General recipe
    • Tables where you can find this data
    • How the tables connect
    • What fields you might want to select or filter on
    • Consider including a glossary inside the recipe page for acronyms or functions used - what they mean, what they're doing in the query
  • Includes “Tips” or “Things to Think About” section: how to avoid duplicates, data model considerations
    • Check out carpentries or O’Reilly books
    • Tips for date range filters
    • don't run queries while the database is updating (less of an issue for Metadb); or, issues with data being out of sync

Additional/related request: also include specific SQL topics that might be useful to explain because they are used in a lot of the current queries, e.g.:

  • 0 vs NULL vs “” vs BLANK vs EQUALS in WHERE clause
  • Ranges in WHERE clause
  • Improving speed of slow queries (not needed in most cases)
    • VACUUM/ANALYZE
    • INDEXING


Examples from Nassib:

https://github.com/folio-org/folio-analytics/tree/main/cookbook

  • Suggestion: include a glossary inside the recipe page for acronyms or functions used - what they mean, what they're doing in the query


Example from Eliana:

LDP SQL Tutorial


Examples from O'Reilly Cookbooks