All Products
Search

This Product

    ApsaraMQ for MQTT:Topic aliases

    Document Center

    ApsaraMQ for MQTT:Topic aliases

    Last Updated:Mar 11, 2026

    Message Queuing Telemetry Transport (MQTT) 5.0 topic aliases replace full topic names with two-byte integers in PUBLISH packets. A topic name like factory/building-3/floor-2/line-7/station-42/sensor/temperature takes 63 bytes per message. A topic alias takes 2 bytes. For connections that publish frequently to the same topics, this reduces per-message overhead and saves bandwidth.

    How topic aliases work

    A topic alias is a two-byte integer that maps to a topic name within a single connection. The mapping is created when a sender includes both a topic name and a Topic Alias in a PUBLISH packet. After that, the sender can publish to the same topic by specifying only the Topic Alias -- the receiver looks up the corresponding topic name from its local mapping table.

    Create a mapping

    In the first PUBLISH packet, include both the full topic name and the Topic Alias:

    Topic Name: factory/building-3/floor-2/line-7/station-42/sensor/temperature
Topic Alias: 1
Payload: 22.5

    The receiver stores the mapping: Topic Alias 1 maps to factory/building-3/floor-2/line-7/station-42/sensor/temperature.

    Use an existing mapping

    In subsequent PUBLISH packets, omit the topic name and send only the Topic Alias:

    Topic Alias: 1
Payload: 23.1

    The receiver resolves Topic Alias 1 to the previously mapped topic name.

    Topic Alias Maximum negotiation

    The client and server independently declare how many topic aliases each is willing to receive. This negotiation happens during connection setup:

    1. The client sets Topic Alias Maximum in its CONNECT packet. This value defines the maximum Topic Alias that the server can use when sending PUBLISH packets to the client.

    2. The server sets Topic Alias Maximum in its CONNACK packet. This value defines the maximum Topic Alias that the client can use when sending PUBLISH packets to the server.

    ApsaraMQ for MQTT supports up to 30 topic aliases in each direction per connection.

    Limits

    LimitValueBehavior when exceeded
    Server-side Topic Alias Maximum30 per connectionThe server closes the connection and reports a topic name error
    Client-declared Topic Alias MaximumUp to 30 per connectionIf the client declares more than 30, the server ignores topic aliases when pushing messages to the client
    UniquenessOne topic per alias at a timeEach Topic Alias maps to exactly one topic name within a connection
    ScopeCurrent connection onlyAll mappings are discarded on disconnect. A new connection starts with no mappings

    Usage rules

    • Topic Alias value cannot be 0. A value of 0 is invalid in PUBLISH packets.

    • Stay within the negotiated maximum. The Topic Alias value in a client-to-server PUBLISH packet must not exceed the Topic Alias Maximum from the server's CONNACK packet. If the server's CONNACK returns a Topic Alias Maximum greater than 0, the client must accept all topic aliases up to that value.

    • Client and server mappings are independent. Topic Alias 1 sent by the client and Topic Alias 1 sent by the server can map to different topics. Each side maintains its own mapping table.

    When to use topic aliases

    Topic aliases are most effective when the topic name is large relative to the payload. The following are common Internet of Things (IoT) and messaging scenarios where topic aliases provide the most benefit.

    High-frequency telemetry -- Sensors that report data every few seconds to deeply nested topics (for example, site/region/building/floor/zone/device-id/metric/type) send the full topic name once and use a 2-byte alias for all subsequent messages. This is useful in systems such as stock market tracking and IoT data collection where a large number of messages are sent every second.

    Bandwidth-constrained devices -- On metered cellular or satellite connections, replacing a 60- to 100-byte topic name with a 2-byte integer in every message reduces cumulative data transfer.

    Battery-powered devices -- Less data per message means fewer radio transmission cycles, which extends battery life for remote monitoring stations and mobile devices.

    Embedded devices with limited memory -- Short integer aliases are faster to process and consume less memory than full UTF-8 topic names on each message.

    Example: bandwidth savings in practice

    A temperature sensor publishes readings every second to home/groundfloor/livingroom/temperature (39 bytes). Without topic aliases, every PUBLISH packet carries these 39 bytes. With a topic alias, only the first packet carries the full name.

    First PUBLISH packet (creates the mapping):

    Topic Name: home/groundfloor/livingroom/temperature
Topic Alias: 1
Payload: 22°C

    All subsequent PUBLISH packets (use the mapping):

    Topic Alias: 1
Payload: 23°C

    Over 1,000 messages, this saves approximately 38 KB of topic name overhead (39 bytes x 999 messages).

    Key takeaways

    • Topic aliases substitute full UTF-8 topic names with a two-byte integer.

    • Mappings are scoped to a single connection and must be rebuilt after reconnecting.

    • Client and server negotiate Topic Alias Maximum independently during connection setup (CONNECT and CONNACK).

    • ApsaraMQ for MQTT supports up to 30 topic aliases per connection in each direction.

    • The topic alias feature optimizes message transmission across various IoT and real-time communication scenarios.