All Products
Search

This Product

    ApsaraMQ for MQTT:Manage topics

    Document Center

    ApsaraMQ for MQTT:Manage topics

    Last Updated:Jul 09, 2026

    Message Queuing Telemetry Transport (MQTT) is a messaging protocol that is based on the publish-subscribe (pub/sub) model. In MQTT, each message belongs to a topic. MQTT supports multiple levels of topics. A level 1 topic is a parent topic. Before you use ApsaraMQ for MQTT, you must create a parent topic in the ApsaraMQ for MQTT console.

    Usage notes

    • Topics cannot be used across instances. For example, you cannot use the endpoint of Instance B to subscribe to a topic that is created on Instance A.

    • Subtopics do not need to be manually created in the ApsaraMQ for MQTT console. You only need to declare a subtopic in your client code, and the subtopic is automatically created and takes effect (auto-creation). Parent topics must be created in advance in the console or by calling an API. For more information about parent topics and subtopics, see Terms.

    • You can create up to 100 wildcard subscriptions for each parent topic. For more information, see Client limits.

    • Topic and Group are managed independently. Group is used for device group identification and access control, while Topic is the message channel. You do not need to associate a Group when you create a Topic.

    • If you use the same instance for both testing and production environments, configure separate parent topics, Group IDs, and Client IDs to achieve logical isolation. Do not mix resources from different environments when you send or subscribe to messages. Otherwise, messages may interfere with each other, clients may be forcibly disconnected, or clients may receive incorrect messages.

    Create a topic

    1. Log on to the ApsaraMQ for MQTT console. In the left-side navigation pane, click Instances.

    2. In the top navigation bar, select the region where the instance that you want to manage resides. On the Instances page, click the instance name to go to the Instance Details page.

    3. In the left-side navigation pane, click Topics. In the upper-left corner of the Topics page, click Create Topic.
    4. In the Create Topic panel, set the Name and Description parameters for the topic and click OK in the lower-left corner.

    Delete a topic

    Warning After a topic is deleted, the producers stop sending messages to the topic and the consumers stop consuming messages from the topic. The metadata and messages in the topic are deleted and cannot be restored. Therefore, exercise caution when you delete a topic.
    1. Go to the Topics page.
    2. In the topic list, find the topic that you want to delete. In the Actions column, choose More > Delete.
    3. In the dialog box that appears, click OK.

    Update the description of a topic

    1. Go to the Topics page.
    2. In the topic list, find the topic that you want to update and click the topic name.
    3. In the Basic Information section of the Topic Details page, click Edit next to Description. Modify the description of the topic in the field and click OK.

    Query the details of a topic

    1. Go to the Topics page.
    2. In the topic list, find the topic that you want to query. Click the topic name to go to the Topic Details page.

    FAQ

    Q: How do I restrict traffic from entering ApsaraMQ for MQTT?

    ApsaraMQ for MQTT does not provide direct traffic restriction rules. To block traffic in an emergency, you can use the following methods:

    1. Delete the AccessKey (AK) that is used to generate the username and password. If the AK is also used by other products, do not delete it.

    2. Delete the corresponding Topic or Group resource. Note that data cannot be recovered after deletion.

    Q: What should I do if some messages cannot be received when I use the + wildcard to subscribe to multiple subtopics?

    This issue is usually related to the client subscription count limit or the subscription ACK mechanism. Follow these troubleshooting steps:

    1. Check whether the number of subscription relationships on the client exceeds the limit. A maximum of 100 wildcard subscription relationships are allowed per parent topic.

    2. Verify that the client correctly handles subscription ACKs. If subscriptions are not acknowledged, the backend subscription status may become abnormal, causing some messages to be lost.

    3. If the issue persists after you adjust the subscription count, submit a ticket and provide the Client ID and specific Topic information for further investigation.

    References