= The map Statement

.Syntax
[source,unlang]
----
map <module-name> "string" {
	<server-attribute> <op> <field>
}
----

The `map` section is one of the most useful new additions to version
4.  It allows for the mapping of arbitrary information from a database
to attributes inside of the server.

The map syntax is similar for all use-cases.  It consists of:

<module-name>:: The name of the module which implements this particular map

"string":: A module-specific query string.  This string is usually a
database query which returns one or more fields.

<server-attribute>:: The server attribute which is assigned the value
taken from the database query.

<op>:: The operator such as `=`, `:=`, etc. Any
xref:unlang/update.adoc#_editing_operators[editing operator] defined for an
xref:unlang/update.adoc[update] statement is permissible.

<field>:: The name of the field from the database. For SQL, the field names are
usually column names.  For LDAP, the field names are usually LDAP attributes.
+
The _<field>_ value should generally be enclosed in single quotes which
prevents any additional expansion of the value. When the right hand side is
instead a double-quoted string, that string is expanded dynamically.  The
resulting value is then taken as the field name.

If the `map` fails for any reason, then all of the results are
discarded, and the `map` does not affect any server attributes.  For
example, the database query can return no results, or a dynamically
expanded _<field>_ can refer to a non-existent field name.  In both
cases, the `map` statement returns `fail`, and no server attributes
are affected.

.Examples

[source,unlang]
----
map sql "SELECT column1, column2, column3 from table WHERE user=%{User-Name}" {
    &reply.Framed-IP-Address := 'column1'
    &reply.Filter-Id := 'column2'
    &reply.Reply-Message := 'column3'
}
----

// Copyright (C) 2021 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
// This documentation was developed by Network RADIUS SAS.
