---
url: /process-functions/mapping-findfirstusingleft.md
description: Finds the first mapping row that matches the given left keys.
---

# mapping.findFirstUsingLeft

Finds the first mapping row that matches the given left keys. Use it when you expect at most one match. To get every match, use [mapping.findUsingLeft](/process-functions/mapping-findusingleft).

```js
mapping.findFirstUsingLeft(mappingName, leftKeys)
```

## Parameters

| Parameter | Type | Description |
|---|---|---|
| `mappingName` | `string` | The mapping's name or id. |
| `leftKeys` | `string[]` | One element for each dimension on the left side, in order. |

## Returns

The row as a JSON string, with its `id`, `left` keys and `right` keys. Use `JSON.parse()` to read it. Returns `null` when no row matches or the mapping can't be found.

## Examples

::: code-group

```js [find.js]
const row = JSON.parse(mapping.findFirstUsingLeft("Time to Year and Month", ["FY2017 - Jul"]));
```

```json [Result]
{
    "id": 1,
    "left": ["FY2017 - Jul"],
    "right": ["2017", "Jul"]
}
```

:::

## Related

* [mapping.findUsingLeft](/process-functions/mapping-findusingleft): returns every row that matches.
* [mapping.findFirstUsingRight](/process-functions/mapping-findfirstusingright): looks up the other way.