> ## 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.

# Reading from Qbilon

> Build read queries with projections, conditions, pagination, and sorting.

## Preface

Qbilon provides a read API, which allows for sophisticated filtering of domain data that shall be retrieved.

The read API can query data from Qbilon using (potentially) complex conditional logic. For this purpose, the data endpoint `/apiv1/data` allows `POST` requests to be received.

## Query Format

The Qbilon Read API supports complex queries of the domain data stored in your Qbilon instance. It uses a versatile query format in JSON that can be included in the body of a POST request to read data from Qbilon. The body consists of several optional parts and some mandatory basic parts. This allows a user to request exactly as much information as they need.

### Full-Fledged Query Format

A full-fledged example of the format for a complex query retrieving assets and relations from the backend could look like this:

```json theme={null}
{
  "types": [
    {
      "names": ["Azure Resource Group"],
      "attributeNames": [
        "Name",
        "ID",
        "Provisioning State"
      ],
      "condition": {
        "conditionType": "nested",
        "operator": "and",
        "condition": [
          {
            "conditionType": "atomic",
            "attributeName": "Provisioning State",
            "operator": "matches",
            "value": "[a-zA-Z]+"
          },
          {
            "conditionType": "relation",
            "relationFullName": "contains [A -> B]",
            "count": 5,
            "operator": "greater_than_or_equal"
          }
        ]
      }
    }
  ],
  "relations": [
    {
      "names": ["has attached [A -> B]"],
      "attributeNames": [
        "Name",
        "ID",
        "Provisioning State"
      ],
      "condition": {
        "conditionType": "atomic",
        "attributeName": "Name",
        "operator": "contains",
        "value": "12"
      }
    }
  ]
}
```

In the following we will go through all parts of this request. There are additional examples at the end of this page that illustrate what can be done with the API.

### Types and Relations

The body of the query is divided into two parts, i.e., `types` and `relations`. This allows you to retrieve them separately or in combination, e.g., if you only provide the `types` part then the result will also only contain types but no relations. Vice versa, if you skip the `types` part and only put the `relations` part into the request body, the API will return only the requested relations, but no types. Each part is designed as an array of query objects so that you can query multiple types/relations with one request.

**Examples**

```json theme={null}
{
  "types": [
    {
      "names": ["Azure Resource Group"],
      "attributeNames": [
        "ID",
        "Name",
        "Provisioning State",
        "Costs Last Month",
        "Current Month Costs",
        "First Seen",
        "Last Seen"
      ]
    }
  ]
}
```

This request retrieves all matching Azure Resource Group assets with the explicitly listed properties. It does not query all types in the instance. The following abbreviated response illustrates the response structure; actual types and values depend on the data in your instance.

```json theme={null}
{
  "types": {
    "Azure Resource Group": {
      "nameAttribute": "Name",
      "elements": [
        {
          "properties": {
            "ID": "example-external-id",
            "Name": "example-resource-group",
            "Provisioning State": "Succeeded"
          },
          "qbilonId": "5"
        }
      ]
    }
  },
  "relations": {}
}
```

All returned types will be found under the `types` field. Within the `elements` field there will be all assets of that type with all their properties. There is some additional information provided, i.e., the property that is used as a name for instances of that type (in this case `Name` with the value `example-resource-group` ) as well as the `qbilonId` for this asset, which is a globally unique ID within Qbilon for this asset.

To retrieve relations, the process is very similar. If you want to retrieve all relations of a certain type, the request would look like this:

```json theme={null}
{
  "relations": [
    {
      "names": ["contains [Azure Resource Group -> Azure Virtual Machine]"],
      "attributeNames": ["ID", "Name", "First Seen", "Last Seen"]
    }
  ]
}
```

The result you would get from the API would have a similar structure:

```json theme={null}
{
    "types": {},
    "relations": {
        "contains [Azure Resource Group -> Azure Virtual Machine]": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "properties": {
                        "ID": "WH3pfqikn78containstonzshgo5P0",
                        "First Seen": "2025-04-04T14:08:58",
                        "Last Seen": "2025-04-04T14:08:58",
                        "Name": "contains"
                    },
                    "qbilonId": "-3",
                    "sourceQbilonId": "8",
                    "targetQbilonId": "9"
                }
                ...
            ]
        }
        ...
    }
}
```

In addition to the `qbilonId` for relations, you will also receive the `sourceQbilonID` and `targetQbilonId`, which are the unique IDs of the source and target assets from and to which this relation goes.

### The 'names' Limiter

