when

when, process option

The process option when is used to filter lines from the processed table before the lines are passed to the Envision process. This allows for conditional inclusion of data in aggregation operations.

when accepts a boolean expression that determines which rows will be included in the processing. Only rows where the condition evaluates to true are passed to the process.

Examples

Basic filtering with a built-in aggregator:

table T = with
  [| as Id, as X |]
  [| "a",   3    |]
  [| "b",   1    |]
  [| "c",   4    |]

// Parenthesis needed on expression due to operator priorities.
x = join(T.Id; "") when (T.X != 1) sort T.X
y = join(T.Id; "") when (T.X <= 3) sort T.X

show summary "Filtered joins" with x, y

This produces:

In the first case, the join aggregator only processes rows where T.X != 1, resulting in "ac" (combining "a" and "c" but skipping "b").

In the second case, it only processes rows where T.X <= 3, resulting in "ba" (note that the order is determined by sort T.X).

Filtering with a user-defined process:

table T = with
  [| as Id, as X |]
  [| "a",   3    |]
  [| "b",   1    |]
  [| "c",   4    |]

def process mySum(x : number) with
  keep total = 0
  total = total + x
  return total

// 'sort' is still required, even if ordering doesn't matter here.
x = mySum(T.X) when (T.Id != "a") sort T.X
y = mySum(T.X) when (T.Id == "c") sort T.X

show summary "Filtered sums" with x, y

This produces:

The first sum excludes the row with Id of "a", so it adds up just 1 + 4 = 5.

The second sum only includes the row with Id of "c", so it equals 4.

Remarks

Parentheses are often needed around the filter condition due to operator precedence, especially when the condition involves comparison operators like <, >, ==, etc.

Unlike the where statement which creates a filtering block, the when option is specific to a single process operation and its scope is limited to that operation.

Recipes and best practices

1. Use when for process-specific filtering: When you only need to filter data for a specific aggregation, use when instead of a broader where block.
2. Consider readability: For complex conditions, you may want to compute the filter condition as a separate boolean vector and then use it in the when clause for better readability.
3. Remember parentheses: It is better to always use parentheses around the condition to avoid operator precedence issues.

See also

• where
• sort
• scan
• join
• process
• Filtering in Envision