> ## Documentation Index
> Fetch the complete documentation index at: https://docs.keephq.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Functions

The **Functions** in Keep Workflow Engine are utilities that can be used to manipulate data, check conditions, or perform transformations within workflows. This document provides a brief overview and usage examples for each available function.

***

## Mathematical Functions

### `add`

**Description:** Adds all provided numbers together. All arguments are converted to integers.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.add(1, 2, 3) # Output: 6
        message2: keep.add(10, 20, 30) # Output: 60
```

***

### `sub`

**Description:** Subtracts all subsequent numbers from the first number. All arguments are converted to integers.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.sub(10, 2, 3) # Output: 5
        message2: keep.sub(100, 20, 30) # Output: 50
```

***

### `mul`

**Description:** Multiplies all provided numbers together. All arguments are converted to integers.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.mul(2, 3, 4) # Output: 24
        message2: keep.mul(5, 6, 7) # Output: 210
```

***

### `div`

**Description:** Divides the first number by all subsequent numbers. All arguments are converted to integers. Returns an integer if the division result is whole, otherwise returns a floating-point number.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.div(10, 2) # Output: 5
        message2: keep.div(10, 3) # Output: 3.3333333333333335
        message3: keep.div(100, 2, 5) # Output: 10
```

***

### `mod`

**Description:** Calculates the remainder of dividing the first number by all subsequent numbers sequentially. All arguments are converted to integers.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.mod(10, 3) # Output: 1
        message2: keep.mod(100, 30, 7) # Output: 2
```

***

### `exp`

**Description:** Raises the first number to the power equal to the product of all subsequent numbers. All arguments are converted to integers.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.exp(2, 3) # Output: 8
        message2: keep.exp(2, 3, 2) # Output: 64
```

***

### `fdiv`

**Description:** Performs integer division of the first number by all subsequent numbers sequentially. All arguments are converted to integers.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.fdiv(10, 3) # Output: 3
        message2: keep.fdiv(100, 3, 2) # Output: 16
```

***

### `eq`

**Description:** Checks if two values are equal.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.eq(5, 5) # Output: true
        message2: keep.eq("hello", "world") # Output: false
        message3: keep.eq([1, 2, 3], [1, 2, 3]) # Output: true
```

***

## String Functions

### `uppercase`

**Description:** Converts a string to uppercase.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: "keep.uppercase('hello world')" # Output: "HELLO WORLD"
```

***

### `lowercase`

**Description:** Converts a string to lowercase.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: "keep.lowercase('HELLO WORLD')" # Output: "hello world"
```

***

### `capitalize`

**Description:** Capitalizes the first character of a string.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.capitalize("hello world") # Output: "Hello world"
```

***

### `title`

**Description:** Converts a string to title case (capitalizes each word).
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.title("hello world") # Output: "Hello World"
```

***

### `split`

**Description:** Splits a string into a list using a delimiter.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: "keep.split('a,b,c', ',')" # Output: ["a", "b", "c"]
```

***

### `strip`

**Description:** Removes leading and trailing whitespace from a string.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.strip("  hello world  ") # Output: "hello world"
```

***

### `replace`

**Description:** Replaces occurrences of a substring with another string.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.replace("hello world", "world", "Keep") # Output: "hello Keep"
```

***

### `remove_newlines`

**Description:** Removes all newline and tab characters from a string.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.remove_newlines("hello\nworld\t!") # Output: "helloworld!"
```

***

### `encode`

**Description:** URL-encodes a string.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.encode("hello world") # Output: "hello%20world"
```

***

### `slice`

**Description:** Extracts a portion of a string based on start and end indices.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.slice("hello world", 0, 5) # Output: "hello"
```

***

## List and Dictionary Functions

### `first`

**Description:** Retrieves the first element from a list.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.first([1, 2, 3]) # Output: 1
```

***

### `last`

**Description:** Retrieves the last element from a list.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.last([1, 2, 3]) # Output: 3
```

***

### `index`

**Description:** Retrieves an element at a specific index from a list.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.index(["a", "b", "c"], 1) # Output: "b"
```

***

### `join`

**Description:** Joins a list of elements into a string using a delimiter.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.join(["a", "b", "c"], ",") # Output: "a,b,c"
```

***

### `len`

**Description:** Returns the length of a list.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.len([1, 2, 3]) # Output: 3
```

***

### `dict_to_key_value_list`

**Description:** Converts a dictionary into a list of key-value pairs.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_to_key_value_list({"a": 1, "b": 2}) # Output: ["a:1", "b:2"]
```

***

### `dict_pop`