Both, types and relations, can have an optional `names` field which lets you restrict the type of assets/relations you want to retrieve from Qbilon.

**Examples**
If you only want to retrieve all assets of type `Azure Resource Group` instead of all assets, you can simply change your request from before to:

```json theme={null}
{
  "types": [
    {
      "names":["Azure Resource Group"]
    }
  ]
}
```

This will give you a response that contains only one type in the `types` field, i.e. `Azure Resource Group` with all its assets in the `elements` field, like this:

```json theme={null}
 {
  "types": {
      "Azure Resource Group": {
          "nameAttribute": "Name",
          "elements": [
              {
                  "properties": {
                      "Provisioning State": "Succeeded",
                      "Costs Last Month": 1203.84,
                      "Current Month Costs": 722.3,
                      "ID": "2zCP1-JoxT0",
                      "First Seen": "2025-04-04T14:08:58",
                      "Last Seen": "2025-04-04T14:08:58",
                      "Name": "azrg-datasync"
                  },
                  "qbilonId": "5"
              },
              {
                  "properties": {
                      "Provisioning State": "Succeeded",
                      "Costs Last Month": 396.45,
                      "Current Month Costs": 17.57,
                      "ID": "2AxdYKJBuOs",
                      "First Seen": "2025-04-04T14:08:58",
                      "Last Seen": "2025-04-04T14:08:58",
                      "Name": "azrg-playground"
                  },
                  "qbilonId": "2"
              },
              ...
          ]
      }
  },
  "relations": {}
}
```

The same logic applies to relations. For them, you will have to provide the full name, e.g., if there is a relation between `Azure Region` and `Azure Resource Group` that is called `contains`, then you would have to provide the full relation name in the form `contains [Azure Region -> Azure Resource Group]` as shown in the following example:

```json theme={null}
{
  "relations": [
    {
      "names":["contains [Azure Region -> Azure Resource Group]"]
    }
  ]
}
```

This query will only return relations of the type `contains [Azure Region -> Azure Resource Group]`, like this:

```json theme={null}
{
    "types": {},
    "relations": {
        "contains [Azure Region -> Azure Resource Group]": {
            "nameAttribute": "Name",
            "elements": [
                {
                    "properties": {
                        "ID": "8yV-QDz23cscontainsWH3pfqikn78",
                        "First Seen": "2025-04-04T14:08:58",
                        "Last Seen": "2025-04-04T14:08:58",
                        "Name": "contains"
                    },
                    "qbilonId": "-3",
                    "sourceQbilonId": "32",
                    "targetQbilonId": "8"
                },
                {
                    "properties": {
                        "ID": "8yV-QDz23cscontainsBna1xvFO-W0",
                        "First Seen": "2025-04-04T14:08:58",
                        "Last Seen": "2025-04-04T14:08:58",
                        "Name": "contains"
                    },
                    "qbilonId": "-4",
                    "sourceQbilonId": "32",
                    "targetQbilonId": "47"
                },
                ...
            ]
        }
    }
}
```

### The 'attributeNames' Limiter

Sometimes you are not interested in the plethora of properties that Qbilon stores for each asset or relation and therefore want to limit what the API returns in this regard. To limit the properties returned to those that are useful to you, you can use the `attributeNames` limiter.

**Examples**
If you want the `Azure Resource Group` example above to be reduced to just the `Name` and `ID` properties, you can achieve this by modifying your request as follows:

```json theme={null}
{
  "types": [
    {
      "names":["Azure Resource Group"],
      "attributeNames":["ID", "Name"]
    }
  ]
}
```

The result of this query will only provide you with the requested assets and properties, as shown below:

```json theme={null}
{
  "types": {
      "Azure Resource Group": {
          "nameAttribute": "Name",
          "elements": [
              {
                  "properties": {
                      "ID": "2zCP1-JoxT0",
                      "Name": "azrg-datasync"
                  },
                  "qbilonId": "5"
              },
              ...
            ]
        }
    },
  "relations": {}
}
```

The attributes used in the `attributeNames` limiter can be freely chosen and do not have any cross-reactions with the attributes you used in your conditions.

> [!NOTE]
>
> The fields `nameAttribute` and `qbilonId` are not properties of an asset, so they are always returned.

All of the above mentioned works in the same way for relations and their properties.

### Atomic Conditions

This condition can express simple conditions, such as `number Of Cores <= 8`, where `number Of Cores` is a numeric property in Qbilon.

Parameters are:

* `conditionType` indicates that the condition is an atomic condition.
* `attributeName` is the name of the property to evaluate in this condition.
* `operator` is used during the evaluation and must fit the data type of the property.
* `value` is the value to compare against.

