> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.itential.com/itential-platform/6/studio/tasks/reference/query/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.itential.com/_mcp/server.

# query

> Use the query task to extract and reshape data from object variables for use with existing tasks.

The `query` task extracts data out of object variables and reshapes that data for an existing task.

## Potential use case

If you have data that does not fit a recognized parameter in an existing task, the `query` task can reshape that data so that it fits. Using an existing task and then extracting data with a query is more efficient than writing a new task to fit the data. You can also use this task to extract data from a variable for evaluation purposes.

There are also unique situations with the `pass_on_null` option that can occur when you perform a query against an object where the query fails.

## Properties

| Incoming       | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pass_on_null` | Boolean | Yes      | Determines the query task results for both its `return_data` as well as which transition (success or failure) it takes if the query fails. See [Using the pass on null variable](#using-the-pass-on-null-variable) below for additional detail.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `query`        | String  | Yes      | Specifies the query expression. It is similar to how you may perform lookups in JavaScript. Consult the [json-query NPM](https://www.npmjs.com/package/json-query) page for usage instructions or review the examples for this task. The query expression can reference a helper function `:get()` when accessing the value of a property in which the key includes special characters. The colon ( : ) is a special character; it is used to delineate JSON keys and values. If the JSON property key includes a colon, query the property value with the `get()` helper function. See Query 9 in the examples below for syntax. The value can come from a job variable, a static value, or an outgoing variable in an earlier task. |
| `obj`          | Object  | Yes      | Identifies the data to query. The object can come from a job variable, a static value, or an outgoing variable in an earlier task.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

| Outgoing      | Description                                                                                                                                                                                                                                                                                                                                   |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `return_data` | The query results are assigned to an immutable outgoing variable `return_data`. Optionally, you can create a job variable from `return_data`. The immutable outgoing variable `return_data` remains, and a new mutable job variable is created. When creating a job variable, provide a new name to avoid name conflicts and provide clarity. |

## Public API query

In this example, a simple automation was built to obtain data from a remote system using a public API.

On the workflow canvas, a `restCall` task is set to retrieve numbers information from an available API on the web. The `query` task represents the data to search, which will be provided by the results of the `restCall` task.

Double-clicking the `restCall` task opens the task dialog and shows the configuration variables. Of note, the URI points to the API: `http://numbersapi.com/random/trivia`.

![](/_fern-img/d14525939ec30f49013a966477488750cd283b3b6faa6c3dc97ee4c1ad52257e.webp)

Next, double-clicking the `Query` task opens the task dialog to show the required input variables. The `query` parameter is set to search the `body` of the JSON in the available API, and the reference task for the `obj` variable is the `response` that returns from the REST Call task.

![](/_fern-img/30799024fe8ba4ba66808eb9af9f0db5b4c97fb18559c30be8a936a9b81f22d6.webp)

