Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdataprime%2Fuser-guide%2Fusing-dataprime%2Farrays.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%2Fusing-dataprime%2Farrays.md%20and%20help%20me%20with%20my%20question%20about%20this%20Coralogix%20documentation%20page.)

# Using arrays, strings, and complex structures with DataPrime

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

By the end of this guide you should be able to manipulate arrays, transform and analyze strings, and access deeply nested fields. You’ll learn how to split strings, decode values, flatten complex objects, and troubleshoot keypath issues that can break queries.

***

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

Real-world logs rarely come in clean. Arrays often need to be expanded, strings need parsing or decoding, and deeply nested or oddly named fields can get in the way of querying. This guide shows you how to handle that complexity with confidence using DataPrime.

***

## `explode` – Split array elements into rows[​](#explode--split-array-elements-into-rows "Direct link to explode--split-array-elements-into-rows")

### Description[​](#description "Direct link to Description")

Use [`explode`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/explode/.md) when you need to analyze each element in an array as its own document. This is useful for permissions, tags, error lists, and other multi-valued fields.

### Syntax[​](#syntax "Direct link to Syntax")

```
explode <array_field> into <new_field> original preserve
```

### Example – Flatten `scopes` for permission analysis[​](#example--flatten-scopes-for-permission-analysis "Direct link to example--flatten-scopes-for-permission-analysis")

#### Input data[​](#input-data "Direct link to Input data")

```
{ "user_id": "1", "scopes": ["read", "write"] }
```

#### Query[​](#query "Direct link to Query")

```
explode scopes into scope original preserve
```

#### Result[​](#result "Direct link to Result")

```
{ user_id: 1, scope: read, scopes: [read, write] }

{ user_id: 1, scope: write, scopes: [read, write] }
```

***

## `arrayConcat` – Combine multiple arrays into one[​](#arrayconcat--combine-multiple-arrays-into-one "Direct link to arrayconcat--combine-multiple-arrays-into-one")

### Description[​](#description-1 "Direct link to Description")

Use [`arrayConcat`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/array/arrayconcat/.md) to merge two or more arrays into a single array field. Ideal for combining values split across fields (e.g., job queues, error types).

### Syntax[​](#syntax-1 "Direct link to Syntax")

```
create <new_field> from arrayConcat(array1, array2, ...)
```

### Example – Merge frontend and backend error arrays[​](#example--merge-frontend-and-backend-error-arrays "Direct link to Example – Merge frontend and backend error arrays")

#### Input data[​](#input-data-1 "Direct link to Input data")

```
{

  "frontend_errors": ["missing_token", "timeout"],

  "backend_errors": ["db_error"]

}
```

#### Query[​](#query-1 "Direct link to Query")

```
create all_errors from arrayConcat(frontend_errors, backend_errors)
```

#### Result[​](#result-1 "Direct link to Result")

```
{ all_errors: [missing_token, timeout, db_error] }
```

***

## `arrayAppend` – Add a value to the end of an array[​](#arrayappend--add-a-value-to-the-end-of-an-array "Direct link to arrayappend--add-a-value-to-the-end-of-an-array")

### Description[​](#description-2 "Direct link to Description")

Use [`arrayAppend`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/array/arrayappend/.md) to add a value to the end of an array field. This is useful when the value is available, but stored separately from the array.

### Syntax[​](#syntax-2 "Direct link to Syntax")

```
replace <array_field> with <array_field>.arrayAppend(<value>)
```

### Example 1 – Add a static job step[​](#example-1--add-a-static-job-step "Direct link to Example 1 – Add a static job step")

#### Input data[​](#input-data-2 "Direct link to Input data")

```
{ "steps": ["extract", "transform"] }
```

#### Query[​](#query-2 "Direct link to Query")

```
replace steps with steps.arrayAppend('finalize')
```

#### Result[​](#result-2 "Direct link to Result")

```
{ steps: [extract, transform, finalize] }
```

***

### Example 2 – Append a field value into the array[​](#example-2--append-a-field-value-into-the-array "Direct link to Example 2 – Append a field value into the array")

#### Input data[​](#input-data-3 "Direct link to Input data")

```
{

  "jobs": ["job-1", "job-2"],

  "extra_job": "job-3"

}
```

#### Query[​](#query-3 "Direct link to Query")

```
replace jobs with jobs.arrayAppend(extra_job)
```

#### Result[​](#result-3 "Direct link to Result")

```
{ jobs: [job-1, job-2, job-3] }
```

***

## `arrayContains` – Check if a value exists in an array[​](#arraycontains--check-if-a-value-exists-in-an-array "Direct link to arraycontains--check-if-a-value-exists-in-an-array")

### Description[​](#description-3 "Direct link to Description")

