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

# filter_containing

> Filter rows containing any or all of a number of specified values. 

Includes or excludes rows of the input datset based on the values of a selected text or list column. Depending on the
configuration, if the column contains any or all of the specified values, the corresponding rows will be kept or dropped
in the output dataset.

"Containment" here means texts in a text column containing one or more specified substrings (words), or lists in a
list column containing one or more elements matching the specified values. See below for illustrative examples.

## 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">
      E.g., to keep only those rows whose values in the "address" column contain the text string "Madrid":

      ```stan theme={null}
      filter_containing(ds, {"column": "address", "values": ["Madrid"]}) -> (ds_filtered)
      ```
    </Tab>

    <Tab title="Example 2">
      Or, given a dataset with the column "jobs", containing lists of one or more job categories in each row, to keep only those rows where the list includes the word "journalist" (ignoring the letter case, i.e. upper or lower case):

      ```stan theme={null}
      filter_containing(ds, {
        "column": "jobs",
        "values": ["journalist"],
        "case_sensitive": false
      }) -> (ds_filtered)
      ```
    </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}
      filter_containing(ds_in: dataset, {
          "param": value,
          ...
      }) -> (ds_out: dataset)
      ```
    </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_in" type="dataset" required>
    An input dataset to filter.
  </ParamField>
</Accordion>

<Accordion title="Outputs" icon="right-from-bracket">
  <ParamField path="ds_out" type="dataset" required>
    A dataset containing the same columns as the input dataset, but including or excluding the matched rows.
  </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="column" type="string (ds_in.column:text|list)" required>
    Name of column to be matched against the specified `values`.
  </ParamField>

  <ParamField path="values" type="[number, string, array[['number', 'string']]]" required>
    Values to be matched in each row to decide its inclusion or exclusion.
    May be a single value or a list of values to be matched.

    <Accordion title="Array items">
      <ParamField path="Item" type="[number, string]">
        Each item in array.
      </ParamField>
    </Accordion>

    <Accordion title="Examples">
      * the
      * \['the', 'cat']
      * 2
      * \[2, 3]
    </Accordion>
  </ParamField>

  <ParamField path="exclude" type="boolean" default="false">
    If `true`, matching rows will be excluded from the output dataset.
    I.e., only rows *not* containing the specified values will be returned.
  </ParamField>

  <ParamField path="contains_all" type="boolean" default="false">
    Rows must contain *all* specified value to pass filter, rather than *any*.
  </ParamField>

  <ParamField path="case_sensitive" type="boolean" default="true">
    Text values must match case to pass filter.
  </ParamField>
</Accordion>