**Description:** Removes specified keys from a dictionary.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_pop({"a": 1, "b": 2, "c": 3}, "a", "b") # Output: {"c": 3}
```

***

### `dict_pop_prefix`

**Description:** Removes all keys that start with a specified prefix from a dictionary.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_pop_prefix({"a_1": 1, "a_2": 2, "b_1": 3}, "a_") # Output: {"b_1": 3}
```

***

### `dict_filter_by_prefix`

**Description:** Returns only the dictionary entries whose keys start with a specified prefix.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dict_filter_by_prefix({"a_1": 1, "a_2": 2, "b_1": 3}, "a_") # Output: {"a_1": 1, "a_2": 2}
```

***

### `dictget`

**Description:** Gets a value from a dictionary with a default fallback.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.dictget({"a": 1, "b": 2}, "c", "default") # Output: "default"
```

***

## Date and Time Functions

### `from_timestamp`

**Description:** Converts unix timestamp int, float or string to datetime object, with optional timezone option.

**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: console
      with:
        message: keep.from_timestamp(1717244449.0) # will print "2024-06-01 12:20:49+00:00"
        # or with timezone
        # message: keep.from_timestamp(1717244449.0, "Europe/Berlin") # will print "2024-06-01 14:20:49+02:00"
```

### `utcnow`

**Description:** Returns the current UTC datetime.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.utcnow()
```

***

### `utcnowtimestamp`

**Description:** Returns the current UTC datetime as a Unix timestamp (seconds since epoch).
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.utcnowtimestamp() # Output: 1704067200
```

***

### `utcnowiso`

**Description:** Returns the current UTC datetime in ISO format.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.utcnowiso()
```

***

### `to_utc`

**Description:** Converts a datetime string or object to UTC.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.to_utc("2024-01-01T00:00:00")
```

***

### `to_timestamp`

**Description:** Converts a datetime object or string into a Unix timestamp.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.to_timestamp("2024-01-01T00:00:00")
```

***

### `datetime_compare`

**Description:** Compares two datetime objects and returns the difference in hours.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.datetime_compare("2024-01-01T10:00:00", "2024-01-01T00:00:00") # Output: 10.0
```

***

### `is_business_hours`

**Description:** Checks whether a given time falls within business hours.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.is_business_hours(
          time_to_check="2024-01-01T14:00:00Z",
          start_hour=8,
          end_hour=20,
          business_days=[0,1,2,3,4],
          timezone="America/New_York"
        )
```

***

## JSON Functions

### `json_dumps`

**Description:** Converts a dictionary or string into a formatted JSON string.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.json_dumps({"key": "value"})
```

***

### `json_loads`

**Description:** Parses a JSON string into a dictionary.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.json_loads('{"key": "value"}')
```

***

## Utility Functions

### `get_firing_time`

**Description:** Calculates the firing duration of an alert in specified time units.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.get_firing_time(alert, "m", tenant_id="tenant-id") # Output: "15.0"
```

***

### `add_time_to_date`

**Description:** Adds time to a date string based on specified time units.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.add_time_to_date("2024-01-01", "%Y-%m-%d", "1w 2d") # Output: "2024-01-10"
```

***

### `timestamp_delta`

**Description:** Adds or subtracts a time delta to/from a datetime. Use negative values to subtract time.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        # Add 2 hours to the current time
        add_hours: keep.timestamp_delta(keep.utcnow(), 2, "hours")

        # Subtract 30 minutes from a specific datetime
        subtract_minutes: keep.timestamp_delta("2024-01-01T12:00:00Z", -30, "minutes") # Output: 2024-01-01T11:30:00Z

        # Add 1 week to a datetime
        add_week: keep.timestamp_delta("2024-01-01T00:00:00Z", 1, "weeks") # Output: 2024-01-08T00:00:00Z
```

***

### `is_first_time`

**Description:** Checks if an alert with a given fingerprint is firing for the first time or first time within a specified period.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        # Check if this is the first time the alert is firing
        first_time: keep.is_first_time(alert.fingerprint, tenant_id="tenant-id")

        # Check if this is the first time the alert is firing in the last 24 hours
        first_time_24h: keep.is_first_time(alert.fingerprint, "24h", tenant_id="tenant-id")
```

***

### `all`

**Description:** Checks if all elements in an iterable are identical.
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.all([1, 1, 1]) # Output: true
```

***

### `diff`

**Description:** Checks if any elements in an iterable are different (opposite of `all`).
**Example:**

```yaml theme={null}
steps:
  - name: example-step
    provider:
      type: mock
      with:
        message: keep.diff([1, 2, 1]) # Output: true
```

***