Use [`arrayContains`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/array/arraycontains/.md) to determine if a specific value appears inside an array. Returns a boolean.

### Syntax[​](#syntax-3 "Direct link to Syntax")

```
create <flag_field> from <array>.arrayContains(<value>)
```

### Example – Flag blocked IP addresses[​](#example--flag-blocked-ip-addresses "Direct link to Example – Flag blocked IP addresses")

#### Input data[​](#input-data-4 "Direct link to Input data")

```
{

  "client_ip": "1.2.3.4",

  "blocked_ips": ["1.2.3.4", "5.6.7.8"]

}
```

#### Query[​](#query-4 "Direct link to Query")

```
create is_blocked_ip from blocked_ips.arrayContains(client_ip)
```

#### Result[​](#result-4 "Direct link to Result")

```
{ is_blocked_ip: true }
```

***

## Parsing and transforming strings[​](#parsing-and-transforming-strings "Direct link to Parsing and transforming strings")

### `arraySplit` – Split a string into parts[​](#arraysplit--split-a-string-into-parts "Direct link to arraysplit--split-a-string-into-parts")

### Description[​](#description-4 "Direct link to Description")

Use [`arraySplit`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/array/arraysplit/.md) to break a string into parts using a delimiter. Often used for names, paths, versions, or tags.

### Syntax[​](#syntax-4 "Direct link to Syntax")

```
<field>.arraySplit(<delimiter>)[<index>]
```

### Example – Split full name into first and last[​](#example--split-full-name-into-first-and-last "Direct link to Example – Split full name into first and last")

#### Input data[​](#input-data-5 "Direct link to Input data")

```
{ "name": "Joe-Nelson" }
```

#### Query[​](#query-5 "Direct link to Query")

```
create first_name from name.arraySplit("-")[0]

| create last_name from name.arraySplit("-")[1]
```

#### Result[​](#result-5 "Direct link to Result")

```
{ first_name: Joe, last_name: Nelson }
```

***

## `arrayJoin` – Join array values into a string[​](#arrayjoin--join-array-values-into-a-string "Direct link to arrayjoin--join-array-values-into-a-string")

### Description[​](#description-5 "Direct link to Description")

Use [`arrayJoin`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/array/arrayjoin/.md) to convert an array into a readable string using a delimiter.

### Syntax[​](#syntax-5 "Direct link to Syntax")

```
<array_field>.arrayJoin(<delimiter>)
```

### Example – Format a user action log[​](#example--format-a-user-action-log "Direct link to Example – Format a user action log")

#### Input data[​](#input-data-6 "Direct link to Input data")

```
{ "users": ["Emma", "Ofri", "Zev"], "action": "LOGIN" }
```

#### Query[​](#query-6 "Direct link to Query")

```
create msg from `Users {users.arrayJoin(', ')} performed action {action}`
```

#### Result[​](#result-6 "Direct link to Result")

```
{ msg: Users Emma, Ofri, Zev performed action LOGIN }
```

***

## `urlDecode` / `urlEncode` – Decode or encode URL-safe strings[​](#urldecode--urlencode--decode-or-encode-url-safe-strings "Direct link to urldecode--urlencode--decode-or-encode-url-safe-strings")

### Description[​](#description-6 "Direct link to Description")

Use [`urlDecode`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/url/urldecode/.md) to make encoded strings readable. Use `urlEncode` when you need to safely transmit or store text.

### Syntax[​](#syntax-6 "Direct link to Syntax")

```
<field>.urlDecode()

<field>.urlEncode()
```

### Example – Decode a query string parameter[​](#example--decode-a-query-string-parameter "Direct link to Example – Decode a query string parameter")

#### Input data[​](#input-data-7 "Direct link to Input data")

```
{ "query_string_parameters": { "name": "Tom%20Kosman" } }
```

#### Query[​](#query-7 "Direct link to Query")

```
replace query_string_parameters.name with query_string_parameters.name.urlDecode()
```

#### Result[​](#result-7 "Direct link to Result")

```
{ query_string_parameters: { name: Tom Kosman } }
```

***

## `decodeBase64` – Decode base64 strings[​](#decodebase64--decode-base64-strings "Direct link to decodebase64--decode-base64-strings")

### Description[​](#description-7 "Direct link to Description")

Use [`decodeBase64`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/decodebase64/.md) to convert encoded strings (e.g., compressed URLs or payloads) into readable values.

### Syntax[​](#syntax-7 "Direct link to Syntax")

```
<field>.decodeBase64()
```

### Example – Decode a base64 URL[​](#example--decode-a-base64-url "Direct link to Example – Decode a base64 URL")

#### Input data[​](#input-data-8 "Direct link to Input data")

```
{ "full_url_encoded": "aHR0cHM6Ly9jb3JhbG9naXguY29t" }
```

#### Query[​](#query-8 "Direct link to Query")

