This page provides information about standards and guidelines for queries to the CUL FOLIO Canned Reports Directory.
Some of these standards are adapted from the Open Library Foundation's FOLIO Analytics report repository.
Most queries include parameters that allow those running the reports to adapt the result set to their needs. For instance, if you are
interested in a report showing loan activity for one library location, you can include that location in the parameters to filter your results.
Filter parameters are include at the top of the query in the WITH statement. For example,
WITH parameters AS (
SELECT
/* enter invoice payment start date and end date in YYYY-MM-DD format */
'2021-07-01' :: DATE AS start_date,
'2022-06-30' :: DATE AS end_date,
/* enter fund group name as 'Central, Humanities, Area Studies, Rare & Distinctive, Law, Sciences, or Social Sciences' */
''::VARCHAR AS fund_group_filter,
/* enter one or more fund codes separated by commas, as in 'math, music' */
''::VARCHAR AS fund_code_filter,
/* enter one or more fund types separated by commas, as in 'restricted, unrestricted' */
''::VARCHAR AS fund_type_filter,
),
All canned reports developed for the CUL FOLIO Analytics repository are coded with "CR"
followed by a 3-digit number and a short title with words separated by underscores,
as shown in these examples:
* CR104 claims_returned
* CR123 open_orders
* CR130 fund_expenditures_by_po_line
Each canned query must be submitted with an associated README.md file. The README.md file
documents the purpose of the query, lists the main tables used in the query, and provides
instructions for using the query.
spacing/indentation
include example
SELECT
sp.name AS service_point_name,
m.name AS material_type,
i.barcode AS item_barcode,
...
SELECT sp.name AS service_point_name,
m.name AS material_type,
i.barcode AS item_barcode,
...
loan_date BETWEEN (SELECT start_date FROM parameters) AND
(SELECT end_date FROM parameters)
keywords
SELECT
'2019-01-01' :: DATE
AS
for aliasing (columns, subqueries, tables, etc.)blank lines
punctuation
,
at end of line(
at end of line)
at beginning of line, lined up with keyword from line with (type conversion
' :: '
followed by data type in upper case (e.g., VARCHAR
, DATE
)comments
/* ... */
for multi-line comments--
for single line commentsfile name
selecting fields
SELECT *
. List all fields explicitly.WITH
statement)WITH
statements to label subqueries (see services_usage query for example) - optionalWITH
statementsWITH
to create temporary tables at the beginning of the query that then get used laterWITH
statement goes straight into primary SELECT
statement for query, do not need a comma after last WITH
statementWITH
statements you can specify the column names before the SELECT
statement, the code is more readable if you continue to alias the columns with AS
instead the SELECT
statement (see services_usage query)COALESCE
, which allows you to specify a default value if the result is nullSELECT
statement because of the joins that will build on itLEFT JOIN
vs. INNER JOIN
LEFT JOIN
makes sure you don't accidentally lose the items you're most interestedLEFT JOIN
to keep all loans even if you don't know the user's demographicsBETWEEN
BETWEEN
for dates is risky because it only includes records up to midnight of the end date (essentially, the end of the day before, but it will include items exactly at midnight of the end date)BETWEEN
, try to educate people about its behavior in comments and set default values that make sense for the behavior (e.g., the first day of one year and the first day of the following year, instead of the last day of the year)>= start_date
and < end_date
instead of BETWEEN
. This is like using BETWEEN
except that you use <
instead of <=
. You still have to use an end date that will not be included in the date range (i.e., the day after the last day you want included).WITH
statements