**Example**

```json theme={null}
{
  "conditionType": "atomic",
  "attributeName": "number Of Cores",
  "operator": "less_than_or_equal",
  "value": 8
}
```

### Relation Conditions

This condition is only applicable to assets and is used to express a relational condition, for instance `devices with number of "monitored_by" edges > 10` or `nodes with number of incoming and outgoing edges > 10`. Please note that the actual number of relations found is not included in the result.

Parameters are:

* `conditionType` indicates that the condition is a relational condition.
* `operator` is used during the evaluation and must be an equality or numeric operator.
* `count` determines the number of distinct relations that each asset instance must satisfy (only **positive integers** or **zero** are allowed).
* **Either** ...
  * `direction`: one of `incoming`, `outgoing`, `both` indicating the direction of relations to consider (only allowed if no `relationFullName` is specified)

**or ...**

* `relationFullName`: name of relations to consider for counting. This must be syntactically correct `simpleName [sourceType → targetType]` (only allowed if no `direction` is specified).

**Examples**
... with `relationFullName`:

```json theme={null}
{
  "conditionType": "relation",
  "operator": "greater_than",
  "count": 10,
  "relationFullName": "monitored by [Device -> PRTG Device]"
}
```

... with `direction`:

```json theme={null}
{
  "conditionType": "relation",
  "operator": "greater_than",
  "count": 10,
  "direction": "both"
}
```

**Reflexive relations with relation condition**
A "reflexive relation" or "loop" is a relation that connects an asset to itself, forming a self-loop.

When using the Read API in Qbilon, you may encounter cases that initially seem counter-intuitive. Therefore, let's take a closer look at these cases and explore why the results are as they are.

First, let's create an example data model to see what it would look like in Qbilon. Send the following data model to Qbilon (e.g., via its [Write API](https://doc.qbilon.io/12-customizing-qbilon/rest-api/writing-to-qbilon.md)):

```json theme={null}
{
  "types": {
    "Computer": {
      "nameAttribute": "Name",
      "elements": [
        {
          "externalId": "1",
          "properties": {
            "Name": "Computer 1"
          }
        }
      ]
    },
    "Application": {
      "nameAttribute": "Name",
      "elements": [
        {
          "externalId": "2",
          "properties": {
            "Name": "Application 1"
          }
        }
      ]
    }
  },
  "relations": {
    "runs on [Application -> Server]": {
      "nameAttribute": "Name",
      "elements":[
        {
          "externalId": "21",
          "properties": {
            "Name": "runs on"
          },
          "sourceExternalId": "2",
          "targetExternalId": "1"
        }
      ]
    },
    "talks with itself [Application -> Application]": {
      "nameAttribute": "Name",
      "elements":[
        {
          "externalId": "22",
          "properties": {
            "Name": "talks with itself"
          },
          "sourceExternalId": "2",
          "targetExternalId": "2"
        }
      ]
    }
  }
}
```

In the data schema, this data would be shown as two asset types ("Application" and "Computer") together with two relation types "talks with itself" and "runs on":

