# Parallel Execution

When a [run](/docs/orchestration/runs.md) starts, Bluebricks builds a dependency graph (DAG) from the Data references in your blueprint. Independent packages execute in parallel; dependent packages wait for their inputs to be ready.

## Data references

Data references let one package consume the outputs of another:

```
Data.<packageId>.<outputKey>
```

* `Data.` is the reserved prefix for cross-package references
* `<packageId>` is the unique ID of the source package
* `<outputKey>` is the name of the output

<details>

<summary><strong>Example</strong></summary>

```json
{
  "packages": [
    {
      "id": "vpc_module",
      "props": {
        "region": { "value": "Props.region" }
      }
    },
    {
      "id": "eks_cluster",
      "props": {
        "vpc_id": { "value": "Data.vpc_module.vpc_id" },
        "subnet_ids": { "value": "Data.vpc_module.private_subnet_ids" }
      }
    }
  ]
}
```

</details>

Here `eks_cluster` depends on `vpc_module`. Bluebricks executes `vpc_module` first, then passes its `vpc_id` and `private_subnet_ids` outputs to `eks_cluster`.

### Data references in expressions

You can combine Data references with other values using [expr](/docs/orchestration/packages/blueprints-overview/expr.md) expressions:

<details>

<summary><strong>Example</strong></summary>

```json
{
  "props": {
    "bucket_name": {
      "value": "'my-app-' + Data.vpc_module.vpc_id + '-logs'"
    },
    "enable_logging": {
      "value": "Props.create_bucket || Data.s3_module.bucket_exists"
    }
  }
}
```

</details>

Expressions are evaluated at runtime after dependencies complete.

## Execution order

Bluebricks determines execution order automatically from your Data references. Consider this blueprint:

<details>

<summary><strong>Example</strong></summary>

```json
{
  "packages": [
    {
      "id": "launch_template",
      "props": {
        "name": { "value": "Props.template_name" }
      }
    },
    {
      "id": "s3_bucket",
      "props": {
        "bucket_name": {
          "value": "'logs-' + Data.launch_template.launch_template_id"
        }
      }
    },
    {
      "id": "monitoring",
      "props": {
        "template_id": {
          "value": "Data.launch_template.launch_template_id"
        }
      }
    }
  ]
}
```

</details>

{% @mermaid/diagram content="flowchart TD
LT\["launch\_template"]
S3\["s3\_bucket"]
MON\["monitoring"]

```
LT --> S3
LT --> MON" %}
```

`launch_template` runs first because it has no dependencies. Once it completes, `s3_bucket` and `monitoring` run **in parallel** since both depend only on `launch_template`.

Data references can also chain across nested blueprints — Bluebricks resolves the full dependency chain automatically, regardless of nesting depth.

## Tips for faster runs

Fewer Data references between packages means more parallel execution. Where possible, use `Props` (set at deployment time) instead of `Data` (resolved at runtime) to keep packages independent.

<details>

<summary><strong>Sequential:</strong> each package depends on the previous one</summary>

```json
{
  "packages": [
    { "id": "A" },
    { "id": "B", "props": { "input": { "value": "Data.A.output" } } },
    { "id": "C", "props": { "input": { "value": "Data.B.output" } } }
  ]
}
```

</details>

<details>

<summary><strong>Parallel:</strong> packages use properties instead of cross-package Data references</summary>

```json
{
  "packages": [
    { "id": "A", "props": { "input": { "value": "Props.value" } } },
    { "id": "B", "props": { "input": { "value": "Props.value" } } },
    { "id": "C", "props": { "input": { "value": "Props.value" } } }
  ]
}
```

</details>

## Best practices

* Use `Props` for static configuration, `Data` for runtime values
* Never create circular dependencies (A depends on B, B depends on A)
* Reference only outputs that will definitely be available
* Use descriptive output keys so Data references are self-documenting
* Keep expressions readable; avoid deeply nested logic

## See also

* [Runs](/docs/orchestration/runs.md)
* [Inputs & Outputs](/docs/orchestration/packages/inputs-and-outputs.md)
* [Creating Blueprints](/docs/orchestration/packages/blueprints-overview/creating-blueprints.md)
* [Using expr](/docs/orchestration/packages/blueprints-overview/expr.md)


---

# Agent Instructions: 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://bluebricks.co/docs/orchestration/runs/parallel-execution.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.