docs: add documentation about DATE/TIME data types (#7746)

* docs: add documentation about DATE/TIME data types * Apply suggestions from code review Co-authored-by: Jim Galasyn <[email protected]> Co-authored-by: Jim Galasyn <[email protected]>
confluentinc · Jun 30, 2021 · 05d3599 · 05d3599
1 parent 9a381a8
commit 05d3599
Show file tree

Hide file tree

Showing 7 changed files with 50 additions and 6 deletions.
diff --git a/docs/developer-guide/ksqldb-reference/scalar-functions.md b/docs/developer-guide/ksqldb-reference/scalar-functions.md
@@ -55,7 +55,11 @@ Converts one type to another. The following casts are supported:
 | any  | `STRING` | Converts the type to its string representation. |
 | `VARCHAR` | `BOOLEAN` | Any string that exactly matches `true`, case-insensitive, is converted to `true`. Any other value is converted to `false`. |
 | `VARCHAR` | `INT`, `BIGINT`, `DECIMAL`, `DOUBLE` | Converts string representation of numbers to number types. Conversion will fail if text does not contain a number or the number does not fit in the indicated type. |
+| `VARCHAR` | `TIME` | Converts time strings to `TIME`. Conversion fails if text is not in `HH:mm:ss` format.     |
+| `VARCHAR` | `DATE` | Converts date strings to `DATE`. Conversion fails if text is not in `yyyy-MM-dd` format.     |
 | `VARCHAR` | `TIMESTAMP` | Converts datestrings to `TIMESTAMP`. Conversion fails if text is not in ISO-8601 format.     |
+| `TIMESTAMP` | `TIME`, `DATE` | Converts a `TIMESTAMP` to `TIME` or `DATE` by extracting the time or date portion of the `TIMESTAMP`.|
+| `DATE` | `TIMESTAMP` | Converts a `DATE` to `TIMESTAMP` by setting the time portion to `00:00:00.000` |
 | `INT`, `BIGINT`, `DECIMAL`, `DOUBLE` | `INT`, `BIGINT`, `DECIMAL`, `DOUBLE` | Convert between numeric types. Conversion can result in rounding |
 | `ARRAY` | `ARRAY` | (Since 0.14) Convert between arrays of different element types |   
 | `MAP` | `MAP` | (Since 0.14) Convert between maps of different key and value types |   

diff --git a/docs/developer-guide/ksqldb-reference/type-coercion.md b/docs/developer-guide/ksqldb-reference/type-coercion.md
@@ -52,8 +52,8 @@ Literal values support more open coercion rules than other expression types.
   Valid boolean values are `true`, `false`, `yes`, `no`, or any substring of
   these values that starts with the first character, for example, `fal`, `y`.
   Comparison is case-insensitive.
-* A `STRING` literal containing an ISO-8601 formatted datestring can be coerced
-  to a `TIMESTAMP`. A datestring containing a timezone is converted to UTC.
+* A `STRING` literal containing an ISO-8601 formatted date or time string can be coerced
+  to `TIMESTAMP`, `DATE` or `TIME`. A datestring containing a timezone is converted to UTC.
 
 ## Expression lists
 
@@ -71,6 +71,8 @@ behavior depends on the type of the first non-null element.
    list.
  * `BOOLEAN`: all other expressions must be coercible to `BOOLEAN`.
  * `TIMESTAMP`: all other expressions must be coercible to `TIMESTAMP`.
+ * `TIME`: all other expressions must be coercible to `TIME`.
+ * `DATE`: all other expressions must be coercible to `DATE`.
  * `ARRAY`: all other expressions must be `ARRAY`s and have element types that
    can be coerced to a common element type.
  * `MAP`: all other expressions must be `MAP`s and have key and value types

diff --git a/docs/developer-guide/ksqldb-rest-api/ksql-endpoint.md b/docs/developer-guide/ksqldb-rest-api/ksql-endpoint.md
@@ -123,7 +123,7 @@ Response JSON Object:
 - **sourceDescription.fields[i].schema** (object): A schema object that describes
   the schema of the field.
 - **sourceDescription.fields[i].schema.type** (string): The type the schema
-  represents. One of INTEGER, BIGINT, BOOLEAN, DOUBLE, STRING, TIMESTAMP, MAP, ARRAY, or
+  represents. One of INTEGER, BIGINT, BOOLEAN, DOUBLE, STRING, TIMESTAMP, TIME, DATE, MAP, ARRAY, or
   STRUCT.
 - **sourceDescription.fields[i].schema.memberSchema** (object): A schema object.
   For MAP and ARRAY types, contains the schema of the map values and array
@@ -157,7 +157,7 @@ Response JSON Object:
 - **queryDescription.fields** (array): A list of field objects that describes each field in the query output.
 - **queryDescription.fields[i].name** (string): The name of the field.
 - **queryDescription.fields[i].schema** (object): A schema object that describes the schema of the field.
-- **queryDescription.fields[i].schema.type** (string): The type the schema represents. One of INTEGER, BIGINT, BOOLEAN, DOUBLE, STRING, TIMESTAMP, MAP, ARRAY, or STRUCT.
+- **queryDescription.fields[i].schema.type** (string): The type the schema represents. One of INTEGER, BIGINT, BOOLEAN, DOUBLE, STRING, TIMESTAMP, TIME, DATE, MAP, ARRAY, or STRUCT.
 - **queryDescription.fields[i].schema.memberSchema** (object): A schema object. For MAP and ARRAY types, contains the schema of the map values and array elements, respectively. For other types this field is not used and its value is undefined.
 - **queryDescription.fields[i].schema.fields** (array): For STRUCT types, contains a list of field objects that descrbies each field within the struct. For other types this field is not used and its value is undefined.
 - **queryDescription.sources** (array): The streams and tables being read by the query.

diff --git a/docs/reference/serialization.md b/docs/reference/serialization.md
@@ -137,7 +137,11 @@ with `ORGID KEY` of `120`, `ID KEY` of `21`, `NAME` of `bob` and `AGE` of `49`.
 
 This data format supports all SQL
 [data types](/reference/sql/data-types) except `ARRAY`, `MAP` and
-`STRUCT`. `TIMESTAMP` typed data is serialized as a long value indicating the Unix epoch time in milliseconds.
+`STRUCT`. 
+
+`TIMESTAMP` typed data is serialized as a `long` value indicating the Unix epoch time in milliseconds.
+`TIME` typed data is serialized as an `int` value indicating the number of milliseconds since the beginning of the day.
+`DATA` typed data is serialized as an `int` value indicating the number of days since the Unix epoch.
 
 ### JSON
 
@@ -259,6 +263,34 @@ a timestamp at `1970-01-01T00:00:00.001` is serialized as
 ksqlDb deserializes a number as a `TIMESTAMP` if it corresponds to a `TIMESTAMP` typed field in
 the stream.
 
+#### Time Serialization
+
+Times are serialized as numbers indicating the number of milliseconds since the beginning of the day.
+For example, `00:00:01` is serialized as
+
+```json
+{
+  "value": 1000
+}
+```
+
+ksqlDb deserializes a number as a `TIME` if it corresponds to a `TIME` typed field in
+the stream.
+
+#### Date Serialization
+
+Dates are serialized as numbers indicating the number of days since the Unix epoch. For example,
+a timestamp at `1970-01-03` is serialized as
+
+```json
+{
+  "value": 2
+}
+```
+
+ksqlDb deserializes a number as a `DATE` if it corresponds to a `DATE` typed field in
+the stream.
+
 #### Field Name Case Sensitivity
 
 The format is case-insensitive when matching a SQL field name with a

diff --git a/docs/reference/sql/appendix.md b/docs/reference/sql/appendix.md
@@ -26,6 +26,7 @@ The following table shows all keywords in the language.
 | `CONNECTOR`    | manage a connector                    |  `CREATE SOURCE CONNECTOR 'jdbc-connector' WITH( …`                  |
 | `CONNECTORS`   | list all connectors                   |  `SHOW CONNECTORS;`                                                  |
 | `CREATE`       | create an object                      |  `CREATE STREAM rock_songs (artist VARCHAR, title VARCHAR) …`        |
+| `DATE`         | date data type                        |                                                                      |
 | `DAY`          | time unit of one day for a window     |  `WINDOW TUMBLING (SIZE 30 SECONDS, RETENTION 1 DAY)`                |
 | `DAYS`         | time unit of days for a window        |  `WINDOW TUMBLING (SIZE 30 SECONDS, RETENTION 1000 DAYS)`            |
 | `DECIMAL`      | decimal numeric type                  |                                                                      |
@@ -104,6 +105,7 @@ The following table shows all keywords in the language.
 | `TABLES`       | list all tables                       | `SHOW TABLES;`                                                       |
 | `TERMINATE`    | end a persistent query                | `TERMINATE query_id;`                                                |
 | `THEN`         | return expression in a CASE block     | `CASE WHEN units<2 THEN 'sm' WHEN units<4 THEN 'med' ELSE 'large' …` |
+| `TIME`         | time data type                        |                                                                      |
 | `TIMESTAMP`    | timestamp data type                   |                                                                      |
 | `TIMESTAMP`    | specify a timestamp column            | `CREATE STREAM pageviews WITH (TIMESTAMP='viewtime', …`              |
 | `TOPIC`        | specify {{site.ak}} topic to delete   | `DROP TABLE <table-name> DELETE TOPIC;`                              |

diff --git a/docs/reference/sql/data-types.md b/docs/reference/sql/data-types.md
@@ -81,10 +81,12 @@ and a scale of _0_.
 - Upcasting a `bigint` to a `decimal` produces a `decimal` with a precision of _19_
 and a scale of _0_.
 
-## Timestamp types
+## Time types
 
 | name      | description                                                     | backing Java type
 |-----------|-----------------------------------------------------------------|------------------
+|`time`     | value representing a time of day in millisecond precision.      | [`java.sql.Time`](https://docs.oracle.com/en/java/javase/11/docs/api/java.sql/java/sql/Time.html)
+|`date`     | value representing a calendar date independent of time zone.    | [`java.sql.Date`](https://docs.oracle.com/en/java/javase/11/docs/api/java.sql/java/sql/Date.html)
 |`timestamp`| value representing a point in time in millisecond precision without timezone information | [`java.sql.Timestamp`](https://docs.oracle.com/en/java/javase/11/docs/api/java.sql/java/sql/Timestamp.html)
 
 ## Compound types

diff --git a/docs/reference/user-defined-functions.md b/docs/reference/user-defined-functions.md
@@ -27,6 +27,8 @@ values.
 | `DOUBLE`  | `double`, `java.lang.Double`          |
 | `DECIMAL` | `java.math.BigDecimal`                |
 | `VARCHAR` | `java.lang.String`                    |
+| `TIME`    | `java.sql.Time`                       |
+| `DATE`    | `java.sql.Date`                       |
 |`TIMESTAMP`| `java.sql.Timestamp`                  |
 | `ARRAY`   | `java.util.List`                      |
 | `MAP`     | `java.util.Map`                       |