Skip to content

Remove column accessors API from documentation #1171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
May 5, 2025
Merged

Remove column accessors API from documentation #1171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
09a61ef
Hide accessors API samples from documentation
koperagen May 5, 2025
b169cc2
Remove obsolete column accessors API from docs
koperagen May 5, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 0 additions & 3 deletions core/build.gradle.kts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -316,9 +316,6 @@ korro {
funSuffix("_properties") {
replaceText("NAME", "Properties")
}
funSuffix("_accessors") {
replaceText("NAME", "Accessors")
}
funSuffix("_strings") {
replaceText("NAME", "Strings")
}
Expand Down
2 changes: 0 additions & 2 deletions docs/StardustDocs/d.tree
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,8 +15,6 @@
<toc-element topic="overview.md">
<toc-element topic="apiLevels.md">
<toc-element topic="stringApi.md"/>
<toc-element toc-title="Column Accessors API" topic="columnAccessorsApi.md"/>
<toc-element topic="KPropertiesApi.md"/>
<toc-element topic="extensionPropertiesApi.md"/>
</toc-element>
<toc-element topic="hierarchical.md"/>
Expand Down
36 changes: 0 additions & 36 deletions docs/StardustDocs/topics/ColumnSelectors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -454,42 +454,6 @@ df.select { name.allCols() }
df.select { name.colsAtAnyDepth { !it.isColumnGroup() } }
```

</tab>
<tab title="Accessors">

```kotlin
// by column name
val name by columnGroup()
df.select { it[name] }
df.select { name }

// by column path
val firstName by name.column<String>()
df.select { firstName }

// with a new name
df.select { name named "Full Name" }

// converted
df.select { firstName.map { it.lowercase() } }

// column arithmetics
val age by column<Int>()
df.select { 2021 - age }

// two columns
df.select { name and age }

// range of columns
df.select { name..age }

// all columns of ColumnGroup
df.select { name.allCols() }

// traversal of columns at any depth from here excluding ColumnGroups
df.select { name.colsAtAnyDepth { !it.isColumnGroup() } }
```

</tab>
<tab title="Strings">

Expand Down
137 changes: 1 addition & 136 deletions docs/StardustDocs/topics/DataColumn.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,140 +35,5 @@ Special case of [`ValueColumn`](#valuecolumn) that stores another [`DataFrame`](

[`DataFrame`](DataFrame.md) stored in [`FrameColumn`](DataColumn.md#framecolumn) may have different schemas.

[`FrameColumn`](DataColumn.md#framecolumn) may appear after [reading](read.md) from JSON or other hierarchical data structures, or after grouping operations such as [groupBy](groupBy.md) or [pivot](pivot.md).

## Column accessors

`ColumnAccessors` are used for [typed data access](columnAccessorsApi.md) in [`DataFrame`](DataFrame.md). `ColumnAccessor` stores column [`name`](#properties) (for top-level columns) or column path (for nested columns), has type argument that corresponds to [`type`](#properties) of thep column, but it doesn't contain any actual data.

<!---FUN columnAccessorsUsage-->

```kotlin
val age by column<Int>()

// Access fourth cell in the "age" column of dataframe `df`.
// This expression returns `Int` because variable `age` has `ColumnAccessor<Int>` type.
// If dataframe `df` has no column "age" or column "age" has type which is incompatible with `Int`,
// runtime exception will be thrown.
df[age][3] + 5

// Access first cell in the "age" column of dataframe `df`.
df[0][age] * 2

// Returns new dataframe sorted by age column (ascending)
df.sortBy(age)

// Returns new dataframe with the column "year of birth" added
df.add("year of birth") { 2021 - age }

// Returns new dataframe containing only rows with age > 30
df.filter { age > 30 }
```

<!---END-->

[Column accessors](DataColumn.md#column-accessors) are created by [property delegate](https://kotlinlang.org/docs/delegated-properties.html) `column`. Column [`type`](DataColumn.md#properties) should be passed as type argument, column [`name`](DataColumn.md#properties) will be taken from the variable name.

<!---FUN createColumnAccessor-->

```kotlin
val name by column<String>()
```

<!---END-->

To assign column name explicitly, pass it as an argument.

<!---FUN createColumnAccessorRenamed-->

```kotlin
val accessor by column<String>("complex column name")
```

<!---END-->

You can also create column accessors for [ColumnGroups](DataColumn.md#columngroup) and [FrameColumns](DataColumn.md#framecolumn)

<!---FUN createGroupOrFrameColumnAccessor-->

```kotlin
val columns by columnGroup()
val frames by frameColumn()
```

<!---END-->

To reference nested columns inside [ColumnGroups](DataColumn.md#columngroup), invoke `column<T>()` on accessor to parent [`ColumnGroup`](#columngroup):

<!---FUN createDeepColumnAccessor-->

```kotlin
val name by columnGroup()
val firstName by name.column<String>()
```

<!---END-->

You can also create virtual accessor that doesn't point to a real column but computes some expression on every data access:

<!---FUN columnAccessorComputed-->
<tabs>
<tab title="Properties">

```kotlin
val fullName by column(df) { name.firstName + " " + name.lastName }

df[fullName]
```

</tab>
<tab title="Accessors">

```kotlin
val name by columnGroup()
val firstName by name.column<String>()
val lastName by name.column<String>()

val fullName by column { firstName() + " " + lastName() }

df[fullName]
```

</tab>
<tab title="Strings">

```kotlin
val fullName by column { "name"["firstName"]<String>() + " " + "name"["lastName"]<String>() }

df[fullName]
```

</tab></tabs>
<!---END-->

If expression depends only on one column, you can also use `map`:

<!---FUN columnAccessorMap-->

```kotlin
val age by column<Int>()
val year by age.map { 2021 - it }

df.filter { year > 2000 }
```

<dataFrame src="org.jetbrains.kotlinx.dataframe.samples.api.Create.columnAccessorMap.html"/>
<!---END-->

To convert [`ColumnAccessor`](columnAccessorsApi.md) into [`DataColumn`](DataColumn.md) add values using `withValues` function:

<!---FUN columnAccessorToColumn-->

```kotlin
val age by column<Int>()
val ageCol1 = age.withValues(15, 20)
val ageCol2 = age.withValues(1..10)
```

<!---END-->
[`FrameColumn`](DataColumn.md#framecolumn) may appear after [reading](read.md) from JSON or other hierarchical data structures, or after grouping operations such as [groupBy](groupBy.md) or [pivot](pivot.md).

52 changes: 0 additions & 52 deletions docs/StardustDocs/topics/KPropertiesApi.md
View file
Open in desktop

This file was deleted.

48 changes: 0 additions & 48 deletions docs/StardustDocs/topics/add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,6 @@ rowExpression: DataRow.(DataRow) -> Value
df.add("year of birth") { 2021 - age }
```

</tab>
<tab title="Accessors">

```kotlin
val age by column<Int>()
val yearOfBirth by column<Int>("year of birth")

df.add(yearOfBirth) { 2021 - age }
```

</tab>
<tab title="Strings">

Expand Down Expand Up @@ -96,30 +86,6 @@ df.add {
}
```

</tab>
<tab title="Accessors">

```kotlin
val yob = column<Int>("year of birth")
val lastNameLength = column<Int>("last name length")
val age by column<Int>()
val isAdult = column<Boolean>("is adult")
val fullName = column<String>("full name")
val name by columnGroup()
val details by columnGroup()
val firstName by name.column<String>()
val lastName by name.column<String>()

df.add {
yob from 2021 - age
age gt 18 into isAdult
details from {
lastName.length() into lastNameLength
fullName from { firstName() + " " + lastName() }
}
}
```

</tab>
<tab title="Strings">

Expand Down Expand Up @@ -168,20 +134,6 @@ val personWithCityInfo = df.add {
}
```

</tab>
<tab title="Accessors">

```kotlin
val city by column<String?>()
val personWithCityInfo = df.add {
val cityInfo = city().map { queryCityInfo(it) }
"cityInfo" {
cityInfo.map { it.location } into CityInfo::location
cityInfo.map { it.population } into "population"
}
}
```

</tab>
<tab title="Strings">

Expand Down
Loading
Loading