# Stream IoT Data to Infuse-DB

> Move device telemetry into a queryable data store.

Use this guide to design the bridge between Infuse-IoT Cloud device workflows and Infuse-DB ingestion.

Infuse-IoT Cloud is the device communication and operational context layer. Infuse-DB is the scalable time-series data layer for live and historical device records. A production pipeline usually has a backend service or gateway between them.

## Integration Shape

<mermaid :config="config" :toolbar="{"title":"IoT telemetry to Infuse-DB"}" code="---%0Atoolbar%3A%0A%20%20title%3A%20IoT%20telemetry%20to%20Infuse-DB%0A---%0AsequenceDiagram%0A%20%20%20%20participant%20Device%20as%20IoT%20device%0A%20%20%20%20participant%20IoT%20as%20Infuse-IoT%20Cloud%0A%20%20%20%20participant%20Worker%20as%20Your%20ingestion%20service%0A%20%20%20%20participant%20DB%20as%20Infuse-DB%0A%0A%20%20%20%20Device-%3E%3EIoT%3A%20Sends%20state%2C%20route%2C%20KV%2C%20logger%2C%20or%20telemetry%20context%0A%20%20%20%20Worker-%3E%3EIoT%3A%20Reads%20device%20identity%2C%20state%2C%20definitions%2C%20and%20route%20context%0A%20%20%20%20Worker-%3E%3EWorker%3A%20Decodes%20and%20validates%20records%0A%20%20%20%20Worker-%3E%3EDB%3A%20Writes%20queryable%20device%20data%0A%20%20%20%20Worker-%3E%3EIoT%3A%20Optionally%20queues%20KV%20updates%20or%20RPC%20commands">



</mermaid>

## 1. Provision The Device

Register and provision the device in Infuse-IoT Cloud first. The device record gives your pipeline stable identifiers such as `deviceId`, `mcuId`, board, organisation, and metadata.

See [Connect an IoT Device](/guides/iot/connect-a-device) for the full onboarding sequence.

## 2. Define The Target Dataset

Create or select the Infuse-DB dataset that should hold the device records. The dataset should include the Infuse `deviceId` and any dimensions you need for querying, such as customer, environment, location, asset group, organisation, board, deployment site, firmware version, or measurement type.

See [Datasets](/docs/infuse-db/datasets) and [Ingestion](/docs/infuse-db/ingestion).

## 3. Read IoT Context

Before writing records, your ingestion service can read Infuse-IoT Cloud context:

<table>
<thead>
  <tr>
    <th>
      Context
    </th>
    
    <th>
      Endpoint
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Device record
    </td>
    
    <td>
      <code>
        GET /device/deviceId/{deviceId}
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Device state
    </td>
    
    <td>
      <code>
        GET /device/deviceId/{deviceId}/state
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Last route
    </td>
    
    <td>
      <code>
        GET /device/deviceId/{deviceId}/lastRoute
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      Logger state
    </td>
    
    <td>
      <code>
        GET /device/deviceId/{deviceId}/loggerStates
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      KV entries
    </td>
    
    <td>
      <code>
        GET /device/deviceId/{deviceId}/kv/entries
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      TDF definitions
    </td>
    
    <td>
      <code>
        GET /defs/tdf
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      KV definitions
    </td>
    
    <td>
      <code>
        GET /defs/kv
      </code>
    </td>
  </tr>
</tbody>
</table>

Use definitions to decode structured payloads consistently. Store the definition version with ingested records when you need reproducible decoding later.

## 4. Write Records To Infuse-DB

Your ingestion service should validate device identity, decode payloads, normalize timestamps, and write raw or computed records into Infuse-DB. Keep the raw device identifier and decoded fields together so later queries can join operational data back to the device registry.

Recommended record fields include:

<table>
<thead>
  <tr>
    <th>
      Field
    </th>
    
    <th>
      Why it helps
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        deviceId
      </code>
    </td>
    
    <td>
      Joins records to Infuse-IoT Cloud and Infuse-Marketplace workflows.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        organisationId
      </code>
    </td>
    
    <td>
      Preserves account ownership.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        boardId
      </code>
    </td>
    
    <td>
      Supports hardware-family queries.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        customer
      </code>
    </td>
    
    <td>
      Supports customer-scoped fleet queries.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        environment
      </code>
    </td>
    
    <td>
      Separates production, test, staging, or field-trial data.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        location
      </code>
    </td>
    
    <td>
      Supports site, region, or installation queries.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        assetGroup
      </code>
    </td>
    
    <td>
      Groups devices by physical asset, product line, or operational unit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        observedAt
      </code>
    </td>
    
    <td>
      Captures the device or gateway timestamp.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ingestedAt
      </code>
    </td>
    
    <td>
      Captures when the backend wrote the record.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        definitionVersion
      </code>
    </td>
    
    <td>
      Makes decoding traceable.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        payload
      </code>
    </td>
    
    <td>
      Stores raw or computed measurement, event, signal, or status data.
    </td>
  </tr>
</tbody>
</table>

## 5. Use IoT Feedback Loops

After data is ingested, your backend can use Infuse-IoT Cloud to act on device state:

- queue a KV update when configuration needs to change,
- send an RPC when an operator or automation requests action,
- inspect logger state before downloading more logged data,
- read last route before sending downlink work.

For endpoint schemas, see the [Infuse-IoT Cloud API reference](/api-reference/iot) and [Infuse-DB docs](/docs/infuse-db).