Materialize

doc/user

This is the root directory of the Materialize user docs, which are rendered by the Hugo site in locally or at https://materialize.io/docs.

Instructions for previewing the documentation locally are contained in .

Writing & managing docs 

Railroad diagrams for SQL grammar 

Railroad diagrams consist of two parts:

To generate diagrams 

  1. Modify/create bnf files in /www/layouts/partials/sql-grammar/bnf.
  2. Ensure your diagram looks like you want using https://www.bottlecaps.de/rr/ui.
  3. Go to /www/util/rr-diagram-gen/
  4. Run make.

You can now include the diagram on a page using:

{{< diagram "SOME_DIAGRAM.html" >}}

Why is the world like this?

Because our diagrams rely on Hugo’s partials features, the diagram files are maintained in the /www dir (the actual Hugo site), but referenced as if they were local (through the magic of symlinks).

Function + Operator docs 

The Functions you see at www/docs/sql/functions/ are populated from www/data/sql_funcs.json. Unfortunately this means that they’re ad hoc and are not actually generated from the Materialize source code.

As new functions get added, this file must be manually updated. The idea here is to structure functions by their input type (whereas operators are grouped by their output type), largely influenced by the way that Postgres structures their function docs.

If you see the need to add or change the grouping here, don’t be shy.

Syntax highlighting 

Most code samples contain two components: the SQL query you want to run and the expected output.

Due to some design choice in the syntax highlighter used by Hugo, you must select a language to highlight the code blocks in or none of the expected formatting gets applied.

For SQL blocks, the natural choice is sql. For the response blocks, which don’t need to be/shouldn’t be syntax highlighted, you can use any non-recognized string as the language (i.e. anything that isn’t popular programming language). For expressivity, we chose nofmt.