# Understanding commands

Copy as Markdown[Open in ChatGPT](https://chatgpt.com/?q=Read%20https%3A%2F%2Fdocs-docusaurus.kinsta.page%2Fdataprime%2Fuser-guide%2Ffoundations%2Funderstanding-commands.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-commands.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:

* Recognize the core DataPrime commands and when to use them.
* Combine multiple commands to perform real-time filtering, transformations, and aggregations.
* Understand the structural difference between commands and functions in a query pipeline.

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

Commands are the engine behind most DataPrime queries. Raw logs are rarely in the shape you need. Whether you're triaging an incident, generating a report, or building a dashboard, you’ll need to transform your data quickly and safely. Commands in DataPrime provide the building blocks to:

* filter out noise
* extract structure
* enrich and join values
* compute statistics
* reshape your dataset in real time

Mastering these tools is what turns a basic query into a flexible investigation or automation pipeline.

## Commands vs. functions[​](#commands-vs-functions "Direct link to Commands vs. functions")

In DataPrime, **commands** are top-level operations that act on **rows and datasets**. They differ from **functions**, which transform individual values. Commands act on rows, fields, and entire document sets.

## Common patterns and syntax[​](#common-patterns-and-syntax "Direct link to Common patterns and syntax")

Most commands appear at the **start of a line** and accept one or more **arguments or expressions**.

They’re usually chained with the pipe (`|`) operator like with `filter`, `groupby`, and `top` in the following example:

```
source logs

| filter status_code >= 500

| groupby path aggregate count() as error_count

| top 5 path by error_count
```

Data flows from left to right and top to bottom. Each command transforms the dataset further.

***

## Core command categories and examples[​](#core-command-categories-and-examples "Direct link to Core command categories and examples")

### Type- and format-specific operations[​](#type--and-format-specific-operations "Direct link to Type- and format-specific operations")

* [**`source`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/sources/source/.md) – Explicitly define your data source (`logs`, `spans`, `metrics`, or enrichment tables).

  ```
  source logs
  ```

* [**`limit`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/limit/.md) – Limit number of rows.

  ```
  limit 100
  ```

* [**`orderby / sortby`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/orderby_sortby/.md) – Sort by an expression.

  ```
  sortby duration desc
  ```

***

### Selection & filtering[​](#selection--filtering "Direct link to Selection & filtering")

These commands reduce the dataset by applying filters or keeping only relevant fields.

* [**`filter`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/filter/.md) – Keep rows where a condition is true.

  ```
  filter status_code >= 500
  ```

* [**`block`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/block/.md) – The opposite of `filter`. Remove rows that match a condition.

  ```
  block method == 'OPTIONS'
  ```

* [**`choose` / `select`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/choose/.md) – Keep only the specified fields.

  ```
  choose path, status_code
  ```

* **`distinct`** – Return one row per unique value.

  ```
  distinct user_id
  ```

* [**`find` / `text`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/find_text/.md) – Free-text search within a field or across all data.

  ```
  find 'timeout' in message

  text '503'
  ```

***

### Data creation & mutation[​](#data-creation--mutation "Direct link to Data creation & mutation")

Commands that let you generate new fields or modify existing ones.

* [**`create` / `add` / `c`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/create/.md) – Define a new field based on an expression. This acts similarly to a variable.

  ```
  create is_error from status_code >= 500
  ```

* [**`replace`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/replace/.md) – Overwrite a field with a new value.

  ```
  replace duration_ms with duration / 1_000_000
  ```

* [**`remove`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/remove/.md) – Remove fields from the document.

  ```
  remove user_agent
  ```

* [**`convert`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/convert/.md) – Make type conversions explicit for readability.

  ```
  convert datatypes status_code:number
  ```

* [**`redact`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/redact/.md) – Mask sensitive data using regex.

  ```
  redact message matching /[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}/ to '[EMAIL]'
  ```

***

### Aggregation & grouping[​](#aggregation--grouping "Direct link to Aggregation & grouping")

These commands reduce many rows into a summary using groupings or statistics.

* [**`aggregate`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/aggregate/.md) – Run one or more aggregation functions on the entire dataset.

  ```
  aggregate count() as total_logs
  ```

* [**`groupby`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/groupby/.md) – Group by a field or expression, and aggregate within those groups.

  ```
  groupby path aggregate avg(duration) as avg_duration
  ```

* [**`countby`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/countby/.md) – Shorthand to group and count.

  ```
  countby status_code into error_counts
  ```

* [**`top` / `bottom`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/top/.md) – Get top/bottom N records by a sort metric.

  ```
  top 5 path by count()
  ```

* [**`multigroupby`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/multigroupby/.md) – Nested groupings (use sparingly for performance).

***

### Parsing & extraction[​](#parsing--extraction "Direct link to Parsing & extraction")

Commands that turn unstructured data into usable fields.

* [**`extract`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/extract/.md) – Use regex or key-value logic to pull fields out of strings.

  ```
  extract message into fields using regexp(e=/(?<user>\w+) did (?<action>\w+)/)
  ```

* [**`explode`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/explode/.md) – Split an array into multiple rows.

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

***

### Joins & enrichment[​](#joins--enrichment "Direct link to Joins & enrichment")

Commands that combine data from other sources or augment with external context.

* [**`enrich`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/enrich/.md) – Join with a lookup table (e.g., employee info).

  ```
  enrich user_id into user_info using employees
  ```

* [**`join`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/join/.md) – Combine two queries based on a condition.

  ```
  source users | join (source logs | countby userid) on id == userid into logins
  ```

***

### Deduplication[​](#deduplication "Direct link to Deduplication")

Reduce redundancy or volume.

* [**`dedupeby`**](https://docs-docusaurus.kinsta.page/dataprime/language-reference/commands-reference/dedupeby/.md) – Keep N unique combinations based on expression(s).

  ```
  dedupeby operationName keep 5
  ```

***

## When to use a command vs a function[​](#when-to-use-a-command-vs-a-function "Direct link to When to use a command vs a function")

* **Use a function** when working with individual field values (`ipInSubnet`, `length`, `urlDecode`, etc.).
* **Use a command** when transforming the shape, size, or structure of your dataset.

***

## Gotchas[​](#gotchas "Direct link to Gotchas")

* **Commands must be in the correct order.** For example, `create` before `filter` if you're filtering on a derived field.
* **Type mismatches can break filters or aggregations.** Use `convert` or casts if necessary.
* **Chaining too many heavy operations on large datasets may exceed limits.** Break into smaller queries if needed.