> ## Documentation Index
> Fetch the complete documentation index at: https://new.docs.falkordb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# map.submap

> Creates a new map containing only the specified keys from the input map.

## Description

Creates a new map containing only the specified keys from the input map. This is the inverse of `removeKeys`.

## Syntax

```cypher theme={null}
flex.map.submap(map, keys)
```

## Parameters

| Parameter | Type | Required | Description                                    |
| --------- | ---- | -------- | ---------------------------------------------- |
| `map`     | map  | Yes      | The source map to extract keys from            |
| `keys`    | list | Yes      | An array of key names to include in the result |

## Returns

**Type:** map (object)

A new map containing only the specified keys and their values from the input map. Returns an empty map if input is not a valid object or keys is not an array.

## Examples

### Example 1: Basic Submap Extraction

```cypher theme={null}
WITH {name: 'Alice', age: 30, email: 'alice@example.com', city: 'NYC'} AS user
RETURN flex.map.submap(user, ['name', 'email']) AS contact
```

**Output:**

```text theme={null}
contact
---------------------------------
{name: 'Alice', email: 'alice@example.com'}
```

### Example 2: Selecting Specific Node Properties

```cypher theme={null}
MATCH (p:Product)
RETURN flex.map.submap(properties(p), ['id', 'name', 'price']) AS summary
```

### Example 3: Building API Response with Selected Fields

```cypher theme={null}
MATCH (u:User {id: $userId})
WITH properties(u) AS allProps
RETURN flex.map.submap(allProps, ['id', 'name', 'email', 'role']) AS userInfo
```

### Example 4: Handling Non-Existent Keys

```cypher theme={null}
WITH {a: 1, b: 2} AS map
RETURN flex.map.submap(map, ['a', 'c', 'd']) AS result
```

**Output:**

```text theme={null}
result
------
{a: 1}
```

(Only existing keys are included)

### Example 5: Dynamic Field Selection

```cypher theme={null}
WITH ['name', 'price', 'category'] AS requestedFields
MATCH (p:Product {id: 123})
RETURN flex.map.submap(properties(p), requestedFields) AS response
```

## Notes

* Returns empty map if input is not a valid object or keys is not an array
* `null` values in the keys array are ignored
* Non-existent keys are silently skipped
* Creates a new map; does not modify the original
* Useful for selecting specific fields, building API responses, or data projection
* More efficient than manually picking each field

## See Also

* [map.removeKeys](/udfs/flex/map/removeKeys) - Remove specific keys (inverse operation)
* [map.removeKey](/udfs/flex/map/removeKey) - Remove a single key
* [map.merge](/udfs/flex/map/merge) - Combine multiple maps

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="What does flex.map.submap do?">
    It extracts a subset of key-value pairs from a map, returning a new map containing only the specified keys.
  </Accordion>

  <Accordion title="What happens if a requested key does not exist in the map?">
    Missing keys are simply omitted from the resulting submap — no error is thrown.
  </Accordion>
</AccordionGroup>