# hawkBit Entity Definitions and RSQL Filtering Guide

This document describes the entities available in hawkBit and how to filter and sort them using RSQL queries through the MCP tools.

## RSQL Query Syntax

RSQL (RESTful Service Query Language) is a query language for filtering and searching entities. It uses a simple, URL-friendly syntax.

### Comparison Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `==` | Equal to | `name==MyTarget` |
| `!=` | Not equal to | `status!=ERROR` |
| `=lt=` or `<` | Less than | `createdAt=lt=1609459200000` |
| `=le=` or `<=` | Less than or equal | `weight=le=500` |
| `=gt=` or `>` | Greater than | `lastTargetQuery=gt=1609459200000` |
| `=ge=` or `>=` | Greater than or equal | `id=ge=100` |
| `=in=` | In list | `status=in=(RUNNING,FINISHED)` |
| `=out=` | Not in list | `updateStatus=out=(ERROR,UNKNOWN)` |

### Logical Operators

| Operator | Description | Example |
|----------|-------------|---------|
| `;` or `and` | Logical AND | `name==Test*;status==RUNNING` |
| `,` or `or` | Logical OR | `status==ERROR,status==CANCELED` |

Always use "and" or "or" for operators when grouping conditions - since this is the human-readable format.

### Wildcard Support

Use `*` as a wildcard character for pattern matching:
- `name==Device*` - Names starting with "Device"
- `name==*Controller` - Names ending with "Controller"
- `name==*test*` - Names containing "test"

### Sub-Entity Filtering

Access nested entity fields using dot notation:
- `assignedDistributionSet.name==MyDS`
- `target.controllerId==device123`
- `type.key==os`

### Map/Metadata Filtering

For metadata and attributes, use dot notation with the key:
- `metadata.environment==production`
- `controllerAttributes.revision==1.5`

---

## Entity Definitions

### Target

Targets represent devices or software instances that can receive software updates.

**Filterable/Sortable Fields:**

| Field                              | Description                                                          | Type |
|------------------------------------|----------------------------------------------------------------------|------|
| `controllerId`                     | Unique identifier of the target                                      | String |
| `name`                             | Display name                                                         | String |
| `description`                      | Description text                                                     | String |
| `updateStatus`                     | Current update status (UNKNOWN, IN_SYNC, PENDING, ERROR, REGISTERED) | Enum |
| `address`                          | IP address or URI                                                    | String |
| `lastTargetQuery`                  | Last time the target polled (timestamp in ms)                        | Long |
| `createdAt`                        | Creation timestamp                                                   | Long |
| `createdBy`                        | Creator username                                                     | String |
| `lastModifiedAt`                   | Last modification timestamp                                          | Long |
| `lastModifiedBy`                   | Last modifier username                                               | String |
| `assignedDistributionSet.name`     | Name of assigned distribution set                                    | String |
| `assignedDistributionSet.version`  | Version of assigned distribution set                                 | String |
| `installedDistributionSet.name`    | Name of installed distribution set                                   | String |
| `installedDistributionSet.version` | Version of installed distribution set                                | String |
| `targetType.key`                   | Target type key                                                      | String |
| `targetType.name`                  | Target type name                                                     | String |
| `tags.name`                        | Tag name                                                             | String |
| `group`                            | Group name                                                           | String |
| `metadata.<key>`                   | Metadata value by key                                                | String |
| `controllerAttributes.<key>`       | Controller attribute by key                                          | String |

**Example Queries:**
```
# Find targets with update errors
updateStatus==ERROR

# Find targets by name pattern
name==device-*

# Find targets with specific distribution set assigned
assignedDistributionSet.name==Firmware;assignedDistributionSet.version==2.0.0

# Find targets that haven't polled in 24 hours (timestamp example)
lastTargetQuery=lt=1704067200000

# Find targets by tag
tags.name==production

# Find targets by metadata
metadata.location==factory-A

# Find targets by controller attribute
controllerAttributes.firmware_version==1.2.3
```

---

### Distribution Set

Distribution Sets are collections of software modules that can be deployed to targets.

**Filterable/Sortable Fields:**

| Field | Description | Type |
|-------|-------------|------|
| `id` | Unique identifier | Long |
| `name` | Distribution set name | String |
| `version` | Version string | String |
| `description` | Description text | String |
| `type.key` | Distribution set type key | String |
| `type.name` | Distribution set type name | String |
| `valid` | Whether the DS is valid for deployment | Boolean |
| `createdAt` | Creation timestamp | Long |
| `createdBy` | Creator username | String |
| `lastModifiedAt` | Last modification timestamp | Long |
| `lastModifiedBy` | Last modifier username | String |
| `tags.name` | Tag name | String |
| `modules.name` | Software module name | String |
| `metadata.<key>` | Metadata value by key | String |

**Example Queries:**
```
# Find distribution sets by name
name==Firmware*

# Find valid distribution sets only
valid==true

# Find by type
type.key==os_app

# Find by tag
tags.name==release-candidate

# Find distribution sets containing a specific module
modules.name==bootloader
```

---

### Rollout

Rollouts are used to deploy software to groups of targets in a controlled manner.

**Filterable/Sortable Fields:**