```
create full_url from full_url_encoded.decodeBase64()
```

#### Result[​](#result-8 "Direct link to Result")

```
{ full_url: https://coralogix.com }
```

***

## `contains`, `startsWith` – Check for string patterns[​](#contains-startswith--check-for-string-patterns "Direct link to contains-startswith--check-for-string-patterns")

### Description[​](#description-8 "Direct link to Description")

Use [`contains`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/contains/.md) or [`startsWith`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/functions-reference/string/startswith/.md) to detect substrings in a string field. Useful for filtering by prefix, domain, or label.

### Syntax[​](#syntax-8 "Direct link to Syntax")

```
<field>.contains(<substring>)

<field>.startsWith(<substring>)
```

### Example – Identify log types or domains[​](#example--identify-log-types-or-domains "Direct link to Example – Identify log types or domains")

#### Input data[​](#input-data-9 "Direct link to Input data")

```
{ "url": "https://google.com/search", "msg": "ERROR timeout exceeded" }
```

#### Query[​](#query-9 "Direct link to Query")

```
filter url.contains("google.com")

| create is_error_log from msg.startsWith("ERROR")
```

#### Result[​](#result-9 "Direct link to Result")

```
{ is_error_log: true }
```

***

## `choose` – Flatten deeply nested fields[​](#choose--flatten-deeply-nested-fields "Direct link to choose--flatten-deeply-nested-fields")

### Description[​](#description-9 "Direct link to Description")

Use [`choose`](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/choose/.md) to extract a deeply nested field and bring it to the top level. Makes it easier to read and query.

### Syntax[​](#syntax-9 "Direct link to Syntax")

```
choose <deep_field> as <alias>
```

### Example – Simplify metric access[​](#example--simplify-metric-access "Direct link to Example – Simplify metric access")

#### Input data[​](#input-data-10 "Direct link to Input data")

```
{

  "http_request": {

    "metrics": {

      "bytes_metrics": {

        "bytes_received": 1024

      }

    }

  }

}
```

#### Query[​](#query-10 "Direct link to Query")

```
choose http_request.metrics.bytes_metrics.bytes_received as bytes_received
```

#### Result[​](#result-10 "Direct link to Result")

```
{ bytes_received: 1024 }
```

***

## `extract ... using kv()` – Parse key-value strings[​](#extract--using-kv--parse-key-value-strings "Direct link to extract--using-kv--parse-key-value-strings")

### Description[​](#description-10 "Direct link to Description")

Use `extract ... using kv()` to convert a structured string into a map of fields. Add `datatypes` to cast values into numbers or timestamps.

Note

There are several [extractor](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/extract/.md) functions that can be used with the `extract` command.

### Syntax[​](#syntax-10 "Direct link to Syntax")

```
extract <field> into <object> using kv(pair_delimiter, key_delimiter) datatypes ...
```

### Example – Parse and cast query parameters[​](#example--parse-and-cast-query-parameters "Direct link to Example – Parse and cast query parameters")

#### Input data[​](#input-data-11 "Direct link to Input data")

```
{ "msg": "query_id=200&duration_ms=1000" }
```

#### Query[​](#query-11 "Direct link to Query")

```
extract msg into data using kv(pair_delimiter='&', key_delimiter='=') datatypes duration_ms:number
```

#### Result[​](#result-11 "Direct link to Result")

```
{ data: { query_id: 200, duration_ms: 1000 } }
```

***

## Bracket notation – Access special keypaths[​](#bracket-notation--access-special-keypaths "Direct link to Bracket notation – Access special keypaths")

### Description[​](#description-11 "Direct link to Description")

Use bracket notation to access keys that contain dots, spaces, or special characters. Required in archive/compliance mode.

### Syntax[​](#syntax-11 "Direct link to Syntax")

```
<root_field>['key.with.dot.or.special-character']
```

### Example – Filter by a key with dots[​](#example--filter-by-a-key-with-dots "Direct link to Example – Filter by a key with dots")

#### Input data[​](#input-data-12 "Direct link to Input data")

```
{ "k8s.tags.process_id": 1234 }
```

#### Query[​](#query-12 "Direct link to Query")

```
filter k8s['tags.process_id'] == 1234
```

#### Result[​](#result-12 "Direct link to Result")

```
{ k8s.tags.process_id: 1234 }
```

***

## Common pitfalls or gotchas[​](#common-pitfalls-or-gotchas "Direct link to Common pitfalls or gotchas")

* **Exploding arrays removes other fields unless you preserve them.** Always use `original preserve` unless you want a minimal result.
* **String length limits can break string functions.** If a field is longer than 256 characters, some functions may silently return `null` in high-tier mode.
* **Always quote bracketed keypaths.** Even one missed bracket or dot can break your query.