Once the automation is executed, the `return_data` variable displays a piece of trivia about a randomly generated number by querying the publicly available [Numbers API](http://numbersapi.com/#42).

![](/_fern-img/bcb603baafcb5a6d367b3c8aec641f88f3b135e162494969dba0caf71a90a4b3.webp)

## Query expressions against an object

The following examples illustrate various query expressions against an example object `exampleObj` on an IOS platform.

### Example object

```js
exampleObj = {
    "platform": {
        "ned": "cisco-ios",
        "description": "Cisco IOS Router or Switch"
    },
    "POPs": {
        "ATL": {
            "COUNTRY": "US",
            "ST": "GEORGIA",
            "LN": "ATLANTA",
            "cisco-ios-xr": [
                {
                    "name": "cr1.atl",
                    "type": "router",
                    "make": "Cisco",
                    "model": "ASR9K"
                }
            ],
            "cisco-ios": [
                {
                    "name": "er1.atl",
                    "type": "router",
                    "make": "Cisco",
                    "model": "3945"
                },
                {
                    "name": "sw1",
                    "type": "switch",
                    "make": "Cisco",
                    "model": "Catalyt 2960G"
                }
            ]
        },
        "ORF": {
            "COUNTRY": "US",
            "ST": "VIRGINIA",
            "LN": "NORFOLK",
            "cisco-ios": [
                {
                    "name": "cr1.orf",
                    "type": "router",
                    "make": "Cisco",
                    "model": "7600"
                }
            ],
            "juniper-junos": [
                {
                    "name": "er1.orf",
                    "type": "router",
                    "make": "Juniper",
                    "model": "MX10"
                }
            ]
        }
    }
}
```

When a query has no matching data and `pass_on_null` is `true`, the workflow will complete successfully.

When a query has no matching data and `pass_on_null` is `false`, the workflow will return an error in the job history. The query will terminate in a failure.

### Query 1

Extract the points of presence with a query that returns the value for the key `POPs`.

```js
{
    pass_on_null: true,
    query: "POPs",
    obj: exampleObj
}
```

**Result:**

```js
{
    "ATL": {
        "COUNTRY": "US",
        "ST": "GEORGIA",
        "LN": "ATLANTA",
        "cisco-ios-xr": [
            {
                "name": "cr1.atl",
                "type": "router",
                "make": "Cisco",
                "model": "ASR9K"
            }
        ],
        "cisco-ios": [
            {
                "name": "er1.atl",
                "type": "router",
                "make": "Cisco",
                "model": "3945"
            },
            {
                "name": "sw1",
                "type": "switch",
                "make": "Cisco",
                "model": "Catalyt 2960G"
            }
        ]
    },
    "ORF": {
        "COUNTRY": "US",
        "ST": "VIRGINIA",
        "LN": "NORFOLK",
        "cisco-ios": [
            {
                "name": "cr1.orf",
                "type": "router",
                "make": "Cisco",
                "model": "7600"
            }
        ],
        "juniper-junos": [
            {
                "name": "er1.orf",
                "type": "router",
                "make": "Juniper",
                "model": "MX10"
            }
        ]
    }
}
```

### Query 2

Refine the previous example and access an object's property. Use dot notation to access the key's value.

```js
{
  pass_on_null: true,
  query: "POPs.ATL.cisco-ios",
  obj: exampleObj
}
```

**Result:**

```js
[
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    },
    {
        "name": "sw1",
        "type": "switch",
        "make": "Cisco",
        "model": "Catalyt 2960G"
    }
]
```

### Query 3

Refine the previous example. Apply a filter using `key=value` syntax that only matches objects where `make` is "Cisco".

```js
{
  pass_on_null: true,
  query: "POPs.ATL.cisco-ios[make=Cisco]",
  obj: exampleObj
}
```

Notice only the first matched element is returned.

**Result:**

```js
{
    "name": "er1.atl",
    "type": "router",
    "make": "Cisco",
    "model": "3945"
}
```

### Query 4

Refine the previous example. Apply a filter to match all objects where `make` is "Cisco" with the asterisk operator.

```js
{
  pass_on_null: true,
  query: "POPs.ATL.cisco-ios[*make=Cisco]",
  obj: exampleObj
}
```

**Result:**

```js
[
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    },
    {
        "name": "sw1",
        "type": "switch",
        "make": "Cisco",
        "model": "Catalyt 2960G"
    }
]
```

### Query 5

Refine the previous example to return all IOS routers in ATL.

```js
{
  pass_on_null: true,
  query: "POPs.ATL.cisco-ios[*type=router]",
  obj: exampleObj
}
```

Since the asterisk operator matches all, an array is returned even if one or no elements match.

**Result:**

```js
[
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    }
]
```

### Query 6

Perform a compound boolean query with a regular expression.

In this example, retrieve all IOS devices in ATL with make Cisco and a name that ends in "atl". The ampersand operator performs a boolean AND evaluation; both conditions must be satisfied. The tilde (`~`) operator performs a regular expression match.

```js
{
  pass_on_null: true,
  query: "POPs.ATL.cisco-ios[* make=Cisco & name~/atl$/]",
  obj: exampleObj
}
```

**Result:**

```js
[
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    }
]
```

### Query 7

Perform a deep query. Search through multiple levels of objects or arrays with `[**]`. Search for any ATL router.

```js
{
  pass_on_null: true,
  query: "POPs.ATL[**][*type=router]",
  obj: exampleObj
}
```

**Result:**

```js
[
    {
        "name": "cr1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "ASR9K"
    },
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    }
]
```

### Query 8

Perform an inner query. Braces de-reference the value of data in the queried object to be used for matching an object's key or an array's element.

Search for all devices in ATL of the NED value found in `platform.ned`.

```js
{
  pass_on_null: true,
  query: "POPs.ATL[{platform.ned}]",
  obj: exampleObj
}
```

**Result:**

```js
[
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    },
    {
        "name": "sw1",
        "type": "switch",
        "make": "Cisco",
        "model": "Catalyt 2960G"
    }
]
```

## Query using the GET helper function

This example demonstrates a query against `exampleObj2` using the `get()` helper function.

### Example object

```js
const exampleObj2 = {
    "platform": {
        "ned": "cisco-ios",
        "description": "Cisco IOS Router or Switch"
    },
    "POPs": {
        "ATL:1": {
            "COUNTRY": "US",
            "ST": "GEORGIA",
            "LN": "ATLANTA",
            "cisco-ios-xr": [
                {
                    "name": "cr1.atl",
                    "type": "router",
                    "make": "Cisco",
                    "model": "ASR9K"
                }
            ],
            "cisco-ios": [
                {
                    "name": "er1.atl",
                    "type": "router",
                    "make": "Cisco",
                    "model": "3945"
                },
                {
                    "name": "sw1",
                    "type": "switch",
                    "make": "Cisco",
                    "model": "Catalyt 2960G"
                }
            ]
        },
        "ORF": {
            "COUNTRY": "US",
            "ST": "VIRGINIA",
            "LN": "NORFOLK",
            "cisco-ios": [
                {
                    "name": "cr1.orf",
                    "type": "router",
                    "make": "Cisco",
                    "model": "7600"
                }
            ],
            "juniper-junos": [
                {
                    "name": "er1.orf",
                    "type": "router",
                    "make": "Juniper",
                    "model": "MX10"
                }
            ]
        }
    }
};
```

### Query 1

Perform a query for a property key that includes a special character. The `get()` helper function matches keys with special characters.

```js
{
  pass_on_null: true,
  query: "POPs.:get(ATL:1)[**][*type=router]",
  obj: exampleObj2
}
```

**Result:**

```js
[
    {
        "name": "cr1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "ASR9K"
    },
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    }
]
```

### Query 2

Search for any `ATL:1` router in the given example object.

```js
{
  pass_on_null: true,
  query: "POPs.:get(ATL:1)[**][*type=router]",
  obj: exampleObj2
}
```

**Result:**

```js
[
    {
        "name": "cr1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "ASR9K"
    },
    {
        "name": "er1.atl",
        "type": "router",
        "make": "Cisco",
        "model": "3945"
    }
]
```

## Single depth query and nested query

The `query` task can extract a property out of an object. Sometimes this object may be nested within another property. The following reference object is used in the examples below.

```bash
{
    "message": "Successfully retrieved product.",
    "data": {
        "_id": "622118d367d955aa5e22f1ed",
        "name": "Wolf Cola",
        "createdBy": "Frank",
        "lastUpdatedBy": "Glenn",
        "description": "The official drink of Boca Raton, FL."
    }
}
```

### Single depth query example

The example data is provided by the job variable `obj`. The object data being queried is the `message`.

![](/_fern-img/84d1e1c0af3694bd857566a0a2e165eff6662fbb5a2796f705d4d927bd6bd443.webp)

The query task extracted the value for `message` ("Successfully retrieved product."). Other tasks can now reference this value in the workflow from the output of the query task (`output.return_data`).

![](/_fern-img/959eef0b4f46146f180e0c01ea2fe57917ba467e14cd895903994fcafef9873c.webp)

### Nested depth query example

The example data is provided by the job variable `obj`. The nested object data being queried is `data.createdBy`.

![](/_fern-img/7094a4eaeddfeb4f90addd4bde16e97f518115b8f28f2f45a9479632901b68cc.webp)

The query task extracted the nested value for `createdBy` ("Frank"). Other tasks can now reference this value in the workflow from the query task's output (`output.return_data`).

![](/_fern-img/c870bd37b4b719bbeee3d6c1ec451a1be8d023fe6318686a62b98451cdfff3fa.webp)

## Using the pass on null variable

The following examples explain the interaction of the returned object and transition result of a `query` task using the `pass_on_null` flag.

### Invalid property: pass on null true

Using the same object from the examples above, the reference variable is set to `true`, and an invalid property is queried.

![](/_fern-img/0bc13c629370aa261bc44b41ce09fc8a471239002b8fad5eda65125dbefd2375.webp)

Since it is a property that does not exist within the object, the query does not match anything and the entire object is returned as the result (a "pass-thru" of the original object). Additionally, the success transition is taken.

![](/_fern-img/022d4c1a148a408b5eede47269fc852c94a1bdb51ba82353151883d527e78f72.webp)

### Invalid property: pass on null false

In this example, an invalid property is being queried and the reference variable is set to `false`.

![](/_fern-img/04865a3cb91dfc5d0c9bedf025aeeef55b166ea4dff0510ca74c60562642014d.webp)

The query does not match anything and the value for the returned data is `undefined`. Because the invalid property is not in the object reference data and the reference variable is set to `false`, the failure transition is taken.

### Multiple nested invalid property: pass on null has no effect

In this example, a property is being queried that is at least two levels deep and neither layer exists in the object. The reference variable setting has no effect on the outcome of the returned object nor the transition.

![](/_fern-img/9195f364d5ce6e4b7d082de8cd73bf2647c90755e5cb805b9a8591a5494379e8.webp)

The result of this query is a unique circumstance because the value for the returned data is `null` with a success transition.

Take special precaution when using this scenario as it is highly counter-intuitive.

> Use the query task to extract and reshape data from object variables for use with existing tasks.