String and char literals in query strings

A literal value is one that is explicitly defined in the code rather than computed or derived from other values. In the query language, literals commonly define constant values in expressions.

This guide covers char literals and string literals in query strings. Query strings use Java syntax for literals, so they follow Java conventions. A char literal is one character in single quotes, such as 'a'. A string literal goes in backticks, a Deephaven addition that stands in for Java's double quotes.

Char literals

A char literal holds exactly one character between single quotes (').

In Java, a char is a primitive data type that stores a single character, while a string is an object that represents a sequence of characters. Because char is a primitive type, it uses less memory and is faster to process than a string object that holds one character. In Groovy, 'a' is a one-character String, not a char.

The following code block creates two char columns. The sourceMeta table shows that each column's data type is char:

Unlike in Groovy, you can't put a string in single quotes in a query string. Deephaven reads single-quoted text longer than one character as a date-time literal, and the query fails if the text isn't a valid date-time value. Use backticks for strings, as described in String literals.

Char literals in query strings can't hold Java escape sequences such as \t. The backslash reaches the query language when you write '\\t'. Then '\t' is two characters between the quotes, so Deephaven reads it as a date-time literal and the query fails. To get a tab or newline, use an escape sequence in a string literal instead.

String literals

String literals in query strings contain zero or more characters inside backticks (`). For example, `Hello, World!` is a string literal.

Quote a string literal

Deephaven converts backticks to Java double quotes before it compiles the query string. Query strings also accept Java double quotes directly, so you can write a string literal in a Groovy query string in two ways:

  • Backticks inside a Groovy double-quoted string, such as "Greeting = `Hello`". No quotes need escaping.
  • Java double quotes inside a Groovy single-quoted string, such as 'Greeting = "Hello"'.

In Groovy, a double-quoted string is a GString, so $ starts interpolation. To put a $ in a query string, escape it ("Price = `\$3.50`") or use a single-quoted Groovy string ('Price = `$3.50`').

Quotes and escape sequences in a string literal

A backtick literal can contain double quotes. Deephaven escapes them when it converts the backticks. In Groovy, though, a double quote would end a double-quoted query string. Put such a query string in Groovy single quotes, as StringWithQuotesColumn does in the example below.

String literals can contain Java escape sequences such as \t (tab) and \n (newline). Because the query string is itself a Groovy string, Groovy turns \n into a real line break before Deephaven sees it. A Java string literal can't contain a line break, so the query fails. Escape the backslash (\\n) so the escape sequence reaches the query language.

The following query creates three string columns in the source table:

  • StringLiteralColumn holds a plain string literal.
  • StringWithQuotesColumn holds a literal that contains double quotes.
  • StringWithEscapeCharacter holds a literal with a tab. Its query string doubles the backslash, so \t reaches the query language as an escape sequence.

Apostrophes in a string literal

Deephaven looks for date-time literals before it reads backticks, and it doesn't skip string literals while it looks. It reads any two apostrophes in a formula with two or more characters between them as a date-time literal. As a result:

  • A string literal with one apostrophe, such as `It's`, works only when no other apostrophe appears in the same formula.
  • A string literal with two apostrophes, such as `Bob's and Al's`, fails, because Deephaven tries to parse s and Al as a date-time value.
  • A string literal that puts a valid date-time value between apostrophes, such as `Meet at '10:00' today`, runs, but the string holds a generated name such as _localTime0 in place of '10:00'.

To use text with apostrophes, store it in a Groovy variable and refer to the variable in the query string.

In the following example, the text variable holds two apostrophes. The apostrophes are in the value of text, not in the query string, so the search for date-time literals never sees them. Message holds Bob's and Al's:

Concatenate string and char literals

Use the + operator to concatenate strings and chars in a query string, whether they are literals or columns. + is evaluated left to right, and each + concatenates only when one of its two operands is a string.

Two chars add as numbers. + adds their numeric character codes and returns an int, so 'a' + 'b' is 195 and 'a' + 'b' + `!` gives 195!. To get ab, start the expression with a string: + 'a' + 'b'.

The following example builds Sentence from three columns that hold string literals, builds StringPlusChar by concatenating a string literal directly with a char literal, and builds CharPlusChar from two char literals:

In the source table, CharPlusChar holds 195, not ab. The sourceMeta table shows that its type is int, while StringPlusChar is a String.