[GitHub] [arrow] lidavidm commented on a change in pull request #10629: ARROW-13218: [Doc] Document/clarify conventions for timestamp storage

[GitBox <gi...@apache.org>]

lidavidm commented on a change in pull request #10629:
URL: https://github.com/apache/arrow/pull/10629#discussion_r661505356



##########
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:
       Just to double check, the "is often stored as…" is commenting about systems outside of Arrow, right? It might be useful to clarify that the "it can be also be encoded…" as noting that Arrow's canonical encoding for LocalDateTime is this encoding, maybe something like "Arrow represents LocalDateTime as a Timestamp as follows…"




-- 
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: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org