# Understanding functions

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdataprime%2Fuser-guide%2Ffoundations%2Funderstanding-functions.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)[Open in Claude](https://claude.ai/new?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdataprime%2Fuser-guide%2Ffoundations%2Funderstanding-functions.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

## Goal[​](#goal "Direct link to Goal")

By the end of this guide you should be able to identify, use, and compose DataPrime functions to transform and evaluate values within your datasets.

## Why it matters[​](#why-it-matters "Direct link to Why it matters")

Functions in DataPrime are the precision tools of your queries. They let you inspect individual fields within your logs, calculate values, validate formats, work with timestamps, manipulate arrays, and more—all inline, at the field level. If commands define *what to do* with documents, functions define *how to compute* new values or check conditions.

Mastering functions allows you to:

* Clean and normalize messy fields
* Build rich conditional logic
* Perform math and string operations without leaving the platform
* Get the most out of filtering, aggregating, and alerting

## What are functions?[​](#what-are-functions "Direct link to What are functions?")

Functions are **expressions** that take one or more inputs and return a value. That value can be:

* stored in a new field (via `create`),
* used in a condition (e.g. `filter length(name) > 10`),
* or passed into another function (function chaining).

Functions are available in [two interchangeable notations](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/.md):

* **Function notation**: `length(name)`
* **Method notation**: `name.length()`

These two notations are equivalent. Use whichever is more readable and useful in context.

***

## Common function categories[​](#common-function-categories "Direct link to Common function categories")

Functions are grouped into categories based on what kind of data they operate on. Here’s a breakdown of the most common ones. See the [language reference](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/.md) for a list of all functions.

### String functions[​](#string-functions "Direct link to String functions")

Transform or evaluate strings—essential for log cleanup and normalization.

* [`length(str)`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/length/.md) – Number of characters.
* [`contains(str, substr)`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/contains/.md) – Checks if a string contains a value.
* [`startsWith()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/startswith/.md), [`endsWith()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/endswith/.md) – Prefix/suffix matching.
* [`pad()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/pad/.md), [`toLowerCase()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/tolowercase/.md), [`trim()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/trim/.md) – Modify string content.

***

### Number functions[​](#number-functions "Direct link to Number functions")

Work with and calculate numerical values.

* [`abs()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/abs/.md), [`floor()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/floor/.md), [`ceil()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/ceil/.md) – Basic math.
* [`mod()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/mod/.md), [`round()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/round/.md), [`power()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/power/.md) – Advanced operations.
* [`log()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/log/.md), [`log2()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/ln/.md) – Work with logarithms.
* [`max()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/aggregation/max/.md), [`min()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/aggregation/min/.md) – Compare multiple values.
* [`fromBase()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/frombase/.md), [`toBase()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/number/tobase/.md) – Convert between number bases.

***

### Time functions[​](#time-functions "Direct link to Time functions")

Parse, format, and compute with timestamps and intervals.

* [`now()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/now/.md) – The current timestamp.
* [`parseTimestamp()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/parsetimestamp/.md), [`formatTimestamp()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/formattimestamp/.md) – Work with time strings.
* [`diffTime()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/difftime/.md) – Time between two timestamps.
* [`addTime()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/addtime/.md), [`subtractTime()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/subtracttime/.md) – Adjust timestamps.
* [`parseInterval()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/parseinterval/.md), [`formatInterval()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/time/formatinterval/.md) – Work with time durations.

***

### Array functions[​](#array-functions "Direct link to Array functions")

Manipulate and search within arrays.

* `arrayLength(arr)` – Count elements.
* `arrayContains(arr, value)` – Check membership.
* `arrayJoin(arr, delimiter)` – Flatten to string.
* `arrayAppend()`, `arrayRemove()`, `arrayInsertAt()` – Modify contents.
* `arraySplit()` – Turn a string into an array.

***

### Validation & utility functions[​](#validation--utility-functions "Direct link to Validation & utility functions")

Check or generate structured values.

* [`isUuid()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/uuid/isuuid/.md), [`randomUuid()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/uuid/randomuuid/.md) – Work with UUIDs.
* [`ipInSubnet()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/ip/ipinsubnet/.md), [`ipPrefix()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/ip/ipprefix/.md) – Work with IPs.
* [`decodeBase64()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/decodebase64/.md), [`encodeBase64()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/encodebase64/.md) – Encode/decode safely.
* [`matches()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/matches/.md) – Test a regex match.

***

### Control flow functions[​](#control-flow-functions "Direct link to Control flow functions")

Allow inline conditional logic and fallback values.

* [`if(condition, then, else)`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/general/if/.md) – Simple branching.
* [`firstNonNull()`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/general/firstnonnull/.md) – Return the first non-null value.
* [`case`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/cases/case/.md), [`case_equals`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/cases/case_contains/.md), [`case_contains`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/cases/case_contains/.md) – Complex branching logic.

***

## Function composition and chaining[​](#function-composition-and-chaining "Direct link to Function composition and chaining")

Functions can be nested and/or chained. For example:

```
source logs

| email.trim().toLowerCase().contains('@company.com')
```

This is equivalent to:

```
source logs

| contains(toLowerCase(trim(username)), '@company.com')
```

Both are valid. Use the style that’s most readable and appropriate for your use case.

***

## Expected output[​](#expected-output "Direct link to Expected output")

Most functions return simple [types](https://docs-docusaurus.kinsta.page/dataprime/language-reference/types/.md): `string`, `number`, `boolean`, `timestamp`, `array`, etc.

These can then be:

* displayed in the document
* used in `filter`, `groupby`, `create`, etc.
* passed into other functions

### Example[​](#example "Direct link to Example")

Let’s say we want to normalize a user email and tag whether it's an internal account:

```
source logs

| create email_lower from email.toLowerCase()

| create user_is_internal from email_lower.contains('@company.com')

| choose email, email_lower, user_is_internal
```

If the original document looked like this:

```
{

  "email": "MARIA@COMPANY.COM"

}
```

Then the output will look like:

```
{

  "email": "MARIA@COMPANY.COM",

  "email_lower": "maria@company.com",

  "user_is_internal": true

}
```

This shows how two chained functions can be used in combination—`toLowerCase()` and `contains()`—and their outputs visualized using `choose`.

***

## Gotchas and best practices[​](#gotchas-and-best-practices "Direct link to Gotchas and best practices")

* **Watch out for nulls**: Many functions will return `null` if passed a null input.
* **Don’t over-nest**: For deeply nested expressions, consider breaking them into multiple `create` steps.
* **Use casting when needed**: Use `:number` or `:string` to convert types, e.g. `duration:number`.
* **Use method notation for clarity**: Especially when chaining multiple operations on a field.