Map directive for variable mapping in Nginx - Step-by-Step Execution

Process Flow - Map directive for variable mapping

Start

↓

Define map block

↓

Input variable checked

↓

Match input value to map keys

↓

If match found

→Assign mapped value to new variable

↓

If no match

→Assign default value

↓

Use mapped variable in config

↓

End

The map directive checks an input variable, matches it against keys, assigns a mapped value or default, then uses that mapped variable in configuration.

Execution Sample

Nginx

map $http_user_agent $is_mobile {
    default 0;
    ~*Mobile 1;
}

server {
    if ($is_mobile) { return 302 /mobile; }
}

This code maps user agents containing 'Mobile' to 1, others to 0, then redirects mobile users.

Process Table

Step	Input $http_user_agent	Map Match	Mapped $is_mobile	Action
1	"Mozilla/5.0 (Mobile)"	Matches ~*Mobile	1	Redirect to /mobile
2	"Mozilla/5.0 (Windows NT)"	No match, use default	0	No redirect, serve normally
3	"SomeOtherAgent"	No match, use default	0	No redirect, serve normally

💡 All requests processed; mapping assigns 1 for mobile user agents, 0 otherwise.

Status Tracker

Variable	Start	After 1	After 2	After 3
$http_user_agent	N/A	"Mozilla/5.0 (Mobile)"	"Mozilla/5.0 (Windows NT)"	"SomeOtherAgent"
$is_mobile	N/A	1	0	0

Key Moments - 2 Insights

Why does $is_mobile become 0 for some user agents?

Because the map directive uses 'default 0;' for any input that does not match the regex ~*Mobile, as shown in execution_table rows 2 and 3.

How does the map directive decide which value to assign?

It checks the input variable against each key in order; if a regex or exact match is found, it assigns that value; otherwise, it assigns the default value, as seen in the concept_flow and execution_table.

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of $is_mobile at step 2?

A 0

B Undefined

C 1

D Mobile

💡 Hint

Check the 'Mapped $is_mobile' column at step 2 in the execution_table.

At which step does the input match the regex ~*Mobile?

A Step 3

B Step 2

C Step 1

D None

💡 Hint

Look at the 'Map Match' column in the execution_table.

If the default value in the map was changed to 2, what would $is_mobile be at step 3?

A 0

B 2

C 1

D Undefined

💡 Hint

Refer to the 'Map Match' and 'Mapped $is_mobile' logic in the execution_table and variable_tracker.

Concept Snapshot

map directive syntax:
map $input_var $output_var {
  default value;
  key1 value1;
  ~regex value2;
}

It maps input variable values to output variable values.
If no key matches, default is used.
Useful for conditional config based on variables.

Full Transcript

The nginx map directive lets you create a new variable based on the value of an existing variable. You define a map block with keys and values. When nginx processes a request, it checks the input variable against the keys. If it finds a match, it assigns the corresponding value to the new variable. If no match is found, it assigns the default value. This is useful to simplify conditional logic in your configuration. For example, mapping user agents containing 'Mobile' to 1 and others to 0, then redirecting mobile users. The execution table shows how different user agents are mapped and what actions follow. The variable tracker shows how variables change per request. Understanding the map directive helps you write cleaner, more efficient nginx configs.