---
title: "step matching by field · RUAL Documentation"
description: "Returns the matching objects for the given key-value pair in steps."
canonical: https://docs.rual.nl/block-types/array/array_matching_by_field
language: en
---

# 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).

### Type Selection Required

This block requires you to select the data type you want to work with. You must manually select the type using the type selector modal. To access the modal, click the white button on the block.

### Field Selection Required

This block requires field selection (in). You must manually select the fields you want to work with using the field selector modal. To access the modal, click the white button on the block.

Returns the matching objects for the given key-value pair in steps.

- stop after mismatch required `condition` If true, only the first contiguous run of matches is returned: scanning stops at the first mismatch AFTER a match. Mismatches before any match do not stop it. Required input pin.

- array required `array` The array of objects to be searched. Required input pin.

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

- matches `array` The array of objects that have the matching key and value.

- indexes `array` The original positions in the input array of each matched item.

- has match `condition` Condition indicating whether there is at least one match.

Selects items whose value at the key path equals the compare pin named after the selected type. Outputs the matches, their original indexes, and condition=true when at least one matched. With stopaftermismatch=true only the FIRST contiguous run of matches is returned: scanning stops at the first mismatch AFTER a match, while mismatches before any match do not stop it. Equality is strict; numbers compare by value across integer/float.

| `where key` |
| --- |

A typical wiring for [step matching by field](https://docs.rual.nl/block-types/array/array_matching_by_field): [==](https://docs.rual.nl/block-types/condition/condition_equal) feeds the `stopaftermismatch` pin; [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 `array` out pin feeds [length](https://docs.rual.nl/block-types/array/array_length).

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

### Version history

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