| Field | Description | Type |
|-------|-------------|------|
| `id` | Unique identifier | Long |
| `name` | Rollout name | String |
| `description` | Description text | String |
| `status` | Rollout status (CREATING, READY, PAUSED, STARTING, RUNNING, FINISHED, etc.) | Enum |
| `distributionSet.id` | Distribution set ID | Long |
| `distributionSet.name` | Distribution set name | String |
| `distributionSet.version` | Distribution set version | String |
| `distributionSet.type` | Distribution set type | String |
| `createdAt` | Creation timestamp | Long |
| `createdBy` | Creator username | String |
| `lastModifiedAt` | Last modification timestamp | Long |
| `lastModifiedBy` | Last modifier username | String |

**Example Queries:**
```
# Find running rollouts
status==RUNNING

# Find rollouts by name
name==Campaign*

# Find rollouts for a specific distribution set
distributionSet.name==Firmware;distributionSet.version==2.0.0

# Find finished or paused rollouts
status=in=(FINISHED,PAUSED)
```

---

### Action

Actions represent deployment operations assigned to targets.

**Filterable/Sortable Fields:**

| Field | Description | Type |
|-------|-------------|------|
| `id` | Unique identifier | Long |
| `status` | Action status (SCHEDULED, RUNNING, FINISHED, ERROR, CANCELED, etc.) | Enum |
| `active` | Whether the action is currently active | Boolean |
| `weight` | Priority weight (0-1000) | Integer |
| `lastActionStatusCode` | Last status code reported | Integer |
| `externalRef` | External reference string | String |
| `target.controllerId` | Target controller ID | String |
| `target.name` | Target name | String |
| `target.updateStatus` | Target update status | Enum |
| `distributionSet.id` | Distribution set ID | Long |
| `distributionSet.name` | Distribution set name | String |
| `distributionSet.version` | Distribution set version | String |
| `rollout.id` | Rollout ID | Long |
| `rollout.name` | Rollout name | String |
| `rolloutGroup.id` | Rollout group ID | Long |
| `rolloutGroup.name` | Rollout group name | String |
| `createdAt` | Creation timestamp | Long |
| `createdBy` | Creator username | String |
| `lastModifiedAt` | Last modification timestamp | Long |
| `lastModifiedBy` | Last modifier username | String |

**Example Queries:**
```
# Find active actions
active==true

# Find actions by status
status==RUNNING

# Find failed actions
status==ERROR

# Find actions for a specific target
target.controllerId==device-001

# Find actions for a specific rollout
rollout.name==Campaign2024

# Find high-priority actions
weight=gt=800

# Find actions with specific status code
lastActionStatusCode==200
```

---

### Software Module

Software Modules are individual software components that make up distribution sets.

**Filterable/Sortable Fields:**

| Field | Description | Type |
|-------|-------------|------|
| `id` | Unique identifier | Long |
| `name` | Module name | String |
| `version` | Version string | String |
| `description` | Description text | String |
| `type.key` | Software module type key | String |
| `type.name` | Software module type name | String |
| `createdAt` | Creation timestamp | Long |
| `createdBy` | Creator username | String |
| `lastModifiedAt` | Last modification timestamp | Long |
| `lastModifiedBy` | Last modifier username | String |
| `metadata.<key>` | Metadata value by key | String |

**Example Queries:**
```
# Find modules by name
name==bootloader*

# Find modules by type
type.key==os

# Find modules by version
version==2.0.*

# Find modules with specific metadata
metadata.checksum==abc123
```

---

### Target Filter Query

Target Filter Queries define RSQL filters for grouping targets, used for rollouts and auto-assignment.

**Filterable/Sortable Fields:**

| Field | Description | Type |
|-------|-------------|------|
| `id` | Unique identifier | Long |
| `name` | Filter name | String |
| `autoAssignDistributionSet.name` | Auto-assign DS name | String |
| `autoAssignDistributionSet.version` | Auto-assign DS version | String |
| `createdAt` | Creation timestamp | Long |
| `createdBy` | Creator username | String |
| `lastModifiedAt` | Last modification timestamp | Long |
| `lastModifiedBy` | Last modifier username | String |

**Example Queries:**
```
# Find filters by name
name==Production*

# Find filters with auto-assignment configured
autoAssignDistributionSet.name==*

# Find filters for a specific auto-assign distribution set
autoAssignDistributionSet.name==Firmware;autoAssignDistributionSet.version==2.0.0
```

---

## Common Query Patterns

### Combining Multiple Conditions (AND)
```
status==RUNNING;createdAt=gt=1704067200000
```

### Alternative Conditions (OR)
```
status==ERROR,status==CANCELED
```

### Complex Queries with Grouping
```
(status==RUNNING,status==SCHEDULED);target.updateStatus!=ERROR
```

### Timestamp Filtering
Timestamps are in milliseconds since Unix epoch:
```
# Created after January 1, 2024
createdAt=gt=1704067200000

# Modified in the last 24 hours (example timestamp)
lastModifiedAt=gt=1704153600000
```

### Wildcard Patterns
```
# Starts with
name==prefix*

# Ends with
name==*suffix

# Contains
name==*substring*
```