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;