dre_core/config/
report.rs

1//! The shape of a report YAML file under `reports/` (one fragment of a report: a report may be
2//! split over several files, merged by name).
3//!
4//! Values the loader checks itself, to say what's wrong in DRE's words, are [`Loose`]. Outputs and
5//! Sets are read where they're used.
6
7use schemars::JsonSchema;
8use serde::Deserialize;
9use serde::de::IgnoredAny;
10
11use super::de::{Located, Loose, Map, Maybe, OneOf, UnknownKeys};
12
13type JsonMap = serde_json::Map<String, serde_json::Value>;
14
15/// One `queries:` item: a query's name, or a query with settings.
16pub type QueryItem = Located<Loose<OneOf<String, QueryEntry>>>;
17
18/// A report: SQL queries plus an output, in a YAML file under `reports/`.
19#[derive(Default, Deserialize, JsonSchema)]
20#[schemars(title = "DRE report", deny_unknown_fields)]
21pub struct ReportFile {
22    /// The report's name. Default: the name of the folder the YAML file is in. Report names are unique across the project.
23    #[schemars(length(min = 1))]
24    pub name: Option<Located<Loose<String>>>,
25    /// What this report answers, including its business definitions and units.
26    pub description: Option<Located<Loose<String>>>,
27    /// Metadata for external tools. DRE checks its shape, not the meaning of its keys.
28    pub meta: Option<Located<Loose<JsonMap>>>,
29    /// Tags to select the report with, `-s tag:<tag>`.
30    pub tags: Option<Located<Loose<Vec<String>>>>,
31    /// The `.sql` files whose results make the report's tabs, in the order they run, on one database session.
32    #[serde(default)]
33    #[schemars(schema_with = "queries")]
34    pub queries: Option<Located<Loose<Vec<QueryItem>>>>,
35    /// One output, or a list of outputs formatted from the same run of the queries (file outputs are delivered before messages). A list replaces the inherited output; a map changes it.
36    #[serde(default)]
37    #[schemars(schema_with = "output_or_list")]
38    pub output: Option<IgnoredAny>,
39    /// The connection (in `profiles.yml`) the queries run on, unless a query's own `profile:` or a source's says otherwise. Default: the folder's `+profile`, then `default_profile`. Can't be combined with `sets`. May use Jinja with `var()`, `env_var()`, `run.*` and `target.name`.
40    pub profile: Option<Located<Loose<String>>>,
41    /// The Sets the report can run as, by name (declared in `sets.yml`) or declared here.
42    pub sets: Option<Located<Loose<Vec<SetItem>>>>,
43    /// The Set a plain `dre run` uses. Must be one of `sets`.
44    pub default_set: Option<Located<Loose<String>>>,
45    /// Variables, read in SQL and YAML with `var('name')`. Values can be strings, numbers, booleans, lists or maps.
46    pub vars: Option<Located<Loose<JsonMap>>>,
47    /// Optional declarations for variables: type, default, allowed values, description, required, and for strings a pattern and max_length.
48    /// Kept separate from `vars` so a map-valued variable remains a plain value.
49    pub var_schema: Option<Located<Loose<crate::variables::Definitions>>>,
50    /// The timezone `run.date` and `run.now` use, an IANA name such as `Australia/Sydney`. Default: UTC.
51    pub timezone: Option<Located<Loose<String>>>,
52    /// The locale this report's number filters format for (`de-DE`). Default: the folder's `+locale`, then the project's `locale`, then `en`.
53    pub locale: Option<Located<Loose<String>>>,
54    /// The plugin packages this project uses. DRE installs them on demand into `dre_deps/` and pins them in `dre.lock`. May be written in any project YAML file; `dependencies.yml` is the usual place.
55    #[serde(default)]
56    #[schemars(schema_with = "super::dependencies::plugins")]
57    pub plugins: Option<IgnoredAny>,
58    /// dbt-style source declarations (see the sources schema). May be written in any project YAML file.
59    #[serde(default)]
60    #[schemars(schema_with = "super::project::sources_ref")]
61    pub sources: Option<IgnoredAny>,
62    /// Removed: schedules live in schedules.yml. Read only to say so.
63    #[schemars(skip)]
64    pub schedule: Option<Located<IgnoredAny>>,
65    #[serde(rename = "$unknown", default)]
66    #[schemars(skip)]
67    pub unknown: UnknownKeys,
68}
69
70/// A query with settings, instead of just its name.
71#[derive(Deserialize, JsonSchema)]
72#[schemars(rename = "queryEntry", deny_unknown_fields)]
73pub struct QueryEntry {
74    /// The name of a `.sql` file under `reports/`, without folder or extension.
75    #[schemars(required)]
76    pub query: Option<Loose<String>>,
77    /// The connection this query runs on, over the report's, Set's, folder's and project's. Must agree with the `profile` of any source it uses. May use Jinja with `var()`, `env_var()`, `run.*` and `target.name`.
78    pub profile: Option<Loose<String>>,
79    /// `false` runs the file only for what it does (temp tables, `SET`s) and discards any result, so it gets no tab.
80    #[schemars(extend("default" = true))]
81    pub tab: Option<Loose<bool>>,
82    /// The tab (sheet) name. Default: the file's name. Not allowed with `tab: false`.
83    pub tab_name: Option<Loose<String>>,
84    /// Where the data starts on the sheet (xlsx only). Default: `A1`.
85    #[schemars(regex(pattern = "^[A-Za-z]{1,3}[0-9]+$"))]
86    pub anchor: Option<Loose<String>>,
87    /// Whether to write the column names as the first row (xlsx only). Default: the output's `header`.
88    pub header: Option<Loose<bool>>,
89    /// Per-column settings for this tab, by column name (xlsx only).
90    #[serde(default)]
91    #[schemars(schema_with = "columns")]
92    pub columns: Option<serde_json::Value>,
93    /// Size this tab's columns from their content (xlsx only), over the output's `autofit`. Default: the output's, which is on.
94    pub autofit: Option<Loose<bool>>,
95    /// How this tab looks (xlsx only), over the output's `style`: `font`, `header`, `totals`, `banded_rows`, `borders`, and cell keys (`bold`, `fill`, ...) for every data cell. See the xlsx plugin page.
96    #[serde(default)]
97    #[schemars(schema_with = "sheet_style")]
98    pub style: Option<serde_json::Value>,
99    #[serde(rename = "$unknown", default)]
100    #[schemars(skip)]
101    pub unknown: UnknownKeys,
102}
103
104fn sheet_style(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
105    schemars::json_schema!({
106        "type": "object",
107        "description": "How an xlsx tab looks. Cell keys apply to every data cell; `header` and `totals` take cell keys for those rows.",
108        "properties": {
109            "header": {"type": "object", "description": "Cell keys for the header row (default: bold)."},
110            "totals": {"type": "object", "description": "Cell keys for the totals row (default: bold, a thin top border)."},
111            "banded_rows": {"oneOf": [{"type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$"}, {"const": false}], "description": "The fill of every other data row, `\"#RRGGBB\"`, or `false`."},
112            "borders": {"enum": ["none", "thin", "medium"], "description": "A border around every cell of the table."},
113            "bold": {"type": "boolean", "description": "Bold text in every data cell."},
114            "italic": {"type": "boolean", "description": "Italic text in every data cell."},
115            "underline": {"type": "boolean", "description": "Underlined text in every data cell."},
116            "font": {"type": "object", "description": "The font: `{name: Calibri, size: 11}`.", "properties": {"name": {"type": "string", "description": "The font's name."}, "size": {"type": "number", "description": "The size in points."}}, "additionalProperties": false},
117            "font_color": {"type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$", "description": "The text colour, `\"#RRGGBB\"`."},
118            "fill": {"type": "string", "pattern": "^#?[0-9A-Fa-f]{6}$", "description": "The background colour, `\"#RRGGBB\"`."},
119            "align": {"enum": ["left", "center", "right"], "description": "Horizontal alignment."},
120            "border": {"enum": ["none", "thin", "medium"], "description": "A border around each data cell."}
121        },
122        "additionalProperties": false
123    })
124}
125
126fn columns(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
127    schemars::json_schema!({
128        "type": "object",
129        "additionalProperties": {
130            "type": "object",
131            "description": "Settings for one column of an xlsx tab.",
132            "properties": {
133                "format": {"type": "string", "description": "The Excel number format of the column, e.g. `#,##0.00` or `dd/mm/yyyy`. See the xlsx column formats in the plugins reference."},
134                "formula": {"type": "string", "description": "An Excel formula for each row of this column; `{name}` stands for that column's cell on the same row, e.g. `=ROUND({qty}*{unit_price},2)`. The SQL selects a placeholder column where the formula goes."},
135                "total": {"type": "string", "description": "Puts a total under the column: one of `sum`, `count`, `average`, `min`, `max`, or a formula such as `=SUM({net:*})`."},
136                "style": {"type": "object", "description": "How the column's data cells look: `bold`, `italic`, `underline`, `font` (`{name, size}`), `font_color`, `fill` (`\"#RRGGBB\"`), `align` (`left`, `center`, `right`), `border` (`none`, `thin`, `medium`). Over the tab's and output's `style`."},
137                "width": {"oneOf": [{"const": "auto"}, {"type": "number", "exclusiveMinimum": 0, "maximum": 255}], "description": "The column's width: `auto` (sized from its content, at most 60 characters) or a number of characters. Over the tab's and output's `autofit`."}
138            },
139            "additionalProperties": false
140        },
141        "propertyNames": {"minLength": 1}
142    })
143}
144
145/// One `sets:` item: a Set's name (declared in `sets.yml`), or a Set declared here.
146pub type SetItem = Located<Loose<OneOf<String, SetEntry>>>;
147
148/// A Set declared in the report: a named variant of it.
149#[derive(Deserialize, JsonSchema)]
150#[schemars(rename = "setEntry", deny_unknown_fields)]
151pub struct SetEntry {
152    /// The Set's name. A report can also name Sets declared in `sets.yml`.
153    #[schemars(required)]
154    pub name: Option<Loose<String>>,
155    /// The connection this Set runs on. May use Jinja with `var()`, `env_var()`, `run.*` and `target.name`.
156    pub profile: Option<Located<Loose<String>>>,
157    /// Variables, read in SQL and YAML with `var('name')`. Values can be strings, numbers, booleans, lists or maps.
158    #[serde(default)]
159    #[schemars(schema_with = "any_map")]
160    pub vars: Option<Loose<JsonMap>>,
161    /// Queries to leave out of this Set, by name.
162    pub exclude: Option<Located<Loose<Vec<String>>>>,
163    /// Replaces the report's queries for this Set.
164    #[serde(default)]
165    #[schemars(schema_with = "set_queries")]
166    pub queries: Option<Located<Loose<Vec<SetQueryItem>>>>,
167    /// Renames tabs for this Set: query name to tab name.
168    #[serde(default)]
169    #[schemars(schema_with = "tab_names")]
170    pub tab_names: Option<Loose<JsonMap>>,
171    /// Output settings for this Set: a map changes the inherited output (with several, the one its `name:` names); a list replaces them all.
172    #[serde(default)]
173    #[schemars(schema_with = "output_or_list")]
174    pub output: Option<serde_json::Value>,
175    /// The locale for this Set's number filters (`fr-FR`), above the report's.
176    pub locale: Option<Loose<String>>,
177    /// Removed: schedules live in schedules.yml. Read only to say so.
178    #[schemars(skip)]
179    pub schedule: Option<IgnoredAny>,
180    #[serde(rename = "$unknown", default)]
181    #[schemars(skip)]
182    pub unknown: UnknownKeys,
183}
184
185/// One item of a Set's `queries:`: a query's name, or a query with settings.
186pub type SetQueryItem = Loose<OneOf<String, SetQuery>>;
187
188/// A query of a Set with its own settings.
189#[derive(Deserialize)]
190pub struct SetQuery {
191    pub query: Option<Loose<String>>,
192    pub tab: Option<Loose<bool>>,
193    pub tab_name: Option<Loose<String>>,
194}
195
196fn any_map(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
197    schemars::json_schema!({"type": "object", "additionalProperties": true})
198}
199
200fn tab_names(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
201    schemars::json_schema!({"type": "object", "additionalProperties": {"type": "string"}})
202}
203
204fn output_or_list(g: &mut schemars::SchemaGenerator) -> schemars::Schema {
205    let output = g.subschema_for::<Output>();
206    schemars::json_schema!({
207        "oneOf": [output, {"type": "array", "minItems": 1, "items": output}]
208    })
209}
210
211fn set_queries(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
212    schemars::json_schema!({
213        "type": "array",
214        "items": {
215            "description": "A query of this Set, by name, or with its own settings.",
216            "oneOf": [
217                {"type": "string"},
218                {
219                    "type": "object",
220                    "description": "A query with settings.",
221                    "properties": {
222                        "query": {"type": "string", "description": "The query's name."},
223                        "tab": {"type": "boolean", "description": "Whether the query makes a tab."},
224                        "tab_name": {"type": "string", "description": "The tab name."}
225                    },
226                    "required": ["query"],
227                    "additionalProperties": true
228                }
229            ]
230        }
231    })
232}
233
234/// How a report's result is written and where it goes. Besides the keys below, each format takes its own options (for example `delimiter` for `delimited`, `columns` for `fixed_width`, `text` for `message`); they are documented with the formats.
235// Outputs are layered (the built-in default, `default_output`, each folder's `+output`, the
236// report's and a Set's `output`) and read once merged.
237#[derive(Deserialize, JsonSchema)]
238#[schemars(rename = "output", extend("additionalProperties" = true))]
239pub struct Output {
240    /// Names the output so other outputs and Set overrides can refer to it (`outputs.<name>` in a message, `attach:`). Also the default file name (`<name>.<ext>`). Unique within the report.
241    #[schemars(regex(pattern = "^[A-Za-z_][A-Za-z0-9_]*$"))]
242    pub name: Option<Loose<String>>,
243    /// The output format: `message` (built in: a short headline rendered from the results), or `csv`, `delimited`, `fixed_width`, `parquet` or `xlsx` (each a plugin). Default: `csv`, or the project's `default_output`.
244    pub format: Option<Loose<String>>,
245    /// Which of the report's queries this output formats. Default: all of them. Each query runs once, whatever the number of outputs.
246    #[schemars(length(min = 1))]
247    pub queries: Option<Loose<Vec<String>>>,
248    /// A Jinja expression over the results (`results.<query>.value < 0`); when it's false, the output is skipped and recorded as `skipped`.
249    #[serde(default)]
250    #[schemars(schema_with = "string_or_bool")]
251    pub when: Option<Loose<OneOf<String, bool>>>,
252    /// Where to deliver the file: one destination, or a list to deliver to several in one run. Default: the file stays in the target path.
253    #[serde(default)]
254    #[schemars(schema_with = "destination_or_list")]
255    pub destination: Option<Loose<OneOf<Destination, Vec<Loose<Destination>>>>>,
256    pub template: Option<Loose<Template>>,
257    /// File extension for text formats (e.g. `aba`), instead of the format's own. `""` or `false` means none. Not for xlsx.
258    #[serde(default)]
259    #[schemars(schema_with = "extension")]
260    pub extension: Maybe<Loose<Option<OneOf<String, bool>>>>,
261    /// The format's own options.
262    #[serde(rename = "$unknown", default)]
263    #[schemars(skip)]
264    pub options: Map<serde_json::Value>,
265}
266
267/// Where a file is delivered: the name of a destination profile in `profiles.yml`, an optional `path`, and the options of that destination's plugin (e.g. `to`, `subject` and `body` for email). The built-in profile `local` copies the file to a local path.
268#[derive(Deserialize, JsonSchema)]
269#[schemars(rename = "destination", extend("additionalProperties" = true))]
270pub struct Destination {
271    /// The destination profile in `profiles.yml` (under `destinations:`) to deliver with. `local` is built in. It uses its entry for the run (`--target`, `DRE_TARGET`, else the profile's own `target:`, else `dev`); a missing entry is an error, and an entry `{deliver: false}` delivers nowhere. May use Jinja with `var()`, `env_var()`, `run.*` and `target.name`.
272    #[schemars(required)]
273    pub profile: Option<Loose<String>>,
274    /// Where to put the file: a path, or a URL such as `s3://bucket/key`, depending on the destination. Rendered with Jinja, so it can use `var()`, `run.*`, macros and `destination.*` (this destination's settings).
275    pub path: Option<Loose<String>>,
276    /// On a message output's entry, for a destination that takes messages and files (`slack`, `email`): other outputs of the report whose files go with the message.
277    #[serde(default)]
278    #[schemars(schema_with = "attach")]
279    pub attach: Option<Loose<OneOf<String, Vec<String>>>>,
280    /// The destination plugin's options.
281    #[serde(rename = "$unknown", default)]
282    #[schemars(skip)]
283    pub options: Map<serde_json::Value>,
284}
285
286/// Fills a branded Excel workbook instead of creating a new one (xlsx only).
287#[derive(Deserialize, JsonSchema)]
288#[schemars(rename = "template", deny_unknown_fields)]
289pub struct Template {
290    /// Path of the `.xlsx` template, relative to the project.
291    #[schemars(required)]
292    pub file: Option<Loose<String>>,
293    /// Where each query's data goes in the template. Default: none, so the template is copied as it is.
294    pub bindings: Option<Loose<Vec<Loose<TemplateBinding>>>>,
295}
296
297/// One block of data in an xlsx template: a table of a query's result, or a single cell.
298#[derive(Deserialize, JsonSchema)]
299#[schemars(deny_unknown_fields, inline)]
300pub struct TemplateBinding {
301    /// The template sheet to write into.
302    #[schemars(required)]
303    pub sheet: Option<Loose<String>>,
304    /// The query whose result goes here. Must be one of the Binding's queries.
305    pub query: Option<Loose<String>>,
306    /// Which result set of the query to use, counting from 1. Default: the last.
307    #[schemars(range(min = 1))]
308    pub result_index: Option<Loose<u64>>,
309    /// The top-left cell of a table block. A table block needs a `query`.
310    #[schemars(regex(pattern = "^[A-Za-z]{1,3}[0-9]+$"))]
311    pub anchor: Option<Loose<String>>,
312    /// Whether to write the column names above the data in a table block.
313    pub header: Option<Loose<bool>>,
314    /// The columns of the query to write in a table block, in order. Default: all.
315    pub columns: Option<Loose<Vec<String>>>,
316    /// Makes this a single-cell binding: the cell to write. Needs exactly one of `value`, or `query` with `column`.
317    #[schemars(regex(pattern = "^[A-Za-z]{1,3}[0-9]+$"))]
318    pub cell: Option<Loose<String>>,
319    /// A fixed value (rendered with Jinja) for a single-cell binding.
320    pub value: Option<Loose<String>>,
321    /// The column of the query's first row to write into a single-cell binding.
322    pub column: Option<Loose<String>>,
323    #[serde(rename = "$unknown", default)]
324    #[schemars(skip)]
325    pub unknown: UnknownKeys,
326}
327
328fn string_or_bool(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
329    schemars::json_schema!({"type": ["string", "boolean"]})
330}
331
332fn extension(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
333    // `null` is a value here (no extension), not schemars' "optional".
334    schemars::json_schema!({"type": ["string", "boolean", "null"], "x-dre-null": true})
335}
336
337fn destination_or_list(g: &mut schemars::SchemaGenerator) -> schemars::Schema {
338    let destination = g.subschema_for::<Destination>();
339    schemars::json_schema!({
340        "oneOf": [destination, {"type": "array", "minItems": 1, "items": destination}]
341    })
342}
343
344fn attach(_: &mut schemars::SchemaGenerator) -> schemars::Schema {
345    schemars::json_schema!({
346        "oneOf": [
347            {"type": "string"},
348            {"type": "array", "items": {"type": "string"}, "minItems": 1}
349        ]
350    })
351}
352
353fn queries(g: &mut schemars::SchemaGenerator) -> schemars::Schema {
354    let entry = g.subschema_for::<QueryEntry>();
355    schemars::json_schema!({
356        "type": "array",
357        "items": {
358            "oneOf": [
359                {"type": "string", "description": "The name of a `.sql` file under `reports/`, without extension."},
360                entry
361            ]
362        }
363    })
364}
dre_core/config/report.rs

dre_core/config/
report.rs
