<!-- review: finished -->

<a id="stream-map"></a>

# Map

Creates variables whose values depend on values of other variables.

<a id="configuration-example-62"></a>

## Configuration Example

```nginx
map $remote_addr $limit {
    127.0.0.1    "";
    default      $binary_remote_addr;
}

limit_conn_zone $limit zone=addr:10m;
limit_conn addr 1;
```

<a id="directives-71"></a>

## Directives

<a id="index-0"></a>

<a id="s-map"></a>

### map

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map` string $variable { ... };   |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | —                                 |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

Creates a new variable.
Its value depends on the first parameter, specified as a string with variables,
for example:

```nginx
set $var1 "foo";
set $var2 "bar";

map $var1$var2 $new_variable {
    default "foobar_value";
}
```

Here, the variable `$new_variable` will have a value
composed of the two variables `$var1` and `$var2`,
or a default value if these variables are not defined.

#### NOTE
Since variables are evaluated only when they are used, the mere declaration even of a large number of "map" variables does not add any extra costs to request processing.

Parameters inside the `map` block specify a mapping between source and resulting values.

Source values are specified as strings or regular expressions.

Strings are matched ignoring the case.

A regular expression should either start with a `~` symbol for a case-sensitive matching, or with the `~*` symbols for case-insensitive matching. A regular expression can contain named and positional captures that can later be used in other directives along with the resulting variable.

If a source value matches one of the names of special parameters described below, it should be prefixed with the `\` symbol.

The resulting value can contain text, variable and their combination.

The following special parameters are also supported:

| `default` value   | sets the resulting value if the source value matches none of the specified variants. When default is not specified, the default resulting value will be an empty string.   |
|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `hostnames`       | indicates that source values can be hostnames with a prefix or suffix mask. This parameter should be specified before the list of values.                                  |

For example,

```nginx
*.example.com 1;
example.*     1;
```

The following two records

```nginx
example.com   1;
*.example.com 1;
```

can be combined:

```nginx
.example.com  1;
```

| `include` file   | includes a file with values. There can be several inclusions.   |
|------------------|-----------------------------------------------------------------|
| `volatile`       | indicates that the variable is not cacheable.                   |

If the source value matches more than one of the specified variants, e.g. both a mask and a regular expression match, the first matching variant will be chosen, in the following order of priority:

1. String value without a mask
2. Longest string value with a prefix mask, e.g. `*.example.com`
3. Longest string value with a suffix mask, e.g. `mail.*`
4. First matching regular expression (in order of appearance in a configuration file)
5. Default value (`default`)

<a id="index-1"></a>

<a id="s-map-hash-bucket-size"></a>

### map_hash_bucket_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_bucket_size` size;      |
|------------------------------------------------------------------------------------------|-----------------------------------|
| Default                                                                                  | `map_hash_bucket_size 32|64|128;` |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                            |

Sets the bucket size for the [map](#s-map) variables hash tables. Default value depends on the processor's cache line size. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).

<a id="index-2"></a>

<a id="s-map-hash-max-size"></a>

### map_hash_max_size

| [Syntax](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)   | `map_hash_max_size` size;   |
|------------------------------------------------------------------------------------------|-----------------------------|
| Default                                                                                  | `map_hash_max_size 2048;`   |
| [Context](https://en.angie.software//angie/docs/configuration/configfile.md#configfile)  | stream                      |

Sets the maximum size of the [map](#s-map) variables hash tables. The details of setting up hash tables are provided [separately](https://en.angie.software//angie/docs/configuration/configfile.md#configure-hashes).