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

# find by key - value

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

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

- array required `array` Array of objects to search within.

- field required `value` Field in array of objects to match with.

- results `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.

KEEPS items whose key field equals the comparison value, outputting matches on array and their original positions on array_indexes; it does NOT exclude them. With key empty the item ITSELF is compared, so flat value arrays work. On the legacy value pin comparison is by TEXT (the number 1 matches the string "1"); on a type-selected pin numbers match across int/float but numeric strings do NOT match numbers. Non-object items are dropped when a key is set.

| `where key` |
| --- |
| `===` |

A typical wiring for [find by key - value](https://docs.rual.nl/block-types/array/array_get_objects_by_field_value): [value](https://docs.rual.nl/block-types/value/value_default) feeds the `key` pin; [search](https://docs.rual.nl/block-types/storage/function_search) feeds the `array` pin; [custom field](https://docs.rual.nl/block-types/object/object_get_custom_field) feeds the `value` pin; the `array` out pin feeds [length](https://docs.rual.nl/block-types/array/array_length); the `array_indexes` out pin feeds [get first item](https://docs.rual.nl/block-types/array/array_first_item).

![Studio canvas example for the find by key - value block: typical wiring for find by key - value.](https://docs.rual.nl/canvas-examples/array_get_objects_by_field_value.png)

### Commonly used with

In production blueprints, this block is most often wired together with:

- [value](https://docs.rual.nl/block-types/value/value_default): feeds into this block. Simply returns the provided value.

- [length](https://docs.rual.nl/block-types/array/array_length): this block feeds into it. Returns the total length of the given array.

- [search](https://docs.rual.nl/block-types/storage/function_search): feeds into this block. searches in the given storage based on a query.

- [create](https://docs.rual.nl/block-types/globals/trigger_custom_function): feeds into this block. Creates a new function that can be executed using the given name.

- [get fields](https://docs.rual.nl/block-types/object/object_field_getter_multiple): feeds into this block. Gets the selected fields from the given object.

- [custom field](https://docs.rual.nl/block-types/object/object_get_custom_field): feeds into this block. get the value of a custom field with a custom value block, or dynamic value.

### Version history

Introduced in [`v10.4.28`](https://docs.rual.nl/core-versions/100428).