Merge pull request #1008 from knz/knz-updates

New docs on expressions and constants

Author: jseldess

bool.md

@@ -12,14 +12,17 @@ The `BOOL` [data type](data-types.html) stores a Boolean value of `false` or `tr
 
 In CockroachDB, `BOOLEAN` is an alias for `BOOL`. 
 
-## Format
+## Syntax
 
-When inserting into a `BOOL` column, format the value as `false` or `true` (case-insensitive).
+There are two predefined
+[named constants](sql-constants.html#named-constants) for `BOOL`:
+`TRUE` and `FALSE` (the names are case-insensitive).
 
-Alternately, you can cast `0` or `1` as a `BOOL`:
+Alternately, a boolean value can be obtained by coercing a numeric
+value: zero is coerced to `FALSE`, and any non-zero value to `TRUE`.
 
 - `CAST(0 AS BOOL)` (false)
-- `CAST(1 AS BOOL)` (true)
+- `CAST(123 AS BOOL)` (true)
 
 ## Size
 
@@ -69,4 +72,4 @@ Type | Details
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)

bytes.md

@@ -15,15 +15,17 @@ In CockroachDB, the following are aliases for `BYTES`:
 - `BYTEA` 
 - `BLOB` 
 
-## Formats
+## Syntax
 
-When inserting into a `BYTES` column, use any of the following formats:
+To express a byte array constant, see the section on
+[byte array literals](sql-constants.html#byte-array-literals) for more
+details. For example, the following three are equivalent literals for the same
+byte array: `b'abc'`, `b'\141\142\143'`, `b'\x61\x62\x63'`.
 
-- 1 octet per byte: `b'\141\061\142\062\143\063'`
-- 2 hexadecimal digits per byte: `b'\x61\x31\x62\x32\x63\x33'`. 
-- String literal: `'a1b2c3'`
-
-You can also use these in combination, for example, `b'\141\061\x62\x32\c3'`.
+In addition to this syntax, CockroachDB also supports using
+[string literals](sql-constants.html#string-literals), including the
+syntax `'...'`, `e'...'` and `x'....'` in contexts where a byte array
+is otherwise expected.
 
 ## Size
 
@@ -34,7 +36,12 @@ The size of a `BYTES` value is variable, but it's recommended to keep values und
 ~~~ sql
 > CREATE TABLE bytes (a INT PRIMARY KEY, b BYTES);
 
-> INSERT INTO bytes VALUES (1, 'abc'), (2, b'\141\142\143'), (3, b'\x61\x62\x63'), (4, b'\141\x62\c');
+> -- explicitly typed BYTES literals
+> INSERT INTO bytes VALUES (1, b'\141\142\143'), (2, b'\x61\x62\x63'), (3, b'\141\x62\c');
+
+> -- string literal implicitly typed as BYTES
+> INSERT INTO bytes VALUES (4, 'abc');
+
 
 > SELECT * FROM bytes;
 ~~~
@@ -50,14 +57,16 @@ The size of a `BYTES` value is variable, but it's recommended to keep values und
 (4 rows)
 ~~~
 
-## Supported Casting & Conversion 
+## Supported Conversions
 
-`BYTES` values can be [cast](data-types.html#data-type-conversions--casts) to any of the following data types:
+`BYTES` values can be
+[cast](data-types.html#data-type-conversions--casts) explicitly to
+`STRING`. The conversion verifies that the byte array contains only
+valid UTF-8 byte sequences; an error is reported otherwise.
 
-Type | Details
------|--------
-`STRING` | Requires the byte array to contain only valid UTF-8 character encodings.
+`STRING` values can be cast explicitly to `BYTES`. This conversion
+always succeeds.
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)

data-types.md

@@ -26,12 +26,20 @@ Type | Description | Example
 
 CockroachDB supports explicit type conversions using the following methods:
 
-- `<value>::<data type>`, or its equivalent longer form `CAST(<value> AS <data type>)`, which converts an arbitrary expression of one built-in type to another (this is also known as "casting"). For example:
-`NOW()::DECIMAL`, `VARIANCE(a+2)::INT`.
-
 - `<type> 'string literal'`, to convert from the literal representation of a value to a value of that type. For example:
-`DATE '2008-12-21'`, `INT '123'`, or `BOOL 'true'`.
+  `DATE '2008-12-21'`, `INT '123'`, or `BOOL 'true'`.
+
+- `<value>::<data type>`, or its equivalent longer form `CAST(<value> AS <data type>)`, which converts an arbitrary expression of one built-in type to another (this is also known as type coercion or "casting"). For example:
+  `NOW()::DECIMAL`, `VARIANCE(a+2)::INT`.
+
+  {{site.data.alerts.callout_success}}
+  To create constant values, consider using a
+  <a href="sql-expressions.html#explicitly-typed-expressions">type annotation</a>
+  instead of a cast, as it provides more predictable results.
+  {{site.data.alerts.end}}
 
 - Other [built-in conversion functions](functions-and-operators.html) when the type is not a SQL type, for example `from_ip()`, `to_ip()` to convert IP addresses between `STRING` and `BYTES` values.
 
-You can find each data type's supported converstion and casting on its respective page in the **Supported Casting & Conversion** section.
+
+You can find each data type's supported converstion and casting on its
+respective page in its section **Supported Casting & Conversion**.

date.md

@@ -8,13 +8,21 @@ The `DATE` [data type](data-types.html) stores a year, month, and day.
 
 <div id="toc"></div>
 
-## Format
+## Syntax
 
-When inserting into a `DATE` column, format the value as `DATE '2016-01-25'`.
+A constant value of type `DATE` can be expressed using an
+[interpreted literal](sql-constants.html#interpreted-literals), or a
+string literal
+[annotated with](sql-expressions.html#explicitly-typed-expressions)
+type `DATE` or
+[coerced to](sql-expressions.html#explicit-type-coercions) type
+`DATE`.
 
-Alternatively, you can use a string literal, e.g., `'2016-01-25'`, which CockroachDB will resolve into the `DATE` type.
+The string format for dates is `YYYY-MM-DD`. For example: `DATE '2016-12-23'`.
 
-Note that in some contexts, dates may be displayed with hours, minutes, seconds, and timezone set to 0.
+CockroachDB also supports using uninterpreted
+[string literals](sql-constants.html#string-literals) in contexts
+where a `DATE` value is otherwise expected.
 
 ## Size
 
@@ -36,15 +44,20 @@ A `DATE` column supports values up to 8 bytes in width, but the total storage si
 +-------+------+-------+---------+
 ~~~
 ~~~ sql
+> -- explicitly typed DATE literal
 > INSERT INTO dates VALUES (DATE '2016-03-26', 12345);
 
+> -- string literal implicitly typed as DATE
+> INSERT INTO dates VALUES ('2016-03-27', 12345);
+
 > SELECT * FROM dates;
 ~~~
 ~~~
 +---------------------------+-------+
 |             a             |   b   |
 +---------------------------+-------+
 | 2016-03-26 00:00:00+00:00 | 12345 |
+| 2016-03-27 00:00:00+00:00 | 12345 |
 +---------------------------+-------+
 ~~~
 
@@ -64,4 +77,4 @@ Type | Details
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)

decimal.md

@@ -26,11 +26,10 @@ When inserting a decimal value:
 - If digits to the left and right of the decimal point exceed the column's `precision`, CockroachDB gives an error.  
 - If the column's `precision` and `scale` are identical, the inserted value must round to less than 1.
 
-## Format
+## Syntax
 
-When inserting into a `DECIMAL` column, format the value as a numeric literal, e.g., `1.2345` or `1`. 
-
-Alternately, you can cast a float as a decimal: `CAST(1.2345 AS DECIMAL)`. However, note that the precision will be limited to 17 digits in total (both to the left and right of the decimal point). 
+A constant value of type `DECIMAL` can be entered as a [numeric literal](sql-constants.html#numeric-literals).
+For example: `1.414` or `-1234`.
 
 ## Size
 
@@ -53,19 +52,19 @@ The size of a `DECIMAL` value is variable, starting at 9 bytes. It's recommended
 +-------+---------------+-------+---------+
 ~~~
 ~~~ sql
-> INSERT INTO decimals VALUES (1.01234567890123456789, 1.01234567890123456789, CAST(1.01234567890123456789 AS DECIMAL));
+> INSERT INTO decimals VALUES (1.01234567890123456789, 1.01234567890123456789, 1.01234567890123456789);
 
 > SELECT * FROM decimals;
 ~~~
 ~~~
-+------------------------+---------+--------------------+
-|           a            |    b    |         c          |
-+------------------------+---------+--------------------+
-| 1.01234567890123456789 | 1.01235 | 1.0123456789012346 |
-+------------------------+---------+--------------------+
++------------------------+---------+-----------------------+
+|           a            |    b    |         c             |
++------------------------+---------+-----------------------+
+| 1.01234567890123456789 | 1.01235 | 1.0123456789012346789 |
++------------------------+---------+-----------------------+
 # The value in "a" matches what was inserted exactly.
 # The value in "b" has been rounded to the column's scale.
-# The value in "c" has been limited to 17 digits.
+# The value in "c" is handled like "a" because NUMERIC is an alias.
 ~~~
 
 ## Supported Casting & Conversion
@@ -79,8 +78,6 @@ Type | Details
 `BOOL` |  **0** converts to `false`; all other values convert to `true`
 `STRING` | ––
 
-{{site.data.alerts.callout_info}}Because the <a href="serial.html"><code>SERIAL</code> data type</a> represents values automatically generated CockroachDB to uniquely identify rows, you cannot meaningfully cast other data types as <code>SERIAL</code> values.{{site.data.alerts.end}}
-
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)

float.md

@@ -4,7 +4,10 @@ summary: The FLOAT data type stores inexact, floating-point numbers with up to 1
 toc: false
 ---
 
-The `FLOAT` [data type](data-types.html) stores inexact, floating-point numbers with up to 17 digits in total and at least one digit to the right of the decimal point. 
+The `FLOAT` [data type](data-types.html) stores inexact, floating-point numbers with up to 17 digits of decimal precision.
+
+They are handled internally using the [standard double-precision
+(64-bit binary-encoded) IEEE754 format](https://en.wikipedia.org/wiki/IEEE_floating_point).
 
 <div id="toc"></div>
 
@@ -15,14 +18,20 @@ In CockroachDB, the following are aliases for `FLOAT`:
 - `REAL` 
 - `DOUBLE PRECISION` 
 
-## Format
+## Syntax
 
-When inserting into a `FLOAT` column, format the value as a numeric literal, e.g., `1.2345` or `1`.
+A constant value of type `FLOAT` can be entered as a [numeric literal](sql-constants.html#numeric-literals).
+For example: `1.414` or `-1234`.
 
-Alternately, you can cast `+Inf` (positive infinity), `-Inf` (negative infinity), or `NaN` (not a number) as a float:
+The special IEEE754 values for positive infinity, negative infinity
+and Not A Number (NaN) cannot be entered using numeric literals
+directly and must be converted using an
+[interpreted literal](sql-constants.html#interpreted-literals) or an
+[explicit conversion](sql-expressions.html#explicit-type-coercions) from
+a string literal instead. For example:
 
-- `CAST('+Inf' AS FLOAT)`
-- `CAST('-Inf' AS FLOAT)`
+- `FLOAT '+Inf'`
+- `'-Inf'::FLOAT`
 - `CAST('NaN' AS FLOAT)`
 
 ## Size
@@ -61,16 +70,15 @@ A `FLOAT` column supports values up to 8 bytes in width, but the total storage s
 
 ## Supported Casting & Conversion
 
-`DECIMAL` values can be [cast](data-types.html#data-type-conversions--casts) to any of the following data types:
+`FLOAT` values can be [cast](data-types.html#data-type-conversions--casts) to any of the following data types:
 
 Type | Details
 -----|--------
 `INT` | Truncates decimal precision and requires values to be between -2^63 and 2^63-1
-`DECIMAL` | ––
+`DECIMAL` | Causes an error to be reported if the value is NaN or +/- Inf.
 `BOOL` |  **0** converts to `false`; all other values convert to `true`
-
-{{site.data.alerts.callout_info}}Because the <a href="serial.html"><code>SERIAL</code> data type</a> represents values automatically generated CockroachDB to uniquely identify rows, you cannot meaningfully cast other data types as <code>SERIAL</code> values.{{site.data.alerts.end}}
+`STRING` | --
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)

int.md

@@ -20,17 +20,10 @@ In CockroachDB, the following are aliases for `INT`:
 - `INT64` 
 - `BIGINT`
 
-## Formats
+## Syntax
 
-An `INT` column accepts numeric literals and hexadecimal-encoded numeric literals.
-
-### Numeric Literal
-
-When inserting a numeric literal into an `INT` column, format the value as `12345`.
-
-### Hexadecimal-Encoded Numeric Literal
-
-When inserting a hexadecimal-encoded numeric literal into a `INT` column, format the value as hexadecimal digits preceded by `0x`. For example, `0xcafe1111` corresponds to the numeric literal `3405648145`.
+A constant value of type `INT` can be entered as a [numeric literal](sql-constants.html#numeric-literals).
+For example: `42`, `-1234` or `0xCAFE`.
 
 ## Size
 
@@ -74,15 +67,13 @@ CockroachDB does not offer multiple integer types for different widths; instead,
 Type | Details
 -----|--------
 `DECIMAL` | ––
-`FLOAT` | Requires `INT` value to be less than 2^53
+`FLOAT` | Loses precision if the `INT` value is larger than 2^53 in magnitude
 `BOOL` | **0** converts to `false`; all other values convert to `true`
 `DATE` | Converts to days since the Unix epoch (Jan. 1, 1970)
 `TIMESTAMP` | Converts to seconds since the Unix epoch (Jan. 1, 1970)
 `INTERVAL` | Converts to microseconds
 `STRING` | ––
 
-{{site.data.alerts.callout_info}}Because the <a href="serial.html"><code>SERIAL</code> data type</a> represents values automatically generated CockroachDB to uniquely identify rows, you cannot meaningfully cast other data types as <code>SERIAL</code> values.{{site.data.alerts.end}}
-
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)

interval.md

@@ -8,18 +8,28 @@ The `INTERVAL` [data type](data-types.html) stores a value that represents a spa
 
 <div id="toc"></div>
 
-## Formats
+## Syntax
 
-When inserting into an `INTERVAL` column, use one of the following formats:
+A constant value of type `INTERVAL` can be expressed using an
+[interpreted literal](sql-constants.html#interpreted-literals), or a
+string literal
+[annotated with](sql-expressions.html#explicitly-typed-expressions)
+type `INTERVAL` or
+[coerced to](sql-expressions.html#explicit-type-coercions) type
+`INTERVAL`.
+
+`INTERVAL` constants can be expressed using the following formats:
 
 Format | Description
 -------|--------
-Golang | `INTERVAL '1h2m3s4ms5us6ns'`<br><br>Note that `ms` is milliseconds, `us` is microseconds, and `ns` is nanoseconds. Also, all fields support both integers and floats.
-Traditional Postgres | `INTERVAL '1 year 2 months 3 days 4 hours 5 minutes 6 seconds'` 
-ISO 8601 | `INTERVAL 'P1Y2M3DT4H5M6S'`
 SQL Standard | `INTERVAL 'Y-M D H:M:S'`<br><br>`Y-M D`: Using a single value defines days only; using two values defines years and months. Values must be integers.<br><br>`H:M:S`: Using a single value defines seconds only; using two values defines hours and minutes. Values can be integers or floats.<br><br>Note that each side is optional.
+ISO 8601 | `INTERVAL 'P1Y2M3DT4H5M6S'`
+Traditional PostgreSQL | `INTERVAL '1 year 2 months 3 days 4 hours 5 minutes 6 seconds'`
+Golang | `INTERVAL '1h2m3s4ms5us6ns'`<br><br>Note that `ms` is milliseconds, `us` is microseconds, and `ns` is nanoseconds. Also, all fields support both integers and floats.
 
-Alternatively, you can use a string literal, e.g., `'1h2m3s4ms5us6ns'` or`'1 year 2 months 3 days 4 hours 5 minutes 6 seconds'`, which CockroachDB will resolve into the `INTERVAL` type.
+CockroachDB also supports using uninterpreted
+[string literals](sql-constants.html#string-literals) in contexts
+where a `INTERVAL` value is otherwise expected.
 
 Intervals are stored internally as months, days, and nanoseconds.
 
@@ -51,9 +61,9 @@ CREATE TABLE
 ~~~
 
 ~~~ sql
-> INSERT INTO intervals VALUES 
-  (1, INTERVAL '1h2m3s4ms5us6ns'), 
-  (2, INTERVAL '1 year 2 months 3 days 4 hours 5 minutes 6 seconds'), 
+> INSERT INTO intervals VALUES
+  (1, INTERVAL '1h2m3s4ms5us6ns'),
+  (2, INTERVAL '1 year 2 months 3 days 4 hours 5 minutes 6 seconds'),
   (3, INTERVAL '1-2 3 4:5:6');
 ~~~
 
@@ -89,4 +99,4 @@ Type | Details
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)