Skip to main content

deltalake_core/
errors.rs

1//! Exceptions for the deltalake crate
2use chrono::{DateTime, Utc};
3use object_store::Error as ObjectStoreError;
4
5use crate::kernel::Version;
6use crate::kernel::transaction::{CommitBuilderError, TransactionError};
7
8/// A result returned by delta-rs
9pub type DeltaResult<T, E = DeltaTableError> = Result<T, E>;
10
11/// Whether an unsupported column-mapping access was a read or a write.
12#[derive(Debug, Clone, Copy, PartialEq, Eq)]
13pub enum ColumnMappingOperation {
14    /// A read-path operation.
15    Read,
16    /// A write-path operation.
17    Write,
18}
19
20impl std::fmt::Display for ColumnMappingOperation {
21    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
22        match self {
23            ColumnMappingOperation::Read => f.write_str("read"),
24            ColumnMappingOperation::Write => f.write_str("write"),
25        }
26    }
27}
28
29/// Delta Table specific error
30#[allow(missing_docs)]
31#[derive(thiserror::Error, Debug)]
32pub enum DeltaTableError {
33    #[error("Kernel error: {0}")]
34    KernelError(#[from] delta_kernel::error::Error),
35
36    /// Error returned when reading the delta log object failed.
37    #[error("Failed to read delta log object: {}", .source)]
38    ObjectStore {
39        /// Storage error details when reading the delta log object failed.
40        #[from]
41        source: ObjectStoreError,
42    },
43
44    /// Error returned when parsing checkpoint parquet.
45    #[error("Failed to parse parquet: {}", .source)]
46    Parquet {
47        /// Parquet error details returned when reading the checkpoint failed.
48        #[from]
49        source: parquet::errors::ParquetError,
50    },
51
52    /// Error returned when converting the schema in Arrow format failed.
53    #[error("Failed to convert into Arrow schema: {}", .source)]
54    Arrow {
55        /// Arrow error details returned when converting the schema in Arrow format failed
56        #[from]
57        source: arrow::error::ArrowError,
58    },
59
60    /// Error returned when the log record has an invalid JSON.
61    #[error("Invalid JSON in log record, version={}, line=`{}`, err=`{}`", .version, .line, .json_err)]
62    InvalidJsonLog {
63        /// JSON error details returned when parsing the record JSON.
64        json_err: serde_json::error::Error,
65        /// invalid log entry content.
66        line: String,
67        /// corresponding table version for the log file.
68        version: Version,
69    },
70
71    /// Error returned when the log contains invalid stats JSON.
72    #[error("Invalid JSON in file stats: {}", .json_err)]
73    InvalidStatsJson {
74        /// JSON error details returned when parsing the stats JSON.
75        json_err: serde_json::error::Error,
76    },
77
78    /// Error returned when the DeltaTable has an invalid version.
79    #[error("Invalid table version: {0}")]
80    InvalidVersion(Version),
81
82    /// Error returned when an operation requests an older version than the currently loaded one.
83    #[error(
84        "Cannot downgrade from version {current_version} to {requested_version}; use DeltaTable.load_version()"
85    )]
86    VersionDowngrade {
87        /// The currently loaded version.
88        current_version: Version,
89        /// The requested older version.
90        requested_version: Version,
91    },
92
93    /// Error returned when the datetime string is invalid for a conversion.
94    #[error("Invalid datetime string: {}", .source)]
95    InvalidDateTimeString {
96        /// Parse error details returned of the datetime string parse error.
97        #[from]
98        source: chrono::ParseError,
99    },
100
101    /// Error returned when attempting to write bad data to the table
102    #[error("{message}")]
103    InvalidData {
104        /// Action error details returned of the invalid action.
105        message: String,
106    },
107
108    /// Error returned when it is not a DeltaTable.
109    #[error("Not a Delta table: {0}")]
110    NotATable(String),
111
112    /// Error returned when no schema was found in the DeltaTable.
113    #[error("No schema found, please make sure table is loaded.")]
114    NoSchema,
115
116    /// Error returned when writes are attempted with data that doesn't match the schema of the
117    /// table
118    #[error("Data does not match the schema or partitions of the table: {}", msg)]
119    SchemaMismatch {
120        /// Information about the mismatch
121        msg: String,
122    },
123
124    /// Error returned when a partition is not formatted as a Hive Partition.
125    #[error("This partition is not formatted with key=value: {}", .partition)]
126    PartitionError {
127        /// The malformed partition used.
128        partition: String,
129    },
130
131    /// Error returned when a invalid partition filter was found.
132    #[error("Invalid partition filter found: {}.", .partition_filter)]
133    InvalidPartitionFilter {
134        /// The invalid partition filter used.
135        partition_filter: String,
136    },
137
138    /// Error returned when a line from log record is invalid.
139    #[error("Failed to read line from log record")]
140    Io {
141        /// Source error details returned while reading the log record.
142        #[from]
143        source: std::io::Error,
144    },
145
146    /// Error raised while preparing a commit
147    #[error("Commit actions are unsound: {source}")]
148    CommitValidation {
149        /// The source error
150        source: CommitBuilderError,
151    },
152
153    /// Error raised while commititng transaction
154    #[error("Transaction failed: {source}")]
155    Transaction {
156        /// The source error
157        source: TransactionError,
158    },
159
160    /// Error returned when transaction is failed to be committed because given version already exists.
161    #[error("Delta transaction failed, version {0} already exists.")]
162    VersionAlreadyExists(Version),
163
164    /// Error returned when user attempts to commit actions that don't belong to the next version.
165    #[error("Delta transaction failed, version {0} does not follow {1}")]
166    VersionMismatch(Version, Version),
167
168    /// A Feature is missing to perform operation
169    #[error("Delta-rs must be build with feature '{feature}' to support loading from: {url}.")]
170    MissingFeature {
171        /// Name of the missing feature
172        feature: &'static str,
173        /// Storage location url
174        url: String,
175    },
176
177    /// A Feature is missing to perform operation
178    #[error("Cannot infer storage location from: {0}")]
179    InvalidTableLocation(String),
180
181    /// Generic Delta Table error
182    #[error("Log JSON serialization error: {json_err}")]
183    SerializeLogJson {
184        /// JSON serialization error
185        json_err: serde_json::error::Error,
186    },
187
188    /// Generic Delta Table error
189    #[error("Generic DeltaTable error: {0}")]
190    Generic(String),
191
192    /// Generic Delta Table error
193    #[error("Generic error: {source}")]
194    GenericError {
195        /// Source error
196        source: Box<dyn std::error::Error + Send + Sync + 'static>,
197    },
198
199    #[error("Kernel: {source}")]
200    Kernel {
201        #[from]
202        source: crate::kernel::Error,
203    },
204
205    #[error("Table metadata is invalid: {0}")]
206    MetadataError(String),
207
208    #[error("Table has not yet been initialized")]
209    NotInitialized,
210
211    #[error("Table has not yet been initialized with files, therefore {0} is not supported")]
212    NotInitializedWithFiles(String),
213
214    #[error("Change Data not enabled for version: {version}, Start: {start}, End: {end}")]
215    ChangeDataNotRecorded {
216        version: Version,
217        start: Version,
218        end: Version,
219    },
220
221    #[error("Reading a table version: {version} that does not have change data enabled")]
222    ChangeDataNotEnabled { version: Version },
223
224    #[error("Invalid version. Start version {start} is greater than end version {end}")]
225    ChangeDataInvalidVersionRange { start: Version, end: Version },
226
227    #[error("End timestamp {ending_timestamp} is greater than latest commit timestamp")]
228    ChangeDataTimestampGreaterThanCommit { ending_timestamp: DateTime<Utc> },
229
230    #[error("No starting version or timestamp provided for CDC")]
231    NoStartingVersionOrTimestamp,
232
233    /// Error returned when an operation is attempted on a column-mapped table that does not
234    /// yet support column mapping.
235    #[error("Column mapping is not supported for {mode} operation '{operation}' yet")]
236    UnsupportedColumnMapping {
237        /// Whether the unsupported access was a read or a write.
238        mode: ColumnMappingOperation,
239        /// Human-readable description of the operation (e.g. "ADD COLUMN").
240        operation: String,
241    },
242}
243
244impl From<object_store::path::Error> for DeltaTableError {
245    fn from(err: object_store::path::Error) -> Self {
246        Self::GenericError {
247            source: Box::new(err),
248        }
249    }
250}
251
252impl From<serde_json::Error> for DeltaTableError {
253    fn from(value: serde_json::Error) -> Self {
254        DeltaTableError::InvalidStatsJson { json_err: value }
255    }
256}
257
258impl DeltaTableError {
259    /// Crate a NotATable Error with message for given path.
260    pub fn not_a_table(path: impl AsRef<str>) -> Self {
261        let msg = format!(
262            "No snapshot or version 0 found, perhaps {} is an empty dir?",
263            path.as_ref()
264        );
265        Self::NotATable(msg)
266    }
267
268    /// Create a [Generic](DeltaTableError::Generic) error with the given message.
269    pub fn generic(msg: impl ToString) -> Self {
270        Self::Generic(msg.to_string())
271    }
272
273    /// Construct an [`UnsupportedColumnMapping`](DeltaTableError::UnsupportedColumnMapping) error.
274    pub fn unsupported_column_mapping(
275        mode: ColumnMappingOperation,
276        operation: impl ToString,
277    ) -> Self {
278        Self::UnsupportedColumnMapping {
279            mode,
280            operation: operation.to_string(),
281        }
282    }
283}