> ## Documentation Index
> Fetch the complete documentation index at: https://doc.qbilon.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Merging in Qbilon

> Use the merging API to consolidate assets.

## Preface

In Qbilon, merging is one way to consolidate data. It automatically combines assets from two or more distinct data sources based on each asset's properties into one new asset. For example, this can be useful for bringing together information about the same physical asset from two different data sources, such as infrastructure information from a "hyperscaler" and license information from a license management system.

The `/apiv1/data/merge/{taskId}` endpoint enables programmatic merging of data in Qbilon. Currently, this endpoint is in the "beta stage," meaning you can use it, but the data format may change in the future.

> [!WARNING]
>
> Merging changes existing data (e.g., removing original assets and merging them into a new one) and cannot be undone. Use this feature with extreme caution, and thoroughly test your merge configurations in a testing environment before applying them to production data.

## Merging Concept

To better understand this endpoint, we will first explain how merging works from the user's perspective. Then, we will explain the data format that can be used with this endpoint to control how Qbilon merges the data.

**So how does merging work in Qbilon?**
Consider the case shown in the first figure below. You have loaded `Computer` assets from one data source and `License` assets from another. As you can see in the figure, both are currently not connected.

![Merging in Qbilon: Merging Concept](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/5181c03d-d16c-4769-8e90-ba532c9d43cf-screenshot-2026-09-01-155302.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=1bf8d8a731c877b1c8b1bfdfc3da92f7)

The JSON representation of both would resemble the following: This is shown to better illustrate the properties that will be used for merging later on:

```json theme={null}
{
  "types": {
    "Computer": {
      "nameAttribute": "Name",
      "elements": [
        {
          "externalId": "uniqueid-1",
          "properties": {
            "Name": "Computer 1",
            "OS": "Windows 11",
            "OS Product Key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX"
          }
        }
      ]
    },
    "License": {
      "nameAttribute": "Name",
      "elements": [
        {
          "externalId": "uniqueid-2",
          "properties": {
            "Name": "Windows 11 License",
            "License Key": "XXXXX-XXXXX-XXXXX-XXXXX-XXXXX",
            "Start Date": "2022-07-20T00:00:00",
            "End Date": "2027-07-20T00:00:00"
          }
        }
      ]
    }
  },
  ...
}
```

