Metadata Properties

Blocks support metadata, a map of data about the block. The metadata system allows for arbitrary annotation of data. It could be used by developers for many purposes, annotating data sources, transformations, policy etc.

#+src sql SalesPerCountry()
#+meta {
   :author "John Doe"
}
   ...
#+end

#+src sql blockName(value)
#+meta {
      :doc "First line should be a summary of a block.
  Next lines should give more detailed description.
  Our tool will be using this convention to display documentation
  summary / full description when requested.
  All whitespaces at the beginning of the multi-line docstrings will be ignored. This could be used to indent lines according
  to your visual preferences. In this example we use two spaces indentation.

  Try to document all positional arguments, and wrap them with a backticks (`) so that editors and IDEs can identify
  them and potentially provide extra functionality.
  For example, given block accepts `value` argument which expected to be INTEGER."
}
#+begin
  SELECT {{ value }}
#+end

Multiline string literals

If you need a string that spans several lines, use a multiline string literal - a sequence of characters surrounded by double (") quote marks. A multiline string literal includes all of the lines between its opening and closing quotation marks. When your source code includes a line break inside of a multiline string literal, that line break also appears in the string’s value. The use of \n in a multiline string literal is permitted, but not necessary or recommended.

For example, multiline string literal:

"line 1
line 2
line 3"

is equivalent to the string literal:

"line 1\nline 2\nline 3"

or a concatenation of string literals:

"line 1\n" +
"line 2\n" +
"line 3"

Incidental white space

Multiline string literals shown above were easier to read than their concatenated string literal counterparts, but the obvious interpretation for the content of a multiline string literal would include the spaces added to indent the embedded string so that it lines up neatly with the opening delimiter.

Here is the example using dashes to visualize the spaces that the developer added for indentation:

SELECT * FROM {{ block("
-----------------------line 1
-----------------------  line 2
-----------------------    line 3
-----------------------  line 4
-----------------------line 5
-----------------------")
              }}

Spaces may also appear at the end of each line. Trailing white space is most often unintentional, idiosyncratic, and insignificant. It is overwhelmingly likely that the developer does not care about it.

SELECT * FROM {{ block("
-----------------------line 1---
-----------------------  line 2--
-----------------------    line 3------
-----------------------  line 4---
-----------------------line 5-
-----------------------")
              }}

Accordingly, an appropriate interpretation for the content of a multiline string literal is to differentiate incidental white space at the start and end of each line, from essential white space. Using | to visualize margins:

|line 1|
|  line 2|
|    line 3|
|  line 4|
|line 5|

The re-indentation algorithm takes the content of a multiline string literal, it removes the same amount of white space from each line of content until at least one of the lines has a non-white space character in the leftmost position. The position of the opening double (“) quote mark has no effect on the algorithm, but the position of the closing double (”) quote mark does have an effect if placed on its own line.