New docs on expressions and constants

knz · knz · commit ba2680008876 · 2017-01-17T18:39:29.000Z
diff --git a/decimal.md b/decimal.md
@@ -30,7 +30,8 @@ When inserting a decimal value:
 
 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). 
+For more details about decimal numeric formats,
+see the section on [SQL constants](sql-constants.html)
 
 ## Size
 
@@ -83,4 +84,4 @@ Type | Details
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)
diff --git a/float.md b/float.md
@@ -6,6 +6,9 @@ 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. 
 
+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>
 
 ## Aliases
@@ -19,10 +22,15 @@ In CockroachDB, the following are aliases for `FLOAT`:
 
 When inserting into a `FLOAT` column, format the value as a numeric literal, e.g., `1.2345` or `1`.
 
-Alternately, you can cast `+Inf` (positive infinity), `-Inf` (negative infinity), or `NaN` (not a number) as a float:
+For more details about `FLOAT` numeric formats,
+see the section on [SQL constants](sql-constants.html).
+
+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 instead. For example:
 
-- `CAST('+Inf' AS FLOAT)`
-- `CAST('-Inf' AS FLOAT)`
+- `FLOAT '+Inf'`
+- `'-Inf':::FLOAT`
 - `CAST('NaN' AS FLOAT)`
 
 ## Size
@@ -73,4 +81,4 @@ Type | Details
 
 ## See Also
 
