In `OpenStreetMap, relations <http://wiki.openstreetmap.org/wiki/Relation>`_ define logical or geographic relationships between other nodes, ways and relations.
The most common relation type is a multipolygon, but all other relations can be imported as well.
Multipolygons
-------------
`Multipolygon relations <http://wiki.openstreetmap.org/wiki/Relation:multipolygon>`_ are used to represent complex polygon geometries. They are also the only way to represent holes in polygons.
Multipolygon relations are automatically handled by Imposm for all ``polygon`` tables.
The following mapping::
tables:
buildings:
type: polygon
mapping:
building: [__any__]
Inserts closed ways if they have a ``building`` tag::
The roles are ignored by Imposm as not all holes are correctly tagged as ``inner``. Imposm uses geometry operations to verify if a member of a multipolygon is a hole, or if it is a separate polygon.
For compatibility, multipolygon relations without tags will use the tags from the (longest) outer way. Imposm will insert the following relation as well::
OpenStreetMap also uses relations to map more complex features. Some examples:
-`Administrative areas <http://wiki.openstreetmap.org/wiki/Relation:boundary>`_ with boundaries, capitals and label positions.
-`Bus/tram/train routes <http://wiki.openstreetmap.org/wiki/Relation:route>`_ with the route itself, stops and platforms.
-`3D buildings <http://wiki.openstreetmap.org/wiki/Simple_3D_buildings>`_ with multiple parts that should not be computed as holes.
These relations can not be mapped to `simple` linestrings or polygons as they can contain a mix of different geometry types, or would result in invalid geometries (overlapping polygons).
The Imposm table types ``relation`` and ``relation_member`` allow you to import all relevant data for these relations.
``relation_member``
^^^^^^^^^^^^^^^^^^^
The ``relation_member`` table type inserts each member of the relation as a separate row. The ``relation_member`` has access to the `role` and `type` value of each member. You can also import tags from the relation `and` from the member node, way or relation.
The ``relation`` table type inserts the mapped element regardless of the resulting geometry. For example, this allows you to create a table with the metadata (name, reference, operator, etc.) of all available route relations. The actual geometries need to be `joined` form the members.
Example
~~~~~~~
The following mapping imports the bus route relation from above::
routes:
type: relation
columns:
- name: osm_id
type: id
- key: ref
name: ref
type: string
- name: network
key: network
type: string
mapping:
route: [bus]
This will create a single row with the mapped columns.
..note::``relation`` tables do not support geometry columns. Use the geometries of the members, or use a ``polygon`` table if your relations contain multipolygons.