Skip to content

Commit

Permalink
Document dollar-quoted string literal syntax
Browse files Browse the repository at this point in the history
Fixes #6906.

Summary of changes:

- Add new section on dollar-quoted strings to 'SQL Constants' page

- Add more linkage from `STRING` data type page to the string literal
  syntax info
  • Loading branch information
rmloveland committed May 6, 2020
1 parent 08f229a commit 9409a2b
Show file tree
Hide file tree
Showing 2 changed files with 33 additions and 3 deletions.
33 changes: 31 additions & 2 deletions v20.1/sql-constants.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,13 @@ There are five categories of constants in CockroachDB:

## String literals

CockroachDB supports two formats for string literals:
CockroachDB supports the following formats for string literals:

- [Standard SQL string literals](#standard-sql-string-literals).
- [String literals with C escape sequences](#string-literals-with-character-escapes).
- [Dollar-quoted string literals](#dollar-quoted-string-literals)

These format also allow arbitrary Unicode characters encoded as UTF-8.
These formats also allow arbitrary Unicode characters encoded as UTF-8.

In any case, the actual data type of a string literal is determined
using the context where it appears.
Expand Down Expand Up @@ -121,6 +122,34 @@ 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.

### Dollar-quoted string literals

<span class="version-tag">New in v20.1:</span> To make it easier to write certain types of string constants in SQL code, CockroachDB supports dollar-quoted string literals. This is particularly useful for strings that need to contain lots of single quotes (`'`) or backslashes (`\`).

At a high level, the dollar-quoting behavior works similarly to ["heredocs"](https://en.wikipedia.org/wiki/Here_document) as used in UNIX shells and some programming languages.

Dollar-quoted strings have the form: `$` + (optional) tag + `$` + arbitrary text + `$` + (optional) tag + `$`

For example:

{% include copy-clipboard.html %}
~~~ sql
SELECT char_length($MyCoolString$
You can put anything you want in this string -- for example, here's a Windows filesystem pathname: 'C:\Users\foo\Downloads\file.zip'

You can even nest additional dollar-quoted strings inside each other. For example, here is a regular expression using backticks: $myRegex$[foo\tbar]$myRegex$

Finally, you can use $stand-alone dollar signs without the optional tag$.
$MyCoolString$);
~~~

~~~
char_length
---------------
369
(1 row)
~~~

## Numeric literals

Numeric literals can have the following forms:
Expand Down
3 changes: 2 additions & 1 deletion v20.1/string.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,4 +164,5 @@ A literal entered through a SQL client will be translated into a different value

## See also

[Data Types](data-types.html)
- [Data Types](data-types.html)
- [String literal syntax](sql-constants.html#string-literals)

0 comments on commit 9409a2b

Please sign in to comment.