> For the complete documentation index, see [llms.txt](https://daseldocs.tomwright.me/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://daseldocs.tomwright.me/input-output/variables.md).

# Variables

Dasel allows you to define variables for use in your queries.

Variables are referenced using a `$` prefix.

Note that these variables are essentially globals, and once defined, they are accessible at any point in the execution.

Variables can be used alongside `stdin`.

## Inline

Inline variables are those defined within a dasel query itself and should be terminated with a semicolon.

```bash
$ dasel -i json '$x = 1; $y = 2; $x + $y'
3
```

**Multi-step data transformation**

```bash
$ echo '{"users": [{"name": "Alice"}, {"name": "Bob"}]}' \
  | dasel -i json '
    $names = users.map(name);
    $count = len($names);
    "Found " + toString($count) + " users"
  '
"Found 2 users"
```

## From the environment

You can access environment variables using `$ENV_VAR_NAME`.

Note that changes to environment variables within dasel **are not supported**.

```bash
$ GREETING=hello NAME=tom dasel '$GREETING + " " + $NAME'
"hello tom"
```

## From the CLI

You can set variables from the CLI by passing additional arguments in the form of:

`--var name=format:content`

If you wish to pass a file as a variable you can use:

`--var name=format:file:filepath`

```bash
$ echo 'message: Hello world' > test.yaml
$ dasel -o json testVar=yaml:file:test.yaml '$testVar.message'
"Hello world"
```

Note that at this time variables from the CLI are currently required to be documents read from the file system. There are plans to change this in the future.

## Standard variables

Some variables are provided by dasel and will always exist:

* `$root` - The root document passed through `stdin` or `-f`.

### `$this`

`$this` refers to the **current element** being processed. It is available inside expressions that iterate over arrays:

* [`map`](/functions/map.md) — `$this` is the current element being transformed.
* [`filter`](/functions/filter.md) — `$this` is the current element being tested.
* [`each`](/functions/each.md) — `$this` is the current element being visited.
* [`sortBy`](/functions/sortby.md) — `$this` is the current element being compared.
* [`any`](/functions/any.md) / [`all`](/functions/all.md) / [`count`](/functions/count.md) — `$this` is the current element being evaluated.

It is also available in [spread](/syntax/spread.md) contexts and when accessing the current node in conditionals.

#### Examples

```
[1, 2, 3].map($this * 2)
// [2, 4, 6]

[1, 2, 3].filter($this > 1)
// [2, 3]

["hello", "WORLD"].map(toLower($this))
// ["hello", "world"]
```

### `$key`

`$key` refers to the **current index or key** during iteration. For arrays/slices it is an integer index (starting at 0); for maps/objects it is the string key name.

`$key` is available inside all iteration expressions:

* [`map`](/functions/map.md) / [`filter`](/functions/filter.md) / [`each`](/functions/each.md) / [`sortBy`](/functions/sortby.md) / [`groupBy`](/functions/groupby.md) — `$key` is the slice index.
* [`any`](/functions/any.md) / [`all`](/functions/all.md) / [`count`](/functions/count.md) / [`reduce`](/functions/reduce.md) — `$key` is the slice index.
* [`mapValues`](/functions/mapvalues.md) — `$key` is the map key name (string).
* [`search`](/functions/search.md) / [recursive descent](/syntax/recursive-descent.md) — `$key` is the map key (string) or slice index (int) depending on context.

`$key` is scoped to the iteration — it does not leak into outer expressions.

#### Examples

```
[10, 20, 30].map($key)
// [0, 1, 2]

[10, 20, 30].filter($key >= 1)
// [20, 30]

{"a": 1, "b": 2}.mapValues($key)
// {"a": "a", "b": "b"}

[10, 20, 30].map($key + $this)
// [10, 21, 32]
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://daseldocs.tomwright.me/input-output/variables.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.