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

> Extract parts of texts detected using regular expressions. 

A *regular expression* (or *regex*, *regex pattern*) is a sequence of characters that forms a search pattern.
This pattern is compared against texts, and any matches returned. The matches don't have to be returned as found,
but can be formatted using the `output` parameter. Check below references to familiarize yourself with the regex
language:

* [Google-RE2 regex wiki](https://github.com/google/re2/wiki/Syntax)
* [Wikipedia](https://en.wikipedia.org/wiki/Regular_expression)

Also see the `pattern` parameter below for more details.

## Usage

The following example shows how the step can be used in a recipe.

<Accordion title="Examples" icon="code" defaultOpen="true">
  <Tabs>
    <Tab title="Example 1">
      Extract all twitter mentions with handles between 1 and 15 characters long into lists of mentions

      ```stan theme={null}
      extract_regex(ds.text, {
        "pattern": "@\\w{1,15}",
        "extract_all": true
      }) -> (ds.mentions)
      ```
    </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_regex(text: text|category, {
          "param": value,
          ...
      }) -> (text_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 to extract parts from.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="text_extracted" type="column" required>
    A column containing the extracted part (or parts) for each text. The column's data type will depend on the input
    and specified parameters:

    * Output column has type *text* when:
      `"concat_matches": true` or `"extract_all": false` (matches are strings), and `"as_category": false`
    * Output column has type *category* when:
      `"concat_matches": true` or `"extract_all": false` (matches are strings), and `"as_category": true`
    * Output column has type *list\[category]* when:
      `"extract_all": true` and `"concat_matches": false`
  </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="pattern" type="string" required>
    A regular expression.
    The pattern to be matched in input texts. May include (numbered) [regex capturing groups](https://www.regular-expressions.info/replacebackref.html),
    which allows this method to use parts of a match to format the way matches are represented in the output via the
    `output` parameter. The latter uses google-re2 string replacement with curly braces and numerical identifiers,
    e.g. "{1}" instead of the usual regex syntax using backslashes, like "\1". Numerical identifiers refer to capturing
    groups in the regex pattern (named groups are not supported), where

    * 0 is the whole match
    * 1 is the 1st capturing group
    * 2 is the 2nd capturing group
    * etc...

    The default is `"{0}"`, i.e. simply returning the full match.

    For example, if a column of texts includes twitter mentions of the form "@abc", the regular expression

    `"pattern": "(@)(\\w*)"`

    will match these mentions and save the "@" character and the actual name in two separate capturing groups.
    Using the output format

    `"output": "Match: {0}, Tag: {1}, Name: {2}"`

    will then return matches in the form "Match: @abc, Tag: @, Name: abc".

    <Accordion title="Examples">
      * @\w{1,15}
    </Accordion>
  </ParamField>

  <ParamField path="output" type="string" default="{0}">
    Output format string.
    Determines how matches will be represented in the output. Use numbers in curly braces to refer to captured groups.

    <Accordion title="Examples">
      * {0}
    </Accordion>
  </ParamField>

  <ParamField path="flags" type="array[string]" default="[]">
    Match criteria.
    [Python-style regex flags](https://github.com/google/re2/wiki/Syntax#Flags) determining how to match.

    <Accordion title="Array items">
      <ParamField path="Item" type="string">
        Each item in array.

        Values must be one of the following:

        `ascii` `a` `ignorecase` `i` `locale` `l` `multiline` `m` `dotall` `s`
      </ParamField>
    </Accordion>
  </ParamField>

  <ParamField path="extract_all" type="boolean" default="false">
    Whether to extract first match only or all matches (as lists).
  </ParamField>

  <ParamField path="concat_matches" type="boolean" default="false">
    Whether to concatenate all matches into a single text string.
  </ParamField>

  <ParamField path="separator" type="string" default=" ">
    The character (or string of characters) to use when concatenating multiple matches.
  </ParamField>

  <ParamField path="as_category" type="boolean" default="true">
    Whether to return a categorical rather than text column.
    When the result would be text strings rather than lists (`"extract_all": false"` or `"concat_matches": false`),
    whether to return a column of type *category* rather than *text*.
  </ParamField>
</Accordion>