westonpace commented on a change in pull request #10629:
URL: https://github.com/apache/arrow/pull/10629#discussion_r661589118
##########
File path: format/Schema.fbs
##########
@@ -218,8 +218,34 @@ table Time {
/// leap seconds, as a 64-bit integer. Note that UNIX time does not include
/// leap seconds.
///
-/// The Timestamp metadata supports both "time zone naive" and "time zone
-/// aware" timestamps. Read about the timezone attribute for more detail
+/// Date & time libraries often have multiple different data types for temporal
+/// data. In order to ease interoperability between different implementations
the
+/// Arrow project has some recommendations for encoding these types into a
Timestamp
+/// column.
+///
+/// An "Instant" represents a single moment in time that has no meaningful
time zone
+/// or the time zone is unknown. A column of Instants can also contain values
from
+/// multiple time zones. To encode an instant set the timezone string to
"UTC".
+///
+/// A "ZonedDateTime" represents a single moment in time that has a meaningful
+/// reference time zone. To encode a ZonedDateTime as a Timestamp set the
timezone
+/// string to the name of the timezone.
+///
+/// An "OffsetDateTime" represents a single moment in time combined with a
meaningful
+/// offset from UTC. To encode an OffsetDateTime as a Timestamp set the
timezone string
+/// to the numeric time zone offset string (e.g. "+03:00").
+///
+/// A "LocalDateTime" does not represent a single moment in time. It
represents a wall
+/// clock time combined with a date. Because of daylight savings time there
may multiple
+/// Instants that correspond to a single LocalDateTime in any given time zone.
A
+/// LocalDateTime is often stored as a struct or a Date32/Time64 pair.
However, it can
Review comment:
I'm not sure I agree. I think an application is free to store a
LocalDateTime in whatever form suits them. For example, if the application is
planning on doing mostly field extraction & local time display it may make
sense to store in a larger struct form to save time on division.
I don't think the statement "If you have a LocalDateTime you can expect it
to be encoded as a Timestamp column" is true.
I do think the statement "If you have a Timestamp column with no time zone
you can expect it to be a LocalDateTime" is true.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
