Documentation: Migrate reports documentation from 2.1
[working/Evergreen.git] / docs / reports / reporter_template_terminology.txt
1 Template Terminology\r
2 --------------------\r
3 \r
4 Data Types\r
5 ~~~~~~~~~~\r
6 \r
7 indexterm:[reports, data types]\r
8 \r
9 The central column of the _Database Source Browser_ lists _Field Name_ and _Data \r
10 Type_ for the selected database table.\r
11 \r
12 +\r
13 image::media/view-output-2.png[view-output-2]\r
14 +\r
15 \r
16 Each data type has its own characteristics and uses:\r
17 \r
18 [options="header,footer"]\r
19 |====================================\r
20 |Data Type      |Description    |Notes\r
21 |id             |Unique number assigned by the database to identify a \r
22 record  |A number that is a meaningful reference for the database but not \r
23 of much use to a human user. Use in displayed fields when counting records or \r
24 in filters.\r
25 |text   |Text field     |Usually uses the Raw Data transform.\r
26 |timestamp      |Exact date and time    |Select appropriate date/time transform. \r
27 Raw Data includes second and timezone information, usually more than is required \r
28 for a report.\r
29 |bool   |True or False  |Commonly used to filter out deleted item or patron records.\r
30 |org_unit       |A number representing a library, library system, or \r
31 federation      |When you want to filter on a library, make sure that the field \r
32 name is on an org_unit or id data type.\r
33 |link   |A link to another database table       |Link outputs a number that is a \r
34 meaningful reference for the database but not of much use to a human user. You \r
35 will usually want to drill further down the tree in the Sources pane and select \r
36 fields from the linked table. However, in some instances you might want to use \r
37 a link field. For example, to count the number of patrons who borrowed items you \r
38 could do a count on the Patron link data.\r
39 |int    |Integer         \r
40 |money  |Number (in dollars)     \r
41 |=====================================\r
42 \r
43 Field Transforms\r
44 ~~~~~~~~~~~~~~~~\r
45 \r
46 indexterm:[reports, field transforms]\r
47 \r
48 A _Field Transform_ tells the reporter how to process a field for output. \r
49 Different data types have different transform options.\r
50 \r
51 indexterm:[reports, field transforms, raw data]\r
52 \r
53 *Raw Data*.  To display a field exactly as it appears in the database use the \r
54 _Raw Data_ transform, available for all data types.\r
55 \r
56 indexterm:[reports, field transforms, count]\r
57 \r
58 indexterm:[reports, field transforms, raw distinct]\r
59 \r
60 *Count and Count Distinct*.  These transforms apply to the _id_ data type and \r
61 are used to count database records (e.g. for circulation statistics). Use Count \r
62 to tally the total number of records. Use _Count Distinct_ to count the number \r
63 of unique records, removing duplicates.\r
64 \r
65 To demonstrate the difference between _Count_ and _Count Distinct_, consider an \r
66 example where you want to know the number of active patrons in a given month, \r
67 where ``active" means they borrowed at least one item. Each circulation is linked \r
68 to a _Patron ID_, a number identifying the patron who borrowed the item. If we use \r
69 the _Count Distinct_ transform for Patron IDs we will know the number of unique \r
70 patrons who circulated at least one book (2 patrons in the table below). If \r
71 instead, we use _Count_, we will know how many books were circulated, since every \r
72 circulation is linked to a _patron ID_ and duplicate values are also counted. To \r
73 identify the number of active patrons in this example the _Count Distinct_ \r
74 transform should be used.\r
75 \r
76 [options="header,footer"]\r
77 |====================================\r
78 |Title  |Patron ID      |Patron Name\r
79 |Harry Potter and the Chamber of Secrets        |001    |John Doe\r
80 |Northern Lights        |001    |John Doe\r
81 |Harry Potter and the Philosopher’s Stone     |222    |Jane Doe\r
82 |====================================\r
83 \r
84 indexterm:[reports, field transforms, output type]\r
85 \r
86 *Output Type*.  Note that each transform has either an _Aggregate_ or \r
87 _Non-Aggregate_ output type.\r
88 \r
89 indexterm:[reports, field transforms, output type, non-aggregate]\r
90 \r
91 indexterm:[reports, field transforms, output type, aggregate]\r
92 \r
93 Selecting a _Non-Aggregate_ output type will return one row of output in your \r
94 report for each row in the database. Selecting an Aggregate output type will \r
95 group together several rows of the database and return just one row of output \r
96 with, say, the average value or the total count for that group. Other common \r
97 aggregate types include minimum, maximum, and sum.\r
98 \r
99 When used as filters, non-aggregate and aggregate types correspond to _Base_ and \r
100 _Aggregate_ filters respectively. To see the difference between a base filter and \r
101 an aggregate filter, imagine that you are creating a report to count the number \r
102 of circulations in January. This would require a base filter to specify the \r
103 month of interest because the month is a non-aggregate output type. Now imagine \r
104 that you wish to list all items with more than 25 holds. This would require an \r
105 aggregate filter on the number of holds per item because you must use an \r
106 aggregate output type to count the holds.\r
107 \r