alamb commented on a change in pull request #10177:
URL: https://github.com/apache/arrow/pull/10177#discussion_r688913459
##########
File path: java/format/src/main/java/org/apache/arrow/flatbuf/Timestamp.java
##########
@@ -29,8 +29,33 @@
* 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 "zoned date-time" represents a single moment in time that has a meaningful
+ * reference time zone. To encode a zoned date-time as a Timestamp set the
timezone
+ * string to the name of the timezone. There is some ambiguity between an
instant
+ * and a zoned date-time with the UTC time zone. Both of these are stored the
same.
+ * Typically, this distinction does not matter. If it does, then an
application should
Review comment:
👍
--
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]