![Reading from Qbilon: Relation Conditions](https://mintcdn.com/qbilon-docs/aJQhbcvq7mtvhV0w/.gitbook/assets/53811871-39dd-4f3b-ab0e-b3c8d4155b83-screenshot-2026-10-15-150137.png?fit=max\&auto=format\&n=aJQhbcvq7mtvhV0w\&q=85\&s=604b8cb1f75a007570e287006b9324fc)

A diagram showing the actual instance da could look like this:

![Reading from Qbilon: Relation Conditions](https://mintcdn.com/qbilon-docs/Jmla3tEw4FRYjkNT/.gitbook/assets/58f42314-1cec-405e-9a7c-2d21a7d0227f-screenshot-2026-10-15-150116.png?fit=max\&auto=format\&n=Jmla3tEw4FRYjkNT\&q=85\&s=10302f0cf1d2116ca8f6111f0dc080f1)

Now, let's review the different relationship conditions that we might request from Qbilon, as well as the expected results.

**Assets with one incoming relation**
First, we want to retrieve all assets with exactly **one incoming** relation. To do so, we would use the following request:

```json theme={null}
{
  "types": [
    {
      "attributeNames": ["Name"],
      "condition":{
        "conditionType": "relation",
        "operator": "equal_to",
        "count": 1,
        "direction": "incoming"
      }
    }
  ]
}
```

We will receive the following response:

```json theme={null}
{
  "types": {
    "Computer": {
      "nameAttribute": "Name",
      "elements": [
        {
          "properties": {
            "Name": "Computer 1"
          },
          "qbilonId": "58"
        }
      ]
    },
    "Application": {
      "nameAttribute": "Name",
      "elements": [
        {
          "properties": {
            "Name": "Application 1"
          },
          "qbilonId": "11"
        }
      ]
    }
  },
  "relations": {}
}
```

**Explanation**: Qbilon rightfully returned both assets because they have exactly one incoming relation. `Application 1` has an incoming `talks with itself` relation, and `Computer 1` has an incoming `runs on` relation.

**Assets with one outgoing relation**
Now, we want to retrieve all assets that have exactly **one** **outgoing** relation. To do so, we will modify our request slightly to include the following:

```json theme={null}
{
  "types": [
    {
      "attributeNames": ["Name"],
      "condition":{
        "conditionType": "relation",
        "operator": "equal_to",
        "count": 1,
        "direction": "outgoing"
      }
    }
  ]
}
```

We will receive the following response:

```json theme={null}
{
  "types": {},
  "relations": {}
}
```

**Explanation**: Qbilon rightfully returned no assets because both assets have more or less than one outgoing relation. `Application 1` has two outgoing relations: the `talks with itself` relation and the `runs on` relation. `Computer 1` has no outgoing relations.

**Assets with two relations**
Now, we want to retrieve all assets with **exactly two** relations. It does not matter if they are incoming or outgoing. To do so, we will modify our request to include the following:

```json theme={null}
{
  "types": [
    {
      "attributeNames": ["Name"],
      "condition":{
        "conditionType": "relation",
        "operator": "equal_to",
        "count": 2,
        "direction": "both"
      }
    }
  ]
}
```

We will receive the following response:

```json theme={null}
{
  "types": {
    "Application": {
      "nameAttribute": "Name",
      "elements": [
        {
          "properties": {
            "Name": "Application 1"
          },
          "qbilonId": "11"
        }
      ]
    }
  },
  "relations": {}
}
```

**Explanation**: You might ask why `Application 1` is now regarded as an asset with two incoming and two outgoing relations, when its `talks with itself` relation was previously considered in the incoming and outgoing relations query as one relation each. Qbilon counts relations by their unique ID, which is why, in the case of `both`, it is counted only once. Therefore, Qbilon returns only `Application 1`, which has two relations: the `talks with itself` relation and the outgoing `runs on` relation. `Computer 1` has only one incoming relation.

### Nested Conditions

This condition is used to nest other conditions using a logical operator. This allows for the creation of complex conditions, e.g. `numberCores >= 8 || number of incoming&outgoing edges < 10`. The nesting depth is not limited.

Parameters are:

* `conditionType` indicates that the condition is a nested condition.
* `operator` is either `and` or `or` indicating that either all or only one of the given conditions must be met.
* `condition` is a list of conditions which have to be satisfied depending on the logical operator given (`and`/`or`). Nested conditions can contain any type of conditions which can again be nested themselves.

**Example**

```json theme={null}
{
  "conditionType": "nested",
  "operator": "and",
  "condition": [ <other conditions> ]
}
```

### System Conditions

There are currently two additional condition types that cover cases where not a property or relation is being filtered, but system properties of assets and relations, such as the assets' properties `qbilonId` and `datasources` (describing the origin of asset data).

**QbilonIdCondition**
This condition is used to check for Qbilon IDs, i.e., only assets are returned that have an ID contained in the provided list. The IDs are "Base64"-encoded. An error is thrown if any string in the list is not a valid Base64-encoded long integer. The list of IDs cannot hold duplicates. If an ID is not found, it is ignored.

Parameters are:

* `conditionType` indicates that the condition is a `QbilonIdCondition`.
* `ids` List of strings must hold unique, **Base64-encoded** long integer values.

**Example**

```json theme={null}
{
  "conditionType": "qbilonid",
  "ids": ["2", "3"]
}
```

**DataSourceNameCondition**
This condition is used to check for data source names as each asset has a list of data sources that contribute information to it.

This list does always contain the `System` data source as basis. The `Manual` data source only occurs when a user manually creates from scratch or modifies an asset, an asset's property or the property values.

Parameters are:

* `conditionType` indicates that the condition is a `DataSourceNameCondition`.
* `values` Set of string holds the names of data sources to check for, if an asset holds any of the listed data sources, it is considered relevant for the result

**Example**

```json theme={null}
{
  "conditionType": "datasources",
  "values": ["Azure", "CSV Connector"];
}
```

### Condition Operators

Condition operators are used to evaluate atomic or relation conditions. They process two values, i.e. the value of the property/relation count (hereafter called `pval`) and the condition `value` (hereafter called `cval`). As a result, they return `true` or `false`.

#### Nesting limitation

Although in theory nesting can be infinite for the following operators in reality Qbilon only allows filter to a nesting depth of 2 levels.

#### Datatype-Specific and -Unspecific Operators

There are two categories of operators, i.e., **datatype-specific** and **-unspecific** ones, where *equality* and *existence* are datatype-unspecific and the rest are datatype-specific ones. That means that *equality* and *existence* operators can be used with properties of all datatypes, whereas the others only can be used with properties of their specific datatype, e.g., *numeric* only with numbers or *temporal* only with datetimes.

#### Equality

* `equal_to`: True if `pval` and `cval` are equal.
  * Example: an asset has the property `Name` with value `Germany`. When the following condition is processed on this asset, it will return `true`.
  ```json theme={null}
  "condition": {
      "conditionType": "atomic",
      "attributeName": "Name",
      "operator": "equal_to",
      "value": "Germany"
  }
  ```
* `not_equal_to`: True if `pval` and `cval` are not equal.
  * Example: an asset has the property `Name` with value `Germany.` When the following condition is processed on this asset, it will return `true` (as "Germany" != "France").
  ```json theme={null}
  "condition": {
      "conditionType": "atomic",
      "attributeName": "Name",
      "operator": "not_equal_to",
      "value": "France"
  }
  ```

#### Existence

* `exist`:
  * True, if `pval` exists and `cval` is true.
    Example: an asset has the property `Name` with any value. When the following condition is processed on this asset, it will return `true`.
  ```json theme={null}
  "condition": {
      "conditionType": "atomic",
      "attributeName": "Name",
      "operator": "exist",
      "value": true
  }
  ```
* False, if `pval` exists and `cval` is false.
  Example: an asset has the property `Name` with any value. When the following condition is processed on this asset, it will return `false`.
  ```json theme={null}
  "condition": {
      "conditionType": "atomic",
      "attributeName": "Name",
      "operator": "exist",
      "value": false
  }
  ```
* True, if `pval` does not exist and `cval` is false.
  Example: an asset does **not** have the property `Name`. When the following condition is processed on this asset, it will return `true`.
  ```json theme={null}
  "condition": {
      "conditionType": "atomic",
      "attributeName": "Name",
      "operator": "exist",
      "value": false
  }
  ```
* False, if `pval` does not exist and `cval` is true.
  Example: an asset does **not** have the property `Name`. When the following condition is processed on this asset, it will return `false`.
  ```json theme={null}
  "condition": {
      "conditionType": "atomic",
      "attributeName": "Name",
      "operator": "exist",
      "value": true
  }
  ```

#### Numeric

* `less_than`: True if `pval` is smaller than `cval`.

Example: an asset has a property `Age` with the value `25` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Age",
    "operator": "less_than",
    "value": 30
}
```

* `greater_than`: True if `pval` is greater than `cval`.

Example: an asset has a property `Age` with the value `25` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Age",
    "operator": "greater_than",
    "value": 20
}
```

* `less_than_or_equal`: True if `pval` is smaller than `cval` or equal to it.

Example: an asset has a property `Age` with the value `25` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Age",
    "operator": "less_than_or_equal",
    "value": 25
}
```

* `greater_than_or_equal`: True if `pval` is greater than `cval` or equal to it.

Example: an asset has a property `Age` with the value `25` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Age",
    "operator": "greater_than_or_equal",
    "value": 25
}
```

