Memgraph Lab Write Gss

Writing Graph Style Script (GSS)

GSS is Memgraph's language for customizing graph visualization in Memgraph Lab. A GSS file is a sequence of expressions and directives.

Language basics

Value types

Boolean, Color, Number, String, Array, Map, Function, Null

Expressions

Three forms:

1. Literals -- strings "Hello", numbers 42 / 3.14, colors #ff0000, booleans True / False, Null
2. Name expressions -- identifiers bound via Define; all CSS/X11 color names are built-in (e.g. dodgerblue, gold, red)
3. Function calls -- FunctionName(arg1, arg2, ...)

Name rules: starts with a letter, may contain digits, -, _.

Strings support \ escaping for " and newlines.

Truthy / Falsy

Six falsy values: False, 0, "", Null, [] (empty array), {} (empty map). Everything else is truthy.

Short-circuit evaluation

If, And, Or skip branches that are not needed. Function() does not evaluate argument names or body until call time.

Directives

Directives are CSS-like blocks that set visual properties.

@<DirectiveName> <optional predicate> {
  <property-name>: <expression>
  ...
}

• Later directives override earlier ones (cascade, like CSS).
• Properties are name: expression pairs separated by newlines.
• The predicate is an optional boolean expression that filters which elements the directive applies to.

Available directives

@ViewStyle.Map is deprecated since Lab 3.4 -- use @ViewStyle with map-tile-layer instead.

Scope variables

Using node outside @NodeStyle or edge outside @EdgeStyle causes a compile error.

File structure and execution order

1. Global context: all expressions outside directives run first. Use for Define calls and cached computations. graph is available here.
2. @NodeStyle: evaluated per node.
3. @EdgeStyle: evaluated per relationship.

Global names are visible inside directives. Define inside a directive creates a local variable (useful for per-element caching).

Define(EDGE_COUNT, EdgeCount(graph))

@NodeStyle {
  size: Sqrt(NodeCount(graph))
}

@EdgeStyle {
  width: If(Greater(EDGE_COUNT, 1000), 1, 2)
}

@NodeStyle properties

@EdgeStyle properties

@ViewStyle properties

Map view requires nodes with latitude and longitude properties.

Custom functions

Use Define + Function to create reusable logic:

Define(square, Function(x, Mul(x, x)))
square(5)  // -> 25

Define(pow, Function(x, n,
  If(Equals(n, 1), x, Mul(x, pow(x, Sub(n, 1))))
))
pow(2, 10)  // -> 1024

Lambdas for higher-order functions:

Filter(AsArray(1, 2, 3, 4), Function(item, Greater(item, 2)))
// -> [3, 4]

Use Execute to run side-effect expressions and return the last value:

Execute(
  Set(map, "key1", "value1"),
  Set(map, "key2", "value2"),
  MapKeys(map)
)

Colors

Three ways to specify a color:

1. Named -- any X11/CSS color name: red, dodgerblue, gold, etc.
2. Hex literal -- #FF0000, #1E90FF
3. Functions -- RGB(r, g, b), RGBA(r, g, b, a), HSL(h, s, l), HSLA(h, s, l, a), Darker(color), Lighter(color), Mix(c1, c2)

Common patterns

Label from node property

@NodeStyle {
  label: Property(node, "name")
}

Conditional styling with predicates

@NodeStyle HasLabel(node, "Person") {
  color: dodgerblue
  size: 40
}

@NodeStyle And(HasLabel(node, "Person"), Greater(Property(node, "age"), 30)) {
  color: coral
}

Image on nodes

@NodeStyle HasLabel(node, "Country") {
  image-url: Format("https://flagcdn.com/w320/{}.png",
                    LowerCase(Property(node, "code")))
}

Override cascade (general then specific)

@NodeStyle {
  color: lightgray
  size: 20
}

@NodeStyle Equals(Property(node, "name"), "Special") {
  color: gold
  size: 50
}

Normalization with caching

Define(MIN_SIZE, 5)
Define(MAX_SIZE, 20)
Define(PROP, "age")
Define(SIZE_RANGE, Sub(MAX_SIZE, MIN_SIZE))

Define(GetProps, Function(nodes, prop,
  Map(nodes, Function(n, Property(n, prop)))
))
Define(KeepNumbers, Function(vals,
  Filter(vals, Function(v, IsNumber(v)))
))

Define(MAX_VAL, If(Greater(NodeCount(graph), 0),
  Max(KeepNumbers(GetProps(Nodes(graph), PROP))), 0))
Define(MIN_VAL, If(Greater(NodeCount(graph), 0),
  Min(KeepNumbers(GetProps(Nodes(graph), PROP))), 0))

Define(Normalize, Function(n,
  Add(MIN_SIZE, Mul(SIZE_RANGE,
    Div(Sub(Property(n, PROP), MIN_VAL), Sub(MAX_VAL, MIN_VAL))
  ))
))

@NodeStyle And(HasLabel(node, "Person"), IsNumber(Property(node, PROP))) {
  Define(NORM, Normalize(node))
  size: NORM
  label: Format("Age: {}", AsText(Property(node, PROP)))
}

Tree view auto-detection

@ViewStyle IsTreeStructure(graph) {
  view: "tree"
}

Edge styling by relationship type

@EdgeStyle Equals(Type(edge), "FRIENDS_WITH") {
  color: dodgerblue
  width: 2
  label: Type(edge)
}

Validation

If the validate-gss tool is available, always run it after writing or modifying GSS to catch syntax errors before applying the style in Memgraph Lab.

Preview

If the evaluate-gss tool is available, run it after validation to see how styles resolve against actual graph data. Pass custom nodes and relationships to the tool and inspect the computed style properties (color, size, label, etc.) for each node and edge. This catches logic errors that syntax validation cannot - such as a Property call on a missing key, overlapping predicates where the wrong rule wins, or a Format expression producing unexpected text.

Additional resources

• For the complete built-in function reference (90+ functions), see REFERENCE.md
• For more real-world GSS examples and patterns, see EXAMPLES.md