SHOW

Choose the columns a read returns, give them the names you want, and add computed values.

Syntax

SHOW is a clause of LOOKUP. List the columns, separated by commas.

SHOW("column", "column AS name", FUNCTION(…) AS name)

Parameters and arguments

SHOW needs at least one item. Each item is one of three forms.

  • "column"

    The column, under its own name

  • "column AS name"

    The column, under the name you chose. Write the column and name in one quoted text

  • FUNCTION(…) AS name

    A value computed from the row, such as LENGTH(id) AS chars. A function can hold other functions, such as LOWER(CONCAT(contentType, "-", id)). Without AS the name is expr

In a join, write a column as table.column, such as "assets.title".

Examples

The identifier as key, and the version as it is named.

Return type and behaviour

Each row holds the columns you listed, under their names or aliases, with column names in camelCase. Without SHOW, each row holds every column.

A column that holds an object or a list comes back whole, as an object or a list.

Errors and exceptions
ErrorWhat happenedHow to recover
HTQL-2001A column in SHOW does not exist on the tableCheck the column's name
HTQL-5001SHOW is empty: SHOW()List at least one column
HTQL-1003 Unsupported syntaxAn item is arithmetic outside a function, such as version * 10 AS xPut the arithmetic inside a function
Placement and context

Inside LOOKUP, among its clauses. In NEST, SHOW chooses the fields of each child. GET shapes its rows with RETURN instead.

Limitations
  • Not supported: arithmetic written directly as an item, such as SHOW(version * 10 AS x). An item is a column or a function call, so write arithmetic as a function's argument, such as ABS(version * 10) AS x.
  • The AS for a plain column goes inside the quotes: "id AS key". Outside the quotes it belongs to a function: LENGTH(id) AS chars.
  • Write the name after AS in lower case or in snake_case. Capital letters in it are lower-cased: AS typeName arrives as typename, while AS type_name arrives as typeName.
  • A column that is classified above the caller's clearance comes back masked, not refused.
Permissions and security

SHOW needs read access to the table in the LOOKUP. A column classified above the caller's clearance comes back masked: ***** for text columns and null for other columns.

Best practices
  • Choose only the columns you need.
  • Rename a column in SHOW when the code that reads it expects another name.
  • Use table.column in a join so it is clear which table each column comes from.
  • Compute display values, such as a label or a path, in SHOW so every client receives the same one.