Now, your intention is to merge `Computer` where the `OS Product Key` used for OS activation is the same as the `License Key` in a `License` asset. To automatically merge these types, you can create a [Custom Merger](https://doc.qbilon.io/07-data-consolidation-writer/custom-merger.md) task in Qbilon like this:

![Merging in Qbilon: Merging Concept](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/4cc7d77c-9666-4b03-a016-5d738262c4c6-screenshot-2026-09-01-155603.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=53edbf6a299d63d78958c8ac7d950957)

For this merger task, you specified that Qbilon should merge all `Computer` and `Licenses` instances when the `OS Product Key` property value of a `Computer` matches the `License Key` property value of a `License`. If Qbilon finds a combination of assets that matches this merging condition, you also defined that the merged asset should have a new type, `Computer with License`, and that the `Name` property should be used for the display `Name`.

However, you knew that `Name` would probably be present in both assets, so there should be a rule clarifying which value should be used for the newly created asset. To accomplish this, you first created a "Default Merge Strategy" that specifies that, whenever there are conflicting properties, the newest value should be used. Qbilon keeps track of when each property was last written.
For the `Name` property, however, you want the special behavior where the name from the "Asset Management Tool" is used (if present), and then Qbilon falls back to the name from the "License Management Tool".

Fortunately, the existing data contains perfectly matching values for the `OS Product Key` and `License Key`. After running the merger task for the first time, the "Licensing" view and data schema will change as follows:

![Merging in Qbilon: Merging Concept](https://mintcdn.com/qbilon-docs/lr-P4KF_9wn8x9Vs/.gitbook/assets/bed52455-e607-4f11-8625-d19541917b14-screenshot-2026-09-01-160157.png?fit=max\&auto=format\&n=lr-P4KF_9wn8x9Vs\&q=85\&s=0c4aa6f0207ab035826080ab63aead3c)

![Merging in Qbilon: Merging Concept](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/9df2d228-98dc-458b-8c15-6ab3e020dab6-screenshot-2026-09-01-160259.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=1823664c4b3248835e51c4cc7b498238)

As you can see, Qbilon has merged the existing `Computer` and `License` assets into one new `Computer with License` asset, which contains all properties from both original assets. The `Name` property was successfully transferred from the asset originating from the "Asset Management Tool".

This is how merging works from the user's perspective. With the Merging API, you can now programmatically trigger the same behavior by sending the necessary merging information as JSON, rather than creating it manually in the UI.

To use the merge endpoint, two conditions must be met:

* A prepared data source (see the respective section in [Rest API](https://doc.qbilon.io/12-customizing-qbilon/rest-api/index)) in whose name merge requests are sent to Qbilon (this is the `{taskId}` part in the URL), and
* Compliance with the data format as defined in Qbilon's OpenAPI specification is also required (see `<your qbilon host>/openapi/index.html`).

## Data Format

The full version of the JSON format for a merging action, as described above, would look like this:

```json theme={null}
{
    "typeName1": "Computer",
    "typeName2": "License",
    "mergeConditions": {
        "booleanOperator": "and",
        "conditions": [
            {
                "attributeNameA": "OS Product Key",
                "attributeDatatypeA": "Text",
                "attributeNameB": "License Key",
                "attributeDatatypeB": "Text",
                "operator": "equal_to",
                "_conditionDiscriminator_": "simpledoubleattributenamecondition"
            }
        ]
    },
    "targetTypeName": "Computer with License",
    "nameAttributes": [
        {
            "priority": 0,
            "attributeName": "Name"
        }
    ],
    "defaultMergeStrategy": {
        "strategy": "newest",
        "_mergeStrategy_": "oldestNewestMergeStrategy"
    }
}
```

If this is sent within the body to the endpoint `POST apiv1/data/merge/-2` with valid credentials, then all instances of `Computer` will be merged with instances of `License` if the value of the respective `Computer`/`OS Product Key` property is equal to the value of the `License`/`License Key` property.

The following step-by-step walkthrough of the merging configuration will help you better understand each part and the expected merging result.

### Field "mergeConditions"

The `mergeConditions` field contains a list of comparison `conditions` and a `booleanOperator` that specifies how the conditions should be evaluated.

All comparing conditions in the `conditions` array must be in the following form:

```json theme={null}
{
    "conditions": [
        {
            "attributeNameA": "OS Product Key",
            "attributeDatatypeA": "Text",
            "attributeNameB": "License Key",
            "attributeDatatypeB": "Text",
            "operator": "equal_to",
            "_conditionDiscriminator_": "simpledoubleattributenamecondition"
        }
    ]
}
```

The `attr1`/`attr2` fields should refer to an existing attribute of the types being compared. If the attribute does not exist, the condition is evaluated as `false`. The datatype of each attribute must be one of those allowed in Qbilon: `Boolean`, `Text`, `Number` , `DateTime` or `List<Boolean|Text|Number|DateTime>`.

The allowed operators depend on the combination of datatypes of the attributes used for the comparison:

| | **Boolean** | **Number** | **Text** | **DateTime** | **List\<Boolean>** | **List\<Number>** | **List\<Text>** | **List\<DateTime>** |
| - | - | - | - | - | - | - | - | - |
| **Boolean** | • is equal to | – | – | – | • contained in | – | – | – |
| **Number** | – | • is equal to • is \< than • is \<= than • is > than • is >= than | – | – | – | • contained in | – | – |
| **Text** | – | – | • is equal to • contained in • contains | – | – | – | • contained in | – |
| **DateTime** | – | – | – | • is equal to • is \< than • is \<= than • is > than • is >= than | – | – | – | • contained in |
| **List\<Boolean>** | • contains | – | – | – | • is equal to • contains • contained in • intersects with | – | – | – |
| **List\<Number>** | – | • contains | – | – | – | • is equal to • contains • contained in • intersects with | – | – |
| **List\<Text>** | – | – | • contains | – | – | – | • is equal to • contains • contained in • intersects with | – |
| **List\<DateTime>** | – | – | – | • contains | – | – | – | • is equal to • contains • contained in • intersects with |

The last field `conditionDiscriminator` is mandatory and must be `simpledoubleattributecondition`. This may change in a later version of the data format.

### Field "targetTypeName"

The `targetTypeName` field defines the type of the merged assets. If the merger detects two assets that should be merged according to the `mergeConditions`, the `targetTypeName` is the type of the resulting asset. If a type with the given name already exists in Qbilon, only the asset is created, not a new type. If no such type exists, the merger first creates the type and then creates the asset.

### Field "nameAttributes"

The `nameAttributes` field specifies which attribute of the newly merged asset will be used as the asset's display name, i.e., which property will be used for the name in a diagram or table view.

The field expects a list of attribute names and their priorities. If the attribute with priority "0" is not present for either of the two merged assets, then the attribute with priority "1" will be used instead.

Although the list can be empty, it is recommended that you provide at least one attribute name in the following form:

```json theme={null}
[
    {
        "priority": 0,
        "attributeName": "Name"
    }
]
```

### Field "defaultMergeStrategy"

The field `defaultMergeStrategy` is used to define how Qbilon should handle properties that are present in both assets to be merged. For example, the property `Name` can be found in several asset types.

To specify which value Qbilon should use in such cases, you can provide a merge strategy that describes it. Currently, Qbilon supports three different merge strategies out of the box.

* Always take the newest value.
* Always take the oldest value.
* Take the value depending on where it comes from.

To use the `newest` strategy, set the `defaultMergeStrategy` to the following value:

```json theme={null}
 "defaultMergeStrategy": {
    "strategy": "newest",
    "_mergeStrategy_": "oldestNewestMergeStrategy"
}
```

To use the `oldest` strategy, set the `defaultMergeStrategy` to the following value:

```json theme={null}
 "defaultMergeStrategy": {
    "strategy": "oldest",
    "_mergeStrategy_": "oldestNewestMergeStrategy"
}
```

To use the `datasourceDependentMergeStrategy`, set the `defaultMergeStrategy` to the following value:

```json theme={null}
 "defaultMergeStrategy": {
    "type": null,
    "attributeName": "Name",
    "datasources": [
        "Datasource 1",
        "Datasource 2"
    ],
    "_mergeStrategy_": "datasourceDependentMergeStrategy"
}
```

## Merging Behavior in Practice

The following will cover several real-life cases and general topics that users of the Merge API may encounter. We will examine how the Merge API behaves in these cases to help you better understand the expected results of a custom linker.

### Difference "Merge API" vs. "Read/Write/Delete API"

Could the [read](https://doc.qbilon.io/12-customizing-qbilon/rest-api/reading-from-qbilon.md)/[write](https://doc.qbilon.io/12-customizing-qbilon/rest-api/writing-to-qbilon.md)/[delete](https://doc.qbilon.io/12-customizing-qbilon/rest-api/deleting-from-qbilon.md) API of Qbilon in a [custom task](https://doc.qbilon.io/12-customizing-qbilon/custom-tasks/index) be used to achieve the same? Generally, you can achieve a similar result by first reading the data from Qbilon, deleting assets and relations that should be removed, and finally writing back assets and relations that contain the merged information.

However, compared to using the Merge API, this implementation would have two major drawbacks:

* **Newly written data source replaces old data sources**. This means that an asset or relation, along with all its properties, may have originated from data source 1. However, if you manually enter the same data using your own custom task, the information that the data originally came from Data Source 1 will be lost. Instead, the assets will appear in Qbilon as if they were written by your custom task.
* **Updates from the original data sources will not be applied**. This means that if an asset was originally written by data source 1 and then merged with an asset from data source 2, it will receive updates from both data sources if the merge is done through the merge API. However, it will not receive those updates if the data is rewritten through a custom task.

### Repeated Run of Original Data Sources

After merging two assets into one, it is fed updates from two data sources. In the case of several consecutive merges, it is fed updates from even more data sources.

During the original merge, you can define the behavior for conflicting properties. However, this will not be applied during updates run by each data source. For example, if the update strategy for a write is set to `UPDATE_ALWAYS`, the newest value provided by that data source will be applied to the property values of the merged asset whenever that data source runs.

Note that, in rare cases, this could lead to a yo-yo effect, where the value of a property fluctuates between the two values provided by different data sources.

## Error Handling

Since the Merge API is in the alpha stage, most errors are not handled elaborately by Qbilon, but rather discarded as format violations. This behavior will evolve over time, and error handling will become more granular.

### Format Violations

| Title | Description | Expected Behavior |
| - | - | - |
| Non-existent operator | Providing an `operator` value that is not part of the predefined list above. | Returns a `422 - Unprocessable Entity` error. |
| Empty attribute name in condition | Sending a blank value for `name` in `attr1` or `attr2` in the `mergeConditions` field. | Returns a `422 - Unprocessable Entity` error. |

### Inconsistent Input

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| Mismatching operator | If the `operator` value doesn't match the datatypes of the two attributes in a condition (e.g., using `is < than` for two text attributes), Qbilon ignores the condition. | Condition is ignored; returns 20`4 - No Content.` |
| Non-existent attribute | If an attribute in a condition does not exist, Qbilon logs a warning internally but still returns 204. This can happen when querying multiple types, where some may not contain the given attribute. | Logs warning internally; returns 20`4 - No Content.` |
| Mismatching datatype | If the datatype of a provided attribute in `mergeConditions` does not match the actual attribute's datatype (e.g., expected Text, provided Number), Qbilon discards the condition. | Discards condition; returns 20`4 - No Content.` |
| Non-existent type | If a type in `typeName1` or `typeName2` does not exist in Qbilon, it is discarded. | Type is discarded; returns 20`4 - No Content.` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.