Skip to main content

vortex_array/arrays/datetime/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Typed wrappers for temporal extension arrays.
5//!
6//! [`TemporalData`] gives date, time, and timestamp arrays a shared storage interface. The extension
7//! dtype retains each type's unit and metadata while the underlying array stores numeric values.
8
9use std::sync::Arc;
10
11use vortex_error::VortexError;
12use vortex_error::vortex_bail;
13use vortex_error::vortex_err;
14
15use crate::ArrayRef;
16use crate::IntoArray;
17use crate::arrays::Extension;
18use crate::arrays::ExtensionArray;
19use crate::arrays::extension::ExtensionArrayExt;
20use crate::dtype::DType;
21use crate::dtype::extension::ExtDTypeRef;
22use crate::extension::datetime::AnyTemporal;
23use crate::extension::datetime::Date;
24use crate::extension::datetime::TemporalMetadata;
25use crate::extension::datetime::Time;
26use crate::extension::datetime::TimeUnit;
27use crate::extension::datetime::Timestamp;
28
29/// An array wrapper for primitive values that have an associated temporal meaning.
30///
31/// This is a wrapper around ExtensionArrays containing numeric types, each of which corresponds to
32/// either a timestamp or julian date (both referenced to UNIX epoch), OR a time since midnight.
33///
34/// ## Arrow compatibility
35///
36/// TemporalData can be created from Arrow arrays containing the following datatypes:
37/// * `Time32`
38/// * `Time64`
39/// * `Timestamp`
40/// * `Date32`
41/// * `Date64`
42///
43/// Anything that can be constructed and held in a `TemporalData` can also be zero-copy converted
44/// back to the relevant Arrow datatype.
45#[derive(Clone, Debug)]
46pub struct TemporalData {
47    /// The underlying Vortex extension array holding all the numeric values.
48    ext: ExtensionArray,
49}
50
51/// Type alias for backward compatibility.
52pub type TemporalArray = TemporalData;
53
54impl TemporalData {
55    /// Create a new `TemporalData` holding either i32 day offsets, or i64 millisecond offsets
56    /// that are evenly divisible by the number of 86,400,000.
57    ///
58    /// This is equivalent to the data described by either of the `Date32` or `Date64` data types
59    /// from Arrow.
60    ///
61    /// # Panics
62    ///
63    /// If the time unit is milliseconds, and the array is not of primitive I64 type, it panics.
64    ///
65    /// If the time unit is days, and the array is not of primitive I32 type, it panics.
66    ///
67    /// If any other time unit is provided, it panics.
68    pub fn new_date(array: ArrayRef, time_unit: TimeUnit) -> Self {
69        Self {
70            ext: ExtensionArray::new(
71                Date::new(time_unit, array.dtype().nullability()).erased(),
72                array,
73            ),
74        }
75    }
76
77    /// Create a new `TemporalData` holding one of the following values:
78    ///
79    /// * `i32` values representing seconds since midnight
80    /// * `i32` values representing milliseconds since midnight
81    /// * `i64` values representing microseconds since midnight
82    /// * `i64` values representing nanoseconds since midnight
83    ///
84    /// Note, this is equivalent to the set of values represented by the Time32 or Time64 types
85    /// from Arrow.
86    ///
87    /// # Panics
88    ///
89    /// If the time unit is seconds, and the array is not of primitive I32 type, it panics.
90    ///
91    /// If the time unit is milliseconds, and the array is not of primitive I32 type, it panics.
92    ///
93    /// If the time unit is microseconds, and the array is not of primitive I64 type, it panics.
94    ///
95    /// If the time unit is nanoseconds, and the array is not of primitive I64 type, it panics.
96    pub fn new_time(array: ArrayRef, time_unit: TimeUnit) -> Self {
97        Self {
98            ext: ExtensionArray::new(
99                Time::new(time_unit, array.dtype().nullability()).erased(),
100                array,
101            ),
102        }
103    }
104
105    /// Creates a timestamp array with the given unit and optional time zone.
106    ///
107    /// # Panics
108    ///
109    /// Panics if `array` does not have primitive i64 storage, or if
110    /// [`Timestamp::try_new_with_tz`] rejects the unit or time zone.
111    pub fn new_timestamp(
112        array: ArrayRef,
113        time_unit: TimeUnit,
114        time_zone: Option<Arc<str>>,
115    ) -> Self {
116        Self {
117            ext: ExtensionArray::new(
118                Timestamp::new_with_tz(time_unit, time_zone, array.dtype().nullability()).erased(),
119                array,
120            ),
121        }
122    }
123}
124
125impl TemporalData {
126    /// Access the underlying temporal values in the underlying ExtensionArray storage.
127    ///
128    /// These values are to be interpreted based on the time unit and optional time-zone stored
129    /// in the TemporalMetadata.
130    pub fn temporal_values(&self) -> &ArrayRef {
131        self.ext.storage_array()
132    }
133
134    /// Retrieve the temporal metadata.
135    ///
136    /// The metadata is used to provide semantic meaning to the temporal values Array, for example
137    /// to understand the granularity of the samples and if they have an associated timezone.
138    pub fn temporal_metadata(&self) -> TemporalMetadata<'_> {
139        self.ext.dtype().as_extension().metadata::<AnyTemporal>()
140    }
141
142    /// Retrieve the extension DType associated with the underlying array.
143    pub fn ext_dtype(&self) -> ExtDTypeRef {
144        self.ext.ext_dtype().clone()
145    }
146
147    /// Retrieve the DType of the array. This will be a `DType::Extension` variant.
148    pub fn dtype(&self) -> &DType {
149        self.ext.dtype()
150    }
151}
152
153impl From<TemporalData> for ArrayRef {
154    fn from(value: TemporalData) -> Self {
155        value.ext.into_array()
156    }
157}
158
159impl IntoArray for TemporalData {
160    fn into_array(self) -> ArrayRef {
161        self.into()
162    }
163}
164
165impl TryFrom<ArrayRef> for TemporalData {
166    type Error = VortexError;
167
168    /// Try to specialize a generic Vortex array as a TemporalData.
169    ///
170    /// # Errors
171    ///
172    /// If the provided Array does not have `vortex.ext` encoding, an error will be returned.
173    ///
174    /// If the provided Array does not have recognized ExtMetadata corresponding to one of the known
175    /// `TemporalMetadata` variants, an error is returned.
176    fn try_from(value: ArrayRef) -> Result<Self, Self::Error> {
177        let ext = value
178            .as_opt::<Extension>()
179            .ok_or_else(|| vortex_err!("array must be an ExtensionArray"))?;
180        if !ext.ext_dtype().is::<AnyTemporal>() {
181            vortex_bail!(
182                "array extension dtype {} is not a temporal type",
183                ext.ext_dtype()
184            );
185        }
186        Ok(Self {
187            ext: ext.into_owned(),
188        })
189    }
190}
191
192// Conversions to/from ExtensionArray
193impl From<&TemporalData> for ExtensionArray {
194    fn from(value: &TemporalData) -> Self {
195        value.ext.clone()
196    }
197}
198
199impl From<TemporalData> for ExtensionArray {
200    fn from(value: TemporalData) -> Self {
201        value.ext
202    }
203}
204
205impl TryFrom<ExtensionArray> for TemporalData {
206    type Error = VortexError;
207
208    fn try_from(ext: ExtensionArray) -> Result<Self, Self::Error> {
209        if !ext.ext_dtype().is::<AnyTemporal>() {
210            vortex_bail!(
211                "array extension dtype {} is not a temporal type",
212                ext.ext_dtype()
213            );
214        }
215        Ok(Self { ext })
216    }
217}
218
219#[cfg(test)]
220mod tests;