# String API

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

The String API is the most basic and straightforward way to select columns in Kotlin DataFrame [operations](operations.html).

In String API operation overloads, selected column names are provided directly as `String` values in function arguments:

```KOTLIN
// Select "name" and "info" columns
df.select("name", "info")
```

## String Column Accessors

The String API can also be used inside the [Columns Selection DSL](columnselectors.html) and [row expressions](datarow.html#row-expressions) via `String` column accessors.

`String` column accessors allow you to access nested columns and combine them with [the extension properties](extensionpropertiesapi.html) or with any other [CS DSL methods](columnselectors.html#functions-overview).

String column accessors are created using special functions. In the Columns Selection DSL, they have the special type `ColumnAccessor`, while in row expressions they resolve to concrete value types.

You can optionally specify the column type as a type argument of the `String` column accessor creation function. This is required for row expressions and for some operations with a column selection. The type is not verified against the column, so a mismatch may go unnoticed: in the Columns Selection DSL, `col<T>("name")` and `valueCol<T>("name")` return the column as it is, and in row expressions a `null` value passes through a non-null `T` as well. When a mismatch does surface, it is usually a plain `ClassCastException` at the place where the value is used rather than at the accessor call.

| Columns Selection DSL | Row Expressions |   |
| --- | --- | --- |
| `col("name")` / `col<T>("name")` | `getValue<T>("name")` | Resolves into general [DataColumn](datacolumn.html) / row value with the provided `"name"` and type `T`. |
| `colGroup("name")` / `colGroup<T>("name")` | `getColumnGroup("name")` | Resolves into [ColumnGroup](datacolumn.html#columngroup) with the provided `"name"` and type `T`. Can be used for accessing nested columns |
| `valueCol("name")` / `valueCol<T>("name")` | `getValue<T>("name")` | Resolves into [ValueColumn](datacolumn.html#valuecolumn) / row value with the provided `"name"` and type `T`. |
| `frameCol("name")` / `frameCol<T>("name")` | `getFrameColumn("name")` | Resolves into [FrameColumn](datacolumn.html#framecolumn) / `DataFrame` with the provided `"name"` and type `T`. |

> **Warning:**
> Row Expressions methods may be changed in the future.

### Example

Consider a simple hierarchical dataframe from [](resources/example.csv).

This table consists of two columns: `name`, which is a `String` column, and `info`, which is a [column group](datacolumn.html#columngroup) containing two nested [value columns](datacolumn.html#valuecolumn) — `age` of type `Int`, and `height` of type `Double`.

| name | info |
| --- | --- |
|  | age | height |
| Alice | 23 | 175.5 |
| Bob | 27 | 160.2 |

#### Columns Selection DSL

[Get](getcolumn.html) a single "height" subcolumn from the "info" column group

```KOTLIN
df.getColumn { colGroup("info").col("height") }
```

[Select](select.html) the "age" subcolumn from the "info" column group and the "name" column

```KOTLIN
df.select { colGroup("info").col("age") and col("name") }
```

[Calculate the mean](mean.html) value of the ("info"/"age") column; specify the column type as a `col` type argument

```KOTLIN
df.mean { colGroup("info").col<Int>("age") }
```

Combine Extensions Properties and String Column Accessors. [Select](select.html) "height" and "name" columns, assuming we have extension properties for "info" and "name" columns but not for the ("info"/"height") column

```KOTLIN
df.select { "info".col("height") and name }
```

Combine Columns Selection DSL and String Column Accessors. [Remove](remove.html) all `Number` columns from the dataframe except ("info"/"age")

```KOTLIN
df.remove {
    colsAtAnyDepth().colsOf<Number>() except
        colGroup("info").col("age")
}
```

[Select](select.html) all subcolumns from the "info" column group

```KOTLIN
df.select { colGroup("info").select { col("age") and col("height") } }
// or
df.select { colGroup("info").allCols() }
```

#### Row Expressions

[Add](add.html) a new "heightInt" column by casting the "height" column values to `Int`

```KOTLIN
df.add("heightInt") {
    "info"["height"]<Double>().toInt()
}
```

[Filter](filter.html) rows where the ("info"/"age") column value is greater than or equal to 18

```KOTLIN
df.filter { "info"["age"]<Int>() >= 18 }
```

### Invoked String API

> **Warning:**
> This API is outdated and may be changed in the future.
>
>
>
> Please don't mix it with the `col`/`colGroup` methods.
>
>
>
> We don't recommend using it in production code.

Alternatively, you can use the `String` invocation (optional typed argument) for column accessor creation. It will create the same column accessors as in the Columns Selection DSL. You can access nested columns using the `String.get` or `String.invoke` operators or using the `String.select {}` function, where the receiver is the column group name.

```KOTLIN
// Columns Selection DSL

// Get a single "height" subcolumn from the "info" column group
df.getColumn { "info"["height"]<Double>() }

// Select the "age" subcolumn of the "info" column group
// and the "name" column
df.select { "info"["age"] and "name"() }

// Calculate the mean value of the ("info"/"age") column;
// specify the column type as an invocation type argument
df.mean { "info" { "age"<Int>() } }

// Select all subcolumns from the "info" column group
df.select { "info" { "age"() and "height"() } }
// or
df.select { "info".allCols() }

// Row Expressions

// Add a new "heightInt" column by
// casting the "height" column values to `Int`
df.add("heightInt") {
    "info"["height"]<Double>().toInt()
}

// Filter rows where the ("info"/"age") column value
// is greater than or equal to 18
df.filter { "info"["age"]<Int>() >= 18 }
```

## When should I use the String API?

The String API is a good starting point for learning the library and understanding how column selection works.

For production code we strongly recommend using the [Extension Properties API](extensionpropertiesapi.html) instead. It is more concise, fully type-safe, and provides better IDE support.

However, note that sometimes the usage of Extension Properties API is not possible or may require too many excess actions. In such cases, use [String Column Accessors](#string-column-accessors).