# MVTEncode (/docs/reference/sql/aggregate-functions/mvtencode)



This page describes the RawTree engine binary used to generate this reference. It does not define Query API support. Descriptions retain upstream ClickHouse terminology. See [SQL interface scope](/docs/reference/clickhouse-compatibility#service-interfaces).

Encodes a group of features into a binary [Mapbox Vector Tile](https://github.com/mapbox/vector-tile-spec) layer.

This is the aggregate counterpart of the scalar function `MVTEncodeGeom`. Each input row becomes one feature. The
geometry argument is a `Geometry` of tile-space coordinates, typically produced by `MVTEncodeGeom`; the optional
properties argument is a named tuple whose element names become the feature attribute keys and whose element types
determine the vector tile value types. Point, line and polygon geometry are supported.

The properties tuple must have explicit element names. Column aliases inside `tuple(...)` are not propagated to tuple
element names, so name the elements with a cast, for example `tuple(count(), any(id))::Tuple(cluster_count UInt64, id String)`.

Identical property values are interned into the layer's shared value pool, so the emitted tile does not duplicate them.
If `feature_id_name` is given, the named unsigned-integer property element is emitted as the MVT Feature `id` (a `uint64`)
and excluded from the tags; a `NULL` id is omitted for that feature.
The result is the raw bytes of a single-layer tile, which can be returned directly over the HTTP interface with
`FORMAT RawBLOB`. This function is the analogue of PostGIS `ST_AsMVT`.

**Syntax**

```sql
MVTEncode(layer_name[, extent[, feature_id_name[, stringify_unsupported]]])(geometry[, properties])
```

**Parameters**

* `layer_name` — Name of the vector tile layer. [`String`](/reference/data-types/string)
* `extent` — Tile extent in pixels per side. Defaults to `4096`. [`UInt32`](/reference/data-types/int-uint)
* `feature_id_name` — Optional name of an unsigned-integer element of the properties tuple to emit as the Feature `id` instead of as a tag. Parameters are positional, so `extent` must also be given to use it. [`String`](/reference/data-types/string)
* `stringify_unsupported` — Optional flag (`0`/`1`, default `0`); when `1`, property types not directly supported (e.g. big integers, `UUID`, `Decimal`) are encoded as their text `string_value` instead of raising an error. [`UInt8`](/reference/data-types/int-uint)

**Arguments**

* `geometry` — Tile-space geometry, e.g. from `MVTEncodeGeom`. [`Geometry`](/reference/data-types/geo)
* `properties` — Optional named tuple of feature attributes. Element names become attribute keys. [`Tuple`](/reference/data-types/tuple)

**Returned value**

Returns the binary contents of a single-layer Mapbox Vector Tile. [`String`](/reference/data-types/string)

**Examples**

**Encode a clustered tile of points**

```sql title=Query
SELECT MVTEncode('points')(geom, tuple(cluster_count)::Tuple(cluster_count UInt64)) AS tile
FROM
(
    SELECT MVTEncodeGeom((lon, lat)::Point, 10, 550, 335) AS geom, count() AS cluster_count
    FROM points
    GROUP BY geom
)
SETTINGS allow_suspicious_types_in_group_by = 1;
```

*Introduced in version 26.7.0.*
