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

# derive_column

> Derive a new column with a custom JS script. 

Supports any JS script using ECMAScript 2023 syntax. The script should have a `return` clause returning either a value or null / undefined.
The script has access to a `row` object that represent a row in the dataset and have the column names as keys.
Lists are supported both as inputs and outputs.
It's important to correctly manage null values by checking for null (e.g. `if (row.col != null) { ... }`) or using the JS optional chaining operator (`?`).

## Usage

The following examples show how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      The following example joins all values in a list of numbers with '|' as separator:

      ```stan theme={null}
      derive_column(ds, {
        "script": "return row.numCol?.join(' | ');",
        "type": "text"
      }) -> (ds.new_col)
      ```
    </Tab>

    <Tab title="Example 2">
      The following example computes the sum for a list of numbers:

      ```stan theme={null}
      derive_column(ds, {
        "script": "return row.numCol?.reduce((sum, n) => sum + n, 0);",
        "type": "category"
      }) -> (ds.new_col)
      ```
    </Tab>

    <Tab title="Example 3">
      The following example adds a prefix to a category:

      ```stan theme={null}
      derive_column(ds, {
        "script": "return row.cat != null ? `Prefix_${row.cat}` : null;"
      }) -> (ds.new_col)
      ```
    </Tab>

    <Tab title="Example 4">
      The following example extracts a regex from a text:

      ```stan theme={null}
      derive_column(ds, {
        "script": "return row.text?.match(/\d+/);",
        "type": "category"
      }) -> (ds.new_col)
      ```
    </Tab>

    <Tab title="Example 5">
      The following example extracts the domain from a URL column:

      ```stan theme={null}
      derive_column(ds, {
        "script": "return row.url != null ? new URL(row.url).hostname : null;",
        "type": "category"
      }) -> (ds.new_col)
      ```
    </Tab>

    <Tab title="Example 6">
      The following example extracts the year component from a Date column:

      ```stan theme={null}
      derive_column(ds, {
        "script": "return row.dateCol != null ? new Date(row.dateCol).getUTCFullYear() : null;",
        "type": "number"
      }) -> (ds.new_col)
      ```
    </Tab>

    <Tab title="Signature">
      General syntax for using the step in a recipe. Shows the inputs and outputs the step is expected to receive and will produce respectively. For futher details see sections below.

      ```stan theme={null}
      derive_column(ds: dataset, {
          "param": value,
          ...
      }) -> (new_col: column)
      ```
    </Tab>
  </Tabs>
</Accordion>

## Inputs & Outputs

The following are the inputs expected by the step and the outputs it produces. These are generally
columns (`ds.first_name`), datasets (`ds` or `ds[["first_name", "last_name"]]`) or models (referenced
by name e.g. `"churn-clf"`).

<Accordion title="Inputs" icon="right-to-bracket">
  <ParamField path="ds" type="dataset" required>
    An input dataset.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="new_col" type="column" required>
    The column resulting from evaluating the script.
  </ParamField>
</Accordion>

## Configuration

The following parameters can be used to configure the behaviour of the step by including them in
a json object as the last "input" to the step, i.e. `step(..., {"param": "value", ...}) -> (output)`.

<Accordion title="Parameters" defaultOpen="true" icon="sliders">
  <ParamField path="script" type="string" required>
    The javascript code to execute.

    <Accordion title="Examples">
      * For example, to multiply by 2 every row with a value:

      ```json theme={null}
      "return row.num * 2;"
      ```
    </Accordion>
  </ParamField>

  <ParamField path="type" type="string" required>
    Output column type.
    Select the desired type using a shortened yet fully specified name.

    Values must be one of the following:

    `boolean` `category` `date` `number` `text` `url` `list[number]` `list[category]` `list[url]` `list[date]` `list[boolean]`
  </ParamField>
</Accordion>