-[Data Types](data-types.html)
+[Data Types](data-types.html)
diff --git a/sql-constants.md b/sql-constants.md
@@ -0,0 +1,220 @@
+---
+title: SQL Constant values
+summary: SQL Constants represent a simple value that doesn't change.
+toc: false
+---
+
+SQL Constants represent a simple value that doesn't change.
+
+<div id="toc"></div>
+
+## Introduction
+
+There are five categories of constants in CockroachDB:
+
+- string literals: these define string values but their actual data type will
+  be inferred from context, for example `'hello'`;
+- numeric literals: these define numeric values but their actual data
+  type will be inferred from context, for example `-12.3`;
+- byte array literals: these define byte array values with data type
+  `BYTES`, for example `b'hello'`;
+- interpreted literals: these define arbitrary values with an explicit
+  type, for example `INTERVAL '3 days'`.
+- named constants: these have predefined values with a predefined
+  type, for example `TRUE` or `NULL`.
+
+## String literals
+
+CockroachDB supports multiple formats for string literals:
+
+- standard SQL string literals
+- string literals with C escape sequences
+- hexadecimal-encoded strings
+
+The first two formats also allow arbitrary Unicode characters encoded as UTF-8.
+
+In all these cases, the actual data type of a string literal is determined 
+using the context where it appears.
+
+For example:
+
+| Expression | Data type of the string literal |
+|------------|---------------------------------|
+| `length('hello')` | `STRING` |
+| `now() + '3 day'`  | `INTERVAL` |
+| `INSERT INTO tb(date_col) VALUES ('2013-01-02')` | `DATE` |
+
+In general, the data type of a string literal is that demanded by the
+context if there is no ambiguity, or `STRING` otherwise.
+
+Check our blog for
+[more information about the typing of string literals](https://www.cockroachlabs.com/blog/revisiting-sql-typing-in-cockroachdb/).
+
+### Standard SQL string literals
+
+SQL string literals are formed by an arbitrary sequence of characters
+enclosed between single quotes (`'`), for example `'hello world'`. 
+to include a single quote in the string, use a double single quote.
+
+For example:
+
+```sql
+SELECT 'hello' as a, 'it''s a beautiful day' as b;
++-------+----------------------+
+|   a   |          b           |
++-------+----------------------+
+| hello | it's a beautiful day |
++-------+----------------------+
+```
+
+For compatibility with the SQL standard, CockroachDB also recognizes
+the following special syntax: two simple string literals separated by
+a newline character are automatically concatenated together to form a
+single constant. For example:
+
+```sql
+SELECT 'hello'
+' world!' as a;
++--------------+
+|      a       |
++--------------+
+| hello world! |
++--------------+
+```
+
+(This special syntax only works if the two simple literals are
+separated by a newline character. For example `'hello' ' world!'`
+doesn't work. This is mandated by the SQL standard.)
+
+### String literals with character escapes
+
+CockroachDB also supports string literals containing escape sequences
+like in the programming language C. These are constructed by prefixing
+the string literal with the letter `e`, for example
+`e'hello\nworld!'`.
+
+The following escape sequences are supported:
+
+Escape Sequence | Interpretation
+----------------|---------------
+`\a` | ASCII code 7 (BEL)
+`\b` | backspace (ASCII 8)
+`\t` | tab (ASCII 9)
+`\n` | newline (ASCII 10)
+`\v` | vertical tab (ASCII 11)
+`\f` | form feed (ASCII 12)
+`\r` | carriage return (ASCII 13)
+`\xHH` | hexadecimal byte value
+`\ooo` | octal byte value
+`\uXXXX` | 16-bit hexadecimal Unicode character value
+`\UXXXXXXXX` | 32-bit hexadecimal Unicode character value
+
+For example, the `e'x61\141\u0061'` escape string represents the
+hexadecimal byte, octal byte, and 16-bit hexadecimal Unicode character
+values equivalent to the `'aaa'` string literal.
+
+### Hexadecimal-encoded string literals
+
+This is a CockroachDB-specific extension to express string literals: the
+delimiter `x'` followed by an arbitrary sequence of hexadecimal
+digits, followed by a closing `'`.
+
+For example, `x'636174'` or `X'636174'` are equivalent to `'cat'`.
+
+## Numeric literals
+
+Numeric literals can have the following forms:
+
+```
+  [+-]9999
+  [+-]9999.[9999][e[+-]999]
+  [+-][9999].9999[e[+-]999]
+  [+-]9999e[+-]999
+  
+  [+-]0xAAAA
+```
+
+Some examples:
+
+```
+   +4269
+   3.1415
+   -.001
+   6.626e-34
+   50e6
+   0xcafe111
+```
+
+The actual data type of a numeric constant depends both on the context
+where it is used, its literal format and its numeric value.
+
+| Syntax | Possible data types |
+|--------|---------------------|
+| Contains a decimal separator | `FLOAT`, `DECIMAL` |
+| Contains an exponent | `FLOAT`, `DECIMAL` |
+| Contains a value larger than 2^64 in magnitude | `FLOAT`, `DECIMAL` |
+| Otherwise | `INT`, `DECIMAL`, `FLOAT` |
+
+Of the possible data types, which one is actually used is then further
+refined depending on context.
+
+Check our blog for
+[more information about the typing of numeric literals](https://www.cockroachlabs.com/blog/revisiting-sql-typing-in-cockroachdb/).
+
+## Byte array literals
+
+A byte array literal uses the same syntax as string literals containing character escapes,
+using a `b` prefix instead of `e`. Any character escapes are interpreted like they
+would be for string literals.
+
+For example: `b'hello,\x32world'`
+
+The two differences between byte array literals and string literals with character escapes are:
+
+- byte array literals always have data type `BYTES`, whereas the data
+  type of a string literal depends on context;
+- byte array literals may contain invalid UTF-8 byte sequences,
+  whereas string literals must always contain valid UTF-8 sequences.
+
+## Interpreted literals
+
+A constant of any data type can be formed using either of the following formats:
+
+```
+   type 'string'
+   'string':::type
+```
+
+The value of the string part is used as input for the conversion function to the
+specified data type, and the result is used as a constant with that data type.
+
+Examples:
+
+```
+   DATE '2013-12-23'
+   BOOL 'FALSE'
+   '42.69':::INT
+   'TRUE':::BOOL
+   '3 days':::INTERVAL
+```
+
+Additionally, for compatibility with PostgreSQL, the notation
+`'string'::type` and `CAST('string' AS type)` is also recognized as an
+interpreted literal. These are special cases of
+[cast expressions](sql-expressions.html).
+
+## Named constants
+
+CockroachDB recognizes the following SQL named constants:
+
+- `TRUE` and `FALSE`, the two possible values of data type `BOOL`;
+- `NULL`, the special SQL symbol that indicates "no value present".
+
+Note that `NULL` is a valid constant for any type: its actual data
+type during expression evaluation is determined based on context.
+
+## See Also
+
+- [Expressions](sql-expressions.html)
+- [Data Types](data-types.html)
+
diff --git a/sql-expressions.md b/sql-expressions.md
