---
title: "grouped step matching by field · RUAL Documentation"
description: "Returns all matching objects for the given key-value pair in groups in steps ([A, A, A, B, B, A, C, C, C] becomes = [(A, A, A), (B, B), (A), (C, C, C)])."
canonical: https://docs.rual.nl/block-types/array/array_grouped_matching_by_field
language: en
---

# grouped step matching by field

This block is part of the [`array`](https://docs.rual.nl/block-types/array) group and was last modified in core [`v12.0.7`](https://docs.rual.nl/core-versions/120007).

Returns all matching objects for the given key-value pair in groups in steps ([A, A, A, B, B, A, C, C, C] becomes => [(A, A, A), (B, B), (A), (C, C, C)]).

- array required `array` The array of objects to be searched.

- key required `value` The key to be used for matching.

- grouped `array` An array of groups where each group contains matching objects.

Splits the array into CONSECUTIVE runs: a new group starts each time the key field's value differs from the previous item's, so equal values separated by a different value land in SEPARATE groups. Example: key values [A,A,B,A] -> [[A,A],[B],[A]]. Numbers compare across int/float; an empty input or unwired key outputs an empty grouped array.

A typical wiring for [grouped step matching by field](https://docs.rual.nl/block-types/array/array_grouped_matching_by_field): [with values](https://docs.rual.nl/block-types/array/array_of_values) feeds the `array` pin; [value](https://docs.rual.nl/block-types/value/value_default) feeds the `key` pin; the `grouped` out pin feeds [length](https://docs.rual.nl/block-types/array/array_length).

![Studio canvas example for the grouped step matching by field block: typical wiring for grouped step matching by field.](https://docs.rual.nl/canvas-examples/array_grouped_matching_by_field.png)

### Version history

Introduced in [`v12.0.7`](https://docs.rual.nl/core-versions/120007).