/Users/andrewlamb/Software/datafusion/datafusion/common/src/unnest.rs
Line | Count | Source (jump to first uncovered line) |
1 | | // Licensed to the Apache Software Foundation (ASF) under one |
2 | | // or more contributor license agreements. See the NOTICE file |
3 | | // distributed with this work for additional information |
4 | | // regarding copyright ownership. The ASF licenses this file |
5 | | // to you under the Apache License, Version 2.0 (the |
6 | | // "License"); you may not use this file except in compliance |
7 | | // with the License. You may obtain a copy of the License at |
8 | | // |
9 | | // http://www.apache.org/licenses/LICENSE-2.0 |
10 | | // |
11 | | // Unless required by applicable law or agreed to in writing, |
12 | | // software distributed under the License is distributed on an |
13 | | // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
14 | | // KIND, either express or implied. See the License for the |
15 | | // specific language governing permissions and limitations |
16 | | // under the License. |
17 | | |
18 | | //! [`UnnestOptions`] for unnesting structured types |
19 | | |
20 | | /// Options for unnesting a column that contains a list type, |
21 | | /// replicating values in the other, non nested rows. |
22 | | /// |
23 | | /// Conceptually this operation is like joining each row with all the |
24 | | /// values in the list column. |
25 | | /// |
26 | | /// If `preserve_nulls` is false, nulls and empty lists |
27 | | /// from the input column are not carried through to the output. This |
28 | | /// is the default behavior for other systems such as ClickHouse and |
29 | | /// DuckDB |
30 | | /// |
31 | | /// If `preserve_nulls` is true (the default), nulls from the input |
32 | | /// column are carried through to the output. |
33 | | /// |
34 | | /// # Examples |
35 | | /// |
36 | | /// ## `Unnest(c1)`, preserve_nulls: false |
37 | | /// ```text |
38 | | /// ┌─────────┐ ┌─────┐ ┌─────────┐ ┌─────┐ |
39 | | /// │ {1, 2} │ │ A │ Unnest │ 1 │ │ A │ |
40 | | /// ├─────────┤ ├─────┤ ├─────────┤ ├─────┤ |
41 | | /// │ null │ │ B │ │ 2 │ │ A │ |
42 | | /// ├─────────┤ ├─────┤ ────────────▶ ├─────────┤ ├─────┤ |
43 | | /// │ {} │ │ D │ │ 3 │ │ E │ |
44 | | /// ├─────────┤ ├─────┤ └─────────┘ └─────┘ |
45 | | /// │ {3} │ │ E │ c1 c2 |
46 | | /// └─────────┘ └─────┘ |
47 | | /// c1 c2 |
48 | | /// ``` |
49 | | /// |
50 | | /// ## `Unnest(c1)`, preserve_nulls: true |
51 | | /// ```text |
52 | | /// ┌─────────┐ ┌─────┐ ┌─────────┐ ┌─────┐ |
53 | | /// │ {1, 2} │ │ A │ Unnest │ 1 │ │ A │ |
54 | | /// ├─────────┤ ├─────┤ ├─────────┤ ├─────┤ |
55 | | /// │ null │ │ B │ │ 2 │ │ A │ |
56 | | /// ├─────────┤ ├─────┤ ────────────▶ ├─────────┤ ├─────┤ |
57 | | /// │ {} │ │ D │ │ null │ │ B │ |
58 | | /// ├─────────┤ ├─────┤ ├─────────┤ ├─────┤ |
59 | | /// │ {3} │ │ E │ │ 3 │ │ E │ |
60 | | /// └─────────┘ └─────┘ └─────────┘ └─────┘ |
61 | | /// c1 c2 c1 c2 |
62 | | /// ``` |
63 | | #[derive(Debug, Clone, PartialEq, PartialOrd, Hash, Eq)] |
64 | | pub struct UnnestOptions { |
65 | | /// Should nulls in the input be preserved? Defaults to true |
66 | | pub preserve_nulls: bool, |
67 | | } |
68 | | |
69 | | impl Default for UnnestOptions { |
70 | 0 | fn default() -> Self { |
71 | 0 | Self { |
72 | 0 | // default to true to maintain backwards compatible behavior |
73 | 0 | preserve_nulls: true, |
74 | 0 | } |
75 | 0 | } |
76 | | } |
77 | | |
78 | | impl UnnestOptions { |
79 | | /// Create a new [`UnnestOptions`] with default values |
80 | 0 | pub fn new() -> Self { |
81 | 0 | Default::default() |
82 | 0 | } |
83 | | |
84 | | /// Set the behavior with nulls in the input as described on |
85 | | /// [`Self`] |
86 | 0 | pub fn with_preserve_nulls(mut self, preserve_nulls: bool) -> Self { |
87 | 0 | self.preserve_nulls = preserve_nulls; |
88 | 0 | self |
89 | 0 | } |
90 | | } |