#### String

* `contains`: True if `pval` contains `cval` as substring. Be aware that this operator is case sensitive!

Example: an asset has a property `Name` with the value `Germany` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Name",
    "operator": "contains",
    "value": "Ger"
}
```

* `contains_not`: True if `pval` does not contain `cval` as substring. Be aware that this operator is case sensitive!

Example: an asset has a property `Name` with the value `Germany` . When the following condition is processed for this asset, it will return `false`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Name",
    "operator": "contains_not",
    "value": "Ger"
}
```

* `matches`: True if `pval` matches the valid regex pattern `cval` (see [this website](https://regex101.com/) for information on regular expressions).

Example: an asset has a property `Name` with the value `Germany` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Name",
    "operator": "matches",
    "value": "\\w"
}
```

* `matches_not`: True if `pval` does not match the valid regex pattern `cval` (see [this website](https://regex101.com/) for information on regular expressions).

Example: an asset has a property `Name` with the value `Germany` . When the following condition is processed for this asset, it will return `false`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Name",
    "operator": "matches_not",
    "value": "\\w"
}
```

#### List

* `contains_element`: True if `pval` is a list and contains an asset `cval`. This only works for lists with text values.

Example: an asset has a property `Names` with the value `[Germany, France]` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Names",
    "operator": "contains_element",
    "value": "France"
}
```

* `contains_not_element`: True, if `pval` is a list and does not contain a string `cval`. This only works for lists with text values.

Example: an asset has a property `Names` with the value `[Germany, France]` . When the following condition is processed for this asset, it will return `false`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Names",
    "operator": "contains_not_element",
    "value": "France"
}
```

* `contains_element_with`: True if `pval` is a list and contains an asset containing substring `cval`.

Example: an asset has a property `Names` with the value `[Germany, France]` . When the following condition is processed for this asset, it will return `true`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Names",
    "operator": "contains_element_with",
    "value": "Fra"
}
```

* `contains_element_not_with`: True, if `pval` is a list and does not contain a string containing a substring `cval`.

Example: an asset has a property `Names` with the value `[Germany, France]` . When the following condition is processed for this asset, it will return `false`.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Names",
    "operator": "contains_element_not_with",
    "value": "Fra"
}
```

#### Temporal

> [!NOTE]
>
> Remember that **all** times in Qbilon are in UTC, so they might differ from your local time depending where you are currently located.

Temporal Conditions in Qbilon utilize the [ISO-8601 specification for date time ranges](https://en.wikipedia.org/wiki/ISO_8601#Durations). The input string is interpreted as such a specification and calculates a comparison date and time to evaluate if an asset is relevant for the result.
There are two different possibilities to filter with temporal conditions:

* filtering for a relative period (relative to now), e.g,. 5 days in the past from now
* filtering for something that is before or after a specific point in time, e.g., something before 2025-10-10 00:00:00

**Filtering for relative periods**
➥ **Operators**

* `within`: True if `pval` is a datetime and is within the period stated by `cval`. For the period format see "Format" subsection below.
* `not_within`: True if `pval` is a datetime and is **not** within the period stated by `cval`. For the period format see "Format" subsection below.

➥ **Format**
`cval` must be given in the following format or there will be an error message:

* Starting with `P` or `-P` indicating a time **p**eriod in the future or past
* `<integer>Y` = amount of years
* `<integer>M` = amount of months
* `<integer>W` = amount of weeks
* `<integer>D` = amount of days
* `T` indicating the **t**ime part of the period
* `<integer>H` = amount of hours
* `<integer>M`= amount of minutes
* `<integer>S` = amount of seconds
  `P` / `-P` and `T` are both mandatory whereas all other parts are optional.

➥ **Format Examples**
All of the following examples assume that there is an asset that has a property `Last Seen` with the value `2025-04-09T12:30:22` and **now** equals `2025-04-10T12:30:22`

* When the following condition is processed for this asset, it will return `true` , as `pval` lies within the period of 2 years, 3 weeks, 3 hours, 1 minute and 9 seconds in the past relative to **now**.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "within",
    "value": "-P2Y3WT3H1M09S"
}
```

* When the following condition is processed for this asset, it will return `true` , as `pval` does not lie within the period of 1 hours in the past relative to **now**.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "not_within",
    "value": "-PT1H"
}
```

* When the following condition is processed for this asset, it will return `true` , as `pval` lies within the period of 1 day in the past relative to **now** (first we go 2 days in the past and by negating the hours part in the period we add 24 hours again, resulting in 1 day)

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "within",
    "value": "-P2DT-24H"
}
```

* When the following condition is processed for this asset, it will return `false` , as pval does not lie within the period of 10 days and 10 seconds in the future relative to **now**.

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "within",
    "value": "P10DT10S"
}
```

**Filtering for before/after a fixed point in time**
➥ **Operators**

* `before`: True if `pval` is a datetime and is before `cval`. For the time format see "Format" subsection below.
* `after`: True if `pval` is a datetime and is after `cval`. For the time format see "Format" subsection below.

➥ **Format**
`cval` must be given in the following format or the condition will be ignored: `YYYY-MM-DDTHH:MM:SS`.

➥ **Examples**
All of the following examples assume that there is an asset that has a property `Last Seen` with the value `2025-04-09T12:30:22`.

* When the following condition is processed for this asset, it will return `true` , as `pval` lies before `cval` .

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "before",
    "value": "2025-04-10T12:30:22"
}
```

* When the following condition is processed for this asset, it will return `false` , as `pval` does not lie before `cval` .

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "before",
    "value": "2025-04-08T12:30:22"
}
```

* When the following condition is processed for this asset, it will return `true` , as `pval` lies after `cval` .

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "after",
    "value": "2025-04-08T12:30:22"
}
```

* When the following condition is processed for this asset, it will return `false` , as `pval` does not lie after`cval` .

```json theme={null}
"condition": {
    "conditionType": "atomic",
    "attributeName": "Last Seen",
    "operator": "after",
    "value": "2025-04-10T12:30:22"
}
```

### Pagination and Sorting

From version **3.16** onwards, the Qbilon Read API supports pagination and sorting. These options allow you to retrieve a limited number of assets or relations at a time and control their order.
The optional fields `limit`, `offset` and `orderBy` are part of each query object within the `types` or `relations` array. They are included in the JSON body of the `POST /apiv1/data` request, not as URL parameters.

#### The 'limit' and 'offset' Limiters

* `limit` is the maximum number of matching elements to return. Only **positive integers** are allowed. If omitted, no explicit limit is applied.
* `offset` is the number of matching elements to skip before returning results. Only **positive integers** or **zero** are allowed. If omitted, no elements are skipped.
  Conditions are evaluated before pagination. If fewer elements remain than the requested `limit`, the API returns only those elements.

**Example**
To retrieve the first 100 assets of type `Azure Resource Group`, use:

```json theme={null}
{
  "types": [
    {
      "names": ["Azure Resource Group"],
      "attributeNames": ["ID", "Name", "Provisioning State"],
      "limit": 100,
      "offset": 0
    }
  ]
}
```

For the next page, send the same request with `"offset": 100`. For the third page, use `"offset": 200`, and so on. Keep the `names`, `attributeNames`, conditions and sorting unchanged between requests.
The response has the same structure as a query without pagination. The returned assets are found under `types` → `Azure Resource Group` → `elements`. There is no separate page number or total-count field.

> [!NOTE]
>
> Without an explicit `orderBy`, elements are ordered by their internal element ID.

#### Sorting with 'orderBy'

The optional `orderBy` field specifies the properties by which the result is sorted. It is an object whose keys are property names and whose values specify the sorting direction:

* `asc` sorts in ascending order.
* `desc` sorts in descending order.
  Numeric properties are sorted numerically, and date-time properties are sorted chronologically. Elements without a value for the sorting property are placed last. The internal element ID is used as a final tie-breaker.

> [!WARNING]
>
> Please note
> Every property used in `orderBy` must also be included in `attributeNames`. Otherwise, the query is invalid. The direction values must be written in lower case: `asc` or `desc`.

**Example**
To retrieve the first 100 Azure Resource Group assets sorted by `Name` in ascending order:

```json theme={null}
{
  "types": [
    {
      "names": ["Azure Resource Group"],
      "attributeNames": ["ID", "Name", "Provisioning State"],
      "orderBy": {
        "Name": "asc"
      },
      "limit": 100,
      "offset": 0
    }
  ]
}
```

To reverse the sorting direction, replace `"asc"` with `"desc"`.

#### Pagination and Sorting for Relations

The same options work for relations. Provide the full relation name in `names`, as in other relation queries.

**Example**

```json theme={null}
{
  "relations": [
    {
      "names": ["contains [Azure Resource Group -> Azure Virtual Machine]"],
      "attributeNames": ["Name", "First Seen", "Last Seen"],
      "orderBy": {
        "Last Seen": "desc"
      },
      "limit": 50,
      "offset": 0
    }
  ]
}
```

This request returns up to 50 matching relations, with the most recently seen relations first. To retrieve the next page, change `offset` to `50`.

#### Reading All Pages

To read a complete result in pages:

1. Choose a positive `limit` and start with `offset` set to `0`.
2. Send the query and process the returned elements.
3. Increase `offset` by `limit` and repeat the same query.
4. Stop when a page contains fewer elements than `limit`. If the last full page contains exactly `limit` elements, the following request returns an empty page.

> [!WARNING]
>
> Please note
>
> * The response-size limit still applies to every request, even when `limit` is omitted. If a page is too large, reduce `limit` or retrieve fewer properties with `attributeNames`.
> * Separate page requests do not create a snapshot. If elements are added, removed or updated between requests, the page boundaries may shift. For a consistent export, avoid changing the relevant data while reading the pages.

## Error Handling

### Format Violations

The API will throw an exception if the incoming payload (that constitutes the query) is invalid or unexpected in any way.

### Inconsistent Input

| **Title** | **Description** | **Expected Behavior** |
| - | - | - |
| `RelationCondition` for a relation | By design, `RelationCondition` only works for assets because they reflect the **connectedness** of an asset. Any `RelationCondition` defined for a relation is ignored. | `RelationCondition` is skipped for relations. |
| Omitting condition | The `condition` field is optional in `Selector`, which allows all instances of a type to be retrieved. Empty or only relation conditions return all instances of types/relations. | Returns all instances if no condition is defined. |
| Unsuitable operator and value | If the operator and value do not match, conditions will likely not evaluate to any results, potentially returning an empty result. Some operators, like booleans, might still work. | Empty result may be returned. |
| `attributeName` not found | If the provided `attributeName` does not exist for the queried type or relation, it is ignored. | `attributeName` is ignored if not found. |
| `Qbilon ID` not found | When using `Qbilon ID` for requests, the ID must be Base64-encoded. Invalid or empty Base64 IDs are skipped. | Invalid IDs or empty strings are skipped. |

## Additional Condition Examples

### Retrieving Assets

* All assets of type `Azure Resource Group` ...
  * with at least 5 outgoing relations of type `contains` **AND**
  * `Provisioning State` matching regex `[a-zA-Z]+` (containing only characters between a-z or A-Z, at least one),
  * extracting properties `Name`, `ID` and `Provisioning State`.

> [!NOTE]
>
> Please note:
>
> * Within the relation constraint, `relationFullName` only applies to the specified relation (which is unique within Qbilon).
> * `conditionType` fields are **required** to distinguish between the different types of constraints.
> * `direction` is not allowed as we want to apply the condition to all relations `contains [A -> B]`.

```json theme={null}
{
  "types": [
    {
      "names": ["Azure Resource Group"],
      "attributeNames": ["Name", "ID", "Provisioning State"],
      "condition": {
        "conditionType": "nested",
        "operator": "and",
        "condition": [
          {
            "conditionType": "atomic",
            "attributeName": "Provisioning State",
            "operator": "matches",
            "value": "[a-zA-Z]+"
          },
          {
            "conditionType": "relation",
            "relationFullName": "contains [A -> B]",
            "count": 5,
            "operator": "greater_than_or_equal"
          }
        ]
      }
    }
  ]
}
```

### Retrieving Relations

* All relations of type `has attached [A → B]` ...
  * with a value for the property `Name` that does not match the Regex `[a-zA-Z]+` and
  * the relation condition is ignored, since it's not applicable to "relations".

> [!NOTE]
>
> Please note:
>
> * `names` are listing relation full names to consider for querying
> * `conditionType` fields are **required** to distinguish between the different types of constraints

```json theme={null}
{
  "relations": [
    {
      "names": ["has attached [A -> B]"],
      "attributeNames": ["Name", "ID", "Provisioning State"],
      "condition": {
        "conditionType": "nested",
        "operator": "and",
        "condition": [
          {
            "conditionType": "atomic",
            "attributeName": "Name",
            "operator": "matches_not",
            "value": "[a-zA-Z]+"
          },
          {
            "conditionType": "relation",
            "relationFullName": "contains [A -> B]",
            "count": 5,
            "operator": "greater_than_or_equal"
          }
        ]
      }
    }
  ]
}
```

### Retrieving All Assets With Condition

Type names or relation names are not required when querying data with this API, allowing for more powerful (and computationally intense) requests, such as:

```json theme={null}
{
  "types": [
    {
      "attributeNames": ["Name"],
      "condition": {
        "conditionType": "atomic",
        "attributeName": "Name",
        "operator": "contains",
        "value": "a"
      }
    }
  ]
}
```

The omission of the `names` field leads to applying the conditions to **all** assets in Qbilon.

```json theme={null}
{
  "relations": [
    {
      "attributeNames": ["Name"],
      "condition": {
        "conditionType": "atomic",
        "attributeName": "Name",
        "operator": "contains",
        "value": "a"
      }
    }
  ]
}
```

This also applies to relations.

### Retrieving All Properties

The `attributeNames` property in the input is not required, but the `attributeName` in the condition is mandatory. If `attributeNames` is omitted or empty, all properties are retrieved for each matching instance.

```json theme={null}
{
  "types": [
    {
      "names": ["AWS Region"],
      "condition": {
        "conditionType": "atomic",
        "attributeName": "First Seen",
        "operator": "within",
        "value": "P1Y1M1W3DT1H3M30S"
      }
    }
  ]
}
```

Here, all instances of `AWS Region` that meet the temporal range condition are retrieved together with all of their properties.


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