# push

Appends an element to the end of an array. The original array is modified (mutated) with the new element added.

```liquid
{% json items %}[1, 2, 3, 4]{% endjson %}
{% push items, 5 %}

{% log items %}
{% comment %} Output: [1, 2, 3, 4, 5] {% endcomment %}
```

#### Syntax

```liquid
{% push array_name, element %}
```

#### Parameters

| Parameter    | Required | Description                               |
| ------------ | -------- | ----------------------------------------- |
| `array_name` | Yes      | The array to add the element to           |
| `element`    | Yes      | The value to append (literal or variable) |

#### Behavior

* Adds the element to the **end** of the array
* Modifies the original array (mutation)
* Element can be any type: string, number, object, array, or variable
* Supports nested array access with dot notation

#### Examples

**Push a literal value:**

```liquid
{% json numbers %}[1, 2, 3]{% endjson %}
{% push numbers, 4 %}
{% push numbers, 5 %}

{% log numbers %}
{% comment %} Output: [1, 2, 3, 4, 5] {% endcomment %}
```

**Push a variable:**

```liquid
{% json cart_items %}[]{% endjson %}
{% assign new_item = "Product A" %}
{% push cart_items, new_item %}

{% log cart_items %}
{% comment %} Output: ["Product A"] {% endcomment %}
```

**Push an object:**

```liquid
{% json orders %}[]{% endjson %}

{% json new_order %}
  {
    "id": 12345,
    "total": 99.99,
    "status": "pending"
  }
{% endjson %}

{% push orders, new_order %}

{% log orders %}
{% comment %} Output: [{"id": 12345, "total": 99.99, "status": "pending"}] {% endcomment %}
```

**Build array in a loop:**

```liquid
{% json product_titles %}[]{% endjson %}

{% for item in order.line_items %}
  {% push product_titles, item.title %}
{% endfor %}

{% log "Products ordered:" %}
{% log product_titles %}
```

**Collect filtered items:**

```liquid
{% json high_value_orders %}[]{% endjson %}

{% for order in orders %}
  {% if order.total_price > 100 %}
    {% push high_value_orders, order %}
  {% endif %}
{% endfor %}

{% log "High value orders: " | append: high_value_orders.size %}
```

**Push to nested array:**

```liquid
{% json data %}
  {
    "pending": [],
    "completed": []
  }
{% endjson %}

{% push data.pending, "task1" %}
{% push data.pending, "task2" %}
{% push data.completed, "task0" %}

{% log data %}
{% comment %}
Output: {
  "pending": ["task1", "task2"],
  "completed": ["task0"]
}
{% endcomment %}
```

**Stack implementation with push and pop:**

```liquid
{% json history %}[]{% endjson %}

{% comment %} Add to history {% endcomment %}
{% push history, "page1" %}
{% push history, "page2" %}
{% push history, "page3" %}

{% log "History: " %}
{% log history %}
{% comment %} Output: ["page1", "page2", "page3"] {% endcomment %}

{% comment %} Go back {% endcomment %}
{% pop history as current %}
{% log "Current page: " | append: current %}
{% comment %} Output: Current page: page3 {% endcomment %}
```

**Collect errors during processing:**

```liquid
{% json errors %}[]{% endjson %}
{% json processed %}[]{% endjson %}

{% for item in items %}
  {% if item.valid %}
    {% push processed, item %}
  {% else %}
    {% json error %}
      {
        "item_id": {{ item.id }},
        "message": "Validation failed"
      }
    {% endjson %}
    {% push errors, error %}
  {% endif %}
{% endfor %}

{% if errors.size > 0 %}
  {% log "Errors encountered:" %}
  {% log errors %}
{% endif %}

{% log "Successfully processed: " | append: processed.size %}
```

**Build comma-separated string from array:**

```liquid
{% json tags %}[]{% endjson %}

{% push tags, "sale" %}
{% push tags, "featured" %}
{% push tags, "new" %}

{% assign tag_string = tags | join: ", " %}
{% log "Tags: " | append: tag_string %}
{% comment %} Output: Tags: sale, featured, new {% endcomment %}
```

**Aggregate data from API calls:**

```liquid
{% json all_results %}[]{% endjson %}

{% for page in (1..5) %}
  {% assign url = "https://api.example.com/data?page=" | append: page %}
  {% http url: url, method: "GET" as response %}

  {% if response.ok %}
    {% for item in response.body.items %}
      {% push all_results, item %}
    {% endfor %}
  {% endif %}
{% endfor %}

{% log "Total items collected: " | append: all_results.size %}
```

#### Related Tags

| Tag   | Description                                 |
| ----- | ------------------------------------------- |
| `pop` | Removes and returns the last element (LIFO) |

#### Notes

* The array must exist and be a valid array, otherwise an error is thrown
* Push modifies the original array in place
* Useful for building arrays dynamically during script execution
* Works with the Liquid `| push:` filter, but the tag version supports complex values
* Supports dot notation for nested arrays (e.g., `data.items`)
* No limit on the number of elements that can be pushed


---

# 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://docs.datajet-app.com/liquid/tags/push.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.