Skip to content

Apache DataFusion SQL Query Engine

feat: support DATETIME as an alias of TIMESTAMP (#26975)

hozan23aeba33ff9bcd
diff --git a/datafusion/sql/src/planner.rs b/datafusion/sql/src/planner.rs
index b51d1ab777..5f7d01b9f4 100644
--- a/datafusion/sql/src/planner.rs
+++ b/datafusion/sql/src/planner.rs
@@ -797,6 +797,14 @@ impl<'a, S: ContextProvider> SqlToRel<'a, S> {
};
Ok(DataType::Timestamp(precision, tz.map(Into::into)))
}
+ SQLDataType::Datetime(precision)
+ if precision.is_none() || [0, 3, 6, 9].contains(&precision.unwrap()) =>
+ {
+ self.convert_simple_data_type(&SQLDataType::Timestamp(
+ *precision,
+ TimezoneInfo::None,
+ ))
+ }
SQLDataType::Date => Ok(DataType::Date32),
SQLDataType::Time(None, tz_info) => {
if *tz_info == TimezoneInfo::None
diff --git a/datafusion/sql/tests/common/mod.rs b/datafusion/sql/tests/common/mod.rs
index c1707fdcd6..1046ae9d8e 100644
--- a/datafusion/sql/tests/common/mod.rs
+++ b/datafusion/sql/tests/common/mod.rs
@@ -395,8 +395,10 @@ impl TypePlanner for CustomTypePlanner {
None | Some(9) => TimeUnit::Nanosecond,
_ => unreachable!(),
};
+ // Differs from the default mapping (no time zone)
Ok(Some(
- DataType::Timestamp(precision, None).into_nullable_field_ref(),
+ DataType::Timestamp(precision, Some("UTC".into()))
+ .into_nullable_field_ref(),
))
}
_ => Ok(None),
diff --git a/datafusion/sql/tests/sql_integration.rs b/datafusion/sql/tests/sql_integration.rs
index 2a73687c01..d89984da3c 100644
--- a/datafusion/sql/tests/sql_integration.rs
+++ b/datafusion/sql/tests/sql_integration.rs
@@ -5673,10 +5673,13 @@ fn test_custom_type_plan() -> Result<()> {
let planner = SqlToRel::new_with_options(&context, options);
let result = DFParser::parse_sql_with_dialect(sql, dialect);
let mut ast = result.unwrap();
- let err = planner.statement_to_plan(ast.pop_front().unwrap());
- assert_contains!(
- err.unwrap_err().to_string(),
- "This feature is not implemented: Unsupported SQL type DATETIME"
+ let plan = planner.statement_to_plan(ast.pop_front().unwrap())?;
+ assert_snapshot!(
+ plan,
+ @r#"
+ Projection: CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns))
+ EmptyRelation: rows=1
+ "#
);
fn plan_sql(sql: &str) -> LogicalPlan {
@@ -5698,7 +5701,7 @@ fn test_custom_type_plan() -> Result<()> {
assert_snapshot!(
plan,
@r#"
- Projection: CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns))
+ Projection: CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns, "UTC"))
EmptyRelation: rows=1
"#
);
@@ -5708,7 +5711,7 @@ fn test_custom_type_plan() -> Result<()> {
assert_snapshot!(
plan,
@r#"
- Projection: CAST(CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns)) AS Timestamp(ns))
+ Projection: CAST(CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns)) AS Timestamp(ns, "UTC"))
EmptyRelation: rows=1
"#
);
@@ -5720,7 +5723,7 @@ fn test_custom_type_plan() -> Result<()> {
assert_snapshot!(
plan,
@r#"
- Projection: make_array(CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns)), CAST(Utf8("2001-01-02 18:00:00") AS Timestamp(ns)))
+ Projection: make_array(CAST(Utf8("2001-01-01 18:00:00") AS Timestamp(ns, "UTC")), CAST(Utf8("2001-01-02 18:00:00") AS Timestamp(ns, "UTC")))
EmptyRelation: rows=1
"#
);
diff --git a/datafusion/sqllogictest/test_files/datetime/timestamps.slt b/datafusion/sqllogictest/test_files/datetime/timestamps.slt
index ba2def1c05..03be67d214 100644
--- a/datafusion/sqllogictest/test_files/datetime/timestamps.slt
+++ b/datafusion/sqllogictest/test_files/datetime/timestamps.slt
@@ -7171,3 +7171,66 @@ RESET datafusion.explain.physical_plan_only;
statement ok
SET datafusion.execution.target_partitions = 4;
+
+##########
+## DATETIME is an alias of TIMESTAMP without time zone
+##########
+
+query PT
+SELECT CAST('2026-09-21 08:55:40.123456789' AS DATETIME), arrow_typeof(CAST('2026-09-21 08:55:40' AS DATETIME))
+----
+2026-09-21T08:55:40.123456789 Timestamp(ns)
+
+query PT
+SELECT CAST('2026-09-21 08:55:40.123456789' AS DATETIME(0)), arrow_typeof(CAST('2026-09-21 08:55:40' AS DATETIME(0)))
+----
+2026-09-21T08:55:40 Timestamp(s)
+
+query PT
+SELECT CAST('2026-09-21 08:55:40.123456789' AS DATETIME(3)), arrow_typeof(CAST('2026-09-21 08:55:40' AS DATETIME(3)))
+----
+2026-09-21T08:55:40.123 Timestamp(ms)
+
+query PT
+SELECT CAST('2026-09-21 08:55:40.123456789' AS DATETIME(6)), arrow_typeof(CAST('2026-09-21 08:55:40' AS DATETIME(6)))
+----
+2026-09-21T08:55:40.123456 Timestamp(µs)
+
+query PT
+SELECT CAST('2026-09-21 08:55:40.123456789' AS DATETIME(9)), arrow_typeof(CAST('2026-09-21 08:55:40' AS DATETIME(9)))
+----
+2026-09-21T08:55:40.123456789 Timestamp(ns)
+
+query PT
+SELECT DATETIME '2026-09-21 08:55:40', arrow_typeof(DATETIME '2026-09-21 08:55:40')
+----
+2026-09-21T08:55:40 Timestamp(ns)
+
+statement ok
+CREATE TABLE datetime_t (dt DATETIME(3)) AS VALUES ('2026-09-21 08:55:40.123');
+
+query PT
+SELECT dt, arrow_typeof(dt) FROM datetime_t
+----
+2026-09-21T08:55:40.123 Timestamp(ms)
+
+statement ok
+DROP TABLE datetime_t;
+
+# The session time zone only applies to TIMESTAMP WITH TIME ZONE
+statement ok
+SET datafusion.execution.time_zone = '+05:00';
+
+query T
+SELECT arrow_typeof(CAST('2026-09-21 08:55:40' AS DATETIME))
+----
+Timestamp(ns)
+
+statement ok
+RESET datafusion.execution.time_zone;
+
+statement error Unsupported SQL type DATETIME\(5\)
+SELECT CAST('2026-09-21 08:55:40' AS DATETIME(5));
+
+statement error Unsupported SQL type DATETIME\(1\)
+SELECT CAST('2026-09-21 08:55:40' AS DATETIME(1));
diff --git a/docs/source/library-user-guide/extending-sql.md b/docs/source/library-user-guide/extending-sql.md
index 26bdb52fba..34c7e02092 100644
--- a/docs/source/library-user-guide/extending-sql.md
+++ b/docs/source/library-user-guide/extending-sql.md
@@ -158,7 +158,7 @@ struct MyTypePlanner;
impl TypePlanner for MyTypePlanner {
fn plan_type_field(&self, sql_type: &ast::DataType) -> Result<Option<FieldRef>> {
match sql_type {
- // Map DATETIME(precision) to Arrow Timestamp
+ // Map DATETIME(precision) to Arrow Timestamp (this is also the default behavior)
ast::DataType::Datetime(precision) => {
let time_unit = match precision {
Some(0) => TimeUnit::Second,
diff --git a/docs/source/user-guide/sql/data_types.md b/docs/source/user-guide/sql/data_types.md
index 761d903943..9f232e7ed3 100644
--- a/docs/source/user-guide/sql/data_types.md
+++ b/docs/source/user-guide/sql/data_types.md
@@ -97,6 +97,7 @@ The maximum supported precision for `DECIMAL` types is 76.
| `DATE` | `Date32` |
| `TIME` | `Time64(Nanosecond)` |
| `TIMESTAMP`, `TIMESTAMP(p)`, `TIMESTAMP(p) WITHOUT TIME ZONE` | `Timestamp(unit, None)` |
+| `DATETIME`, `DATETIME(p)` | `Timestamp(unit, None)` |
| `TIMESTAMPTZ(p)`, `TIMESTAMP(p) WITH TIME ZONE` | `Timestamp(unit, None)` by default — see the warning below |
| `INTERVAL` | `Interval(MonthDayNano)` |
@@ -119,7 +120,8 @@ Set `datafusion.execution.time_zone` to make these types aware. `'UTC'` is a
good value.
:::
-`unit` comes from the optional precision `p` on the two `TIMESTAMP` rows. Use
+`unit` comes from the optional precision `p` on the `TIMESTAMP` and `DATETIME`
+rows. Use
`0`, `3`, `6` or `9` for `Second`, `Millisecond`, `Microsecond` or `Nanosecond`.
DataFusion rejects each other value of `p`. If you omit `p`, the unit is
`Nanosecond`. The precision goes after `TIMESTAMPTZ`, but before
@@ -173,4 +175,3 @@ set to `c0`, `c1`, ..., `cn`.
| `CUSTOM` | _Not yet supported_ |
| `ENUM` | _Not yet supported_ |
| `SET` | _Not yet supported_ |
-| `DATETIME` | _Not yet supported_ |