---
title: "search neighbors · RUAL Documentation"
description: "Given an anchor GUID, returns the N documents directly before and the M directly after it when the storage is sorted by the chosen field. Use this to sh…"
canonical: https://docs.rual.nl/block-types/storage/function_search_neighbors
language: en
---

# search neighbors

This block is part of the [`storage`](https://docs.rual.nl/block-types/storage) group and was last modified in core [`v15.0.0`](https://docs.rual.nl/core-versions/150000).

### Storage Selection Required

This block relies on a storage to perform its storage releated actions. You must manually select the storage you want to use in your flow using the storage selector modal. To access the modal, click the white button on the block.

Given an anchor GUID, returns the N documents directly before and the M directly after it when the storage is sorted by the chosen field. Use this to show context around a specific document (e.g. messages around a chat message) without paginating the whole storage.

- flow `flow`

- Anchor GUID required `value` GUID of the document to centre the window on.

- Sort Field required `value` Field used to order the storage, e.g. `_meta.created` for a chat message timeline.

- Sort Order `value` Direction of the list the user sees: `desc` (newest first, default) or `asc`.

Default `desc`

- Before `number` How many documents to fetch immediately before the anchor in the sorted list.

Default `2`

- After `number` How many documents to fetch immediately after the anchor in the sorted list.

Default `2`

- Query `query` Optional scope filters : e.g. restrict neighbors to the same chat room. Same shape as the `search` block. • Suggestions: `query_bool_must` `query_bool_must_not` `query_bool_should`

- Storage `storage`

- flow `flow`

- Before `array` Documents immediately before the anchor, ordered in the requested display order.

- Anchor `object` The anchor document itself, or null if not found.

- After `array` Documents immediately after the anchor, ordered in the requested display order.

- Combined `array` Before + anchor + after concatenated in display order : ready to render as a single list.

- Found `condition` True when the anchor document was located.

- success `condition`

- error `value`

| `around` |
| --- |
| `context` |
| `surrounding` |
| `neighbors` |
| `database` |

A typical wiring for [search neighbors](https://docs.rual.nl/block-types/storage/function_search_neighbors): a [function trigger](https://docs.rual.nl/block-types/globals/trigger_custom_function) starts the flow; [value](https://docs.rual.nl/block-types/value/value_default) feeds the `guid` pin; [value](https://docs.rual.nl/block-types/value/value_default) feeds the `sort_field` pin; the `flow` out pin feeds [debug](https://docs.rual.nl/block-types/state%20ui/state_debug).

![Studio canvas example for the search neighbors block: typical wiring for search neighbors.](https://docs.rual.nl/canvas-examples/function_search_neighbors.png)

### Version history

Introduced in [`v15.0.0`](https://docs.rual.nl/core-versions/150000).