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

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

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



##########
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".

Review comment:
       we might want to clarify that this encoding loses details that the value was in fact an instant.




-- 
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