> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.
# MQTT extractor
> Learn how to use the Cognite MQTT extractor to bring MQTT data into Cognite Data Fusion (CDF), including Quality of Service (QoS), broker persistence, and verifying delivery with hosted extractor job metrics.
## Before you start
* Assign [access capabilities](/cdf/access/guides/capabilities#cognite-mqtt-extractor) to *create* a hosted MQTT extractor and for the extractor to *write* data points, time series, events, RAW rows, and instances in data models in the target CDF project.
You can use OpenID Connect and your existing identity provider (IdP) framework to manage access to CDF data securely. For more information, see [setup and administration for extractors](/cdf/integration/guides/extraction/admin_oidc).
## Deploy the extractor
Navigate to Data fusion > Integrate > Extractors.
Locate the **Cognite MQTT extractor** and select **Set up extractor**.
## Message delivery and reliability
Before you define message formats and mappings, review how data reaches CDF. Reliable delivery depends on your **publishers**, your **broker**, and the **Cognite MQTT extractor**, not on the extractor alone. The extractor subscribes to topics at **Quality of Service level 1**, which provides at-least-once delivery, and requests persistent sessions from the broker.
For reliable message delivery during brief disconnections, your broker must persist messages for disconnected clients and retain session state. When the extractor reconnects, the broker can deliver unacknowledged messages. The broker applies the **lower** of the publisher's QoS and the extractor's subscription QoS. **QoS 0** publishes reach the extractor at QoS 0 only, even though the extractor subscribes at **QoS 1**.
Configure your publishers to use **QoS 1** when sending messages, or **QoS 2** if your broker supports it. On your broker, turn on session persistence and offline message buffering according to your vendor's documentation.
To verify that data reaches CDF, use the job metrics in [Hosted extractors overview](/cdf/integration/guides/extraction/hosted_extractors).
The Cognite MQTT extractor does not guarantee zero message loss if network interruptions coincide with Cognite-hosted service restarts.
If the broker shows traffic but CDF does not update, work through the checks below.
**Symptoms:** The broker or your publisher logs show traffic, but time series, events, or other CDF resources do not update.
**Checks:**
1. Confirm publisher **QoS**, broker persistence, and sessions as described earlier in this section.
2. In the [Hosted extractors overview](/cdf/integration/guides/extraction/hosted_extractors), open the job and compare **Source messages** with **Destination uploaded values** and related metrics to see whether failures happen at transform or write steps.
3. If you use an **extraction pipeline** to track ingestion, see [Monitor extraction pipelines](/cdf/integration/guides/interfaces/monitor_integrations#understanding-status-and-uptime) for how to interpret **Topic filters status** and uptime, and troubleshoot failed integrations. The same article explains troubleshooting for on-premises and hosted extractors.
## Message formats
MQTT is a generic message transport protocol agnostic to the message payloads, which can be in any format. The Cognite MQTT extractor supports several [pre-defined message formats](/cdf/integration/guides/extraction/hosted_extractors/hosted_extractors_mappings). If you want to define your own custom mapping of MQTT messages, see [custom data formats for hosted extractors](/cdf/integration/guides/extraction/hosted_extractors/hosted_extractors_custom_mappings).
Custom formats used with MQTT jobs will receive an `input` argument containing the message as JSON, and a `context` argument containing the topic, for example:
```
{
"topic": "company/location3/machine/pressure"
}
```
The topic given in the context will be the *actual* topic the message arrived on, not the topic filter, so it can be used to distinguish identical messages arriving on different topics.
Messages are published on *topics*. A topic can be any string of text, but usually it's a hierarchical structure, separated by forward slashes, for example:
```
company/location3/machine1/pressure
```
Clients can subscribe to messages by subscribing to *topic filters*. A topic filter can be a topic written verbatim, but it also allows for wildcards such that one subscription can yield data from multiple topics. MQTT supports single-level and multi-level wildcards.
`+` denotes a single-level wildcard and matches any text between two slashes. For example, if you have several topics like these:
```
company/location3/machine1/pressure
company/location3/machine2/pressure
company/location3/machine3/pressure
```
You can subscribe to all of them by subscribing to this topic filter:
```
company/location3/+/pressure
```
`#` denotes a multi-level wildcard and matches any text. It has to be used at the end of the topic filter. For example, if you have several topics like the following:
```
company/location3/machine1/pressure
company/location3/machine2/pressure
company/location3/machine1/temperature
```
You can subscribe to all of them by subscribing to this topic filter:
```
company/location3#
```
## Encryption
The Cognite MQTT extractor supports connecting to MQTT brokers with Transport Layer Security (TLS) encryption. Select **Enable Transport Layer Security (TLS) on the connection** when you set up the connection to the broker.
Upload the root certificate to the Cognite MQTT extractor when you're creating the connection if your broker uses a custom Certificate Authority (CA) to create and sign the certificate used for encryption. The extractor supports PEM and DER formats.
**Certificate version**
The Cognite MQTT extractor only supports X.509 certificates of version 3. Earlier versions will not work with the extractor.