> ## 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.

# extract_json_values

> Extract values from JSON columns using JsonPath. 

Uses a simplified JsonPath-like syntax to extract values from JSON objects.

**Supported syntax:**

* Dot notation: `address.city`, `address.anotherLevel.key`
* Array index: `phoneNumbers[0].type`, `phoneNumbers[1].number`
* Array slice (all elements): `phoneNumbers[:]`, `phoneNumbers[::]`
* Array slice (range): `phoneNumbers[0:2]`, `phoneNumbers[0:2:1]`
* Array slice (with step): `phoneNumbers[::2]`
* Quoted keys (for special characters): `address["other info"]`
* Root array access: `$[:].firstName`

**Not supported:**

* Wildcard `[*]` — use `[:]` instead
* Negative indices `[-1]`
* Recursive descent `..`

See [darro#243](https://github.com/graphext/darro/issues/243) for tracking support of these operators.

## 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">
      Extract a simple nested value.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "address.city",
        "type": "text"
      }) -> (ds.cities)
      ```
    </Tab>

    <Tab title="Example 2">
      Extract a value from the first element of an array.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "phoneNumbers[0].type",
        "type": "category"
      }) -> (ds.first_phone_type)
      ```
    </Tab>

    <Tab title="Example 3">
      Extract values from all elements of an array using slice notation.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "phoneNumbers[:].type",
        "type": "list[category]"
      }) -> (ds.all_phone_types)
      ```
    </Tab>

    <Tab title="Example 4">
      Extract values from a range of array elements.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "items[0:3].name",
        "type": "list[category]"
      }) -> (ds.first_three_names)
      ```
    </Tab>

    <Tab title="Example 5">
      Extract a deeply nested value.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "address.anotherLevel.key",
        "type": "text"
      }) -> (ds.deep_value)
      ```
    </Tab>

    <Tab title="Example 6">
      Access a key with special characters using quoted bracket notation.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "address[\"other info\"]",
        "type": "text"
      }) -> (ds.other_info)
      ```
    </Tab>

    <Tab title="Example 7">
      Extract from root-level arrays using the \$ symbol.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "$[:].firstName",
        "type": "list[category]"
      }) -> (ds.first_names)
      ```
    </Tab>

    <Tab title="Example 8">
      Extract numeric values from an array as a multivalued number column.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "scores",
        "type": "list[number]"
      }) -> (ds.all_scores)
      ```
    </Tab>

    <Tab title="Example 9">
      Extract dates in ISO 8601 format (e.g. "2024-01-15T10:30:00" or "2024-01-15"). These are parsed automatically.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "created_at",
        "type": "date"
      }) -> (ds.created_at)
      ```
    </Tab>

    <Tab title="Example 10">
      For dates in non-standard formats (e.g. "15/01/2024", "01-15-2024"), extract as category first and then use cast with a format string, because extract\_json\_values does not support custom date format parsing.

      ```stan theme={null}
      extract_json_values(ds.json_col, {
        "path": "event_date",
        "type": "category"
      }) -> (ds.event_date_raw)

      cast(ds.event_date_raw, {
        "type": "date",
        "format": "%d/%m/%Y"
      }) -> (ds.event_date)
      ```
    </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}
      extract_json_values(text: text|category, {
          "param": value,
          ...
      }) -> (value_extracted: 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="text" type="column[text|category]" required>
    A text column with Json values to extract parts from.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="value_extracted" type="column" required>
    The column resulting from evaluating the JsonPath expression on the input column.
  </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="path" type="string" required>
    JsonPath-like string used to extract values from the JSON column. Supports dot notation, array indices, slices and quoted keys. Does not support wildcard \[\*], negative indices or recursive descent (..).

    <Accordion title="Examples">
      * address.city
      * phoneNumbers\[:].type
    </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]`
  </ParamField>
</Accordion>