Add String API page, update access API overview and EP API by AndreiKingsley · Pull Request #1664 · Kotlin/dataframe

AndreiKingsley · 2026-01-21T20:17:18Z

Jolanrensen · 2026-01-22T19:28:26Z


-The String API is the simplest and unsafest of them all. The main advantage of it is that it can be
-used at any time, including when accessing new columns in chain calls. So we can write something like:
+Also, when using in the [IntelliJ IDEA](https://www.jetbrains.com/idea/) in the 


in the Intellij in the Gradle... the code compeltion?...please check this entire sentence again XD

Jolanrensen · 2026-01-22T19:29:04Z

+However, note that after operations in which resulting columns cannot be inferred 
+by the Compiler Plugin (for example, [`pivot`](pivot.md)),
+extension properties can't be inferred automatically either. For such operations, 
+you can use [`cast`](cast.md) to define a new data schema or use the String API. 


same note as before

Jolanrensen · 2026-01-22T19:29:52Z

+# String API
+
+The String API is the most basic and straightforward API
+for selecting columns in the Kotlin DataFrame [operations](operations.md).


"The String API is the most basic and straightforward API for selecting columns in Kotlin DataFrame operations."

Maybe you can feel it better if you reorder the sentence like this:
"In Kotlin DataFrame operations, the String API is the most basic and straightforward API for selecting columns."

Jolanrensen · 2026-01-22T19:32:16Z

+```
+
+The String API can also be used in any operation with a [row expression](DataRow.md#row-expressions).
+You can access row values in specific columns by invoking `String` values with their names:


the way you write this, it's like the String invocation method only works for Row expressions, however, it also works fine in the columns selection dsl

Ok, I add a mention about usage in CS DSL as well!

koperagen · 2026-01-23T11:28:11Z

How about we make 2,5 groups of String "accessors".
Operator style syntax for String column accessor

df.select { "col"() }, df.select { "col"<String>() }
df.select { "col"["nestedCol"]() }, df.select { "col"["nestedCol"]<String>() }
df.select { "col"() and "anotherCol"<String>() }

Their DataRow counterpart:

df.filter { "col"() } - looks like we don't/can't have "untyped" invoke, in which case type is inferred as Boolean here. Not like in CS DSL

df.filter { "col"<String>() == "abc" }
df.filter { "col"["nestedCol"]<String>() == "abc" }

Compact operator syntax for "and" operation (but to specify type need to fallback to invoke):

df.select { "col" and "anotherCol" }
df.select {  "col"["nestedCol"] and "anotherCol" }

.. and some other operations, right?

Function style syntax for String column accessor

df.select { col("col") }, df.select { col<String>("col") }
df.select { colGroup("col").col("nested") }, df.select { colGroup("col").col<String>("nested") }
df.select { cols("a", "b") }

Their DataRow counterpart:

df.filter { get("col") == "abc" }, or df.filter { it["col"] == "abc" }, df.filter { getValue<String>("col") == "abc" }
df.filter { getColumnGroup("col").getValue<String>("nestedCol") }

Or maybe we should prefer pathOf here? We should decide! Its syntax seems incomplete though, not fully thought through:

df.select { col(pathOf("col", "nestedCol")) }
df.filter {
    pathOf("abc").getValue(it) == "abc"
}

Hopefully it comprehensively covers how one might use String API in CS DSL to achieve most likely desired results, and option to choose a preference
@Jolanrensen @AndreiKingsley

koperagen · 2026-01-23T16:03:19Z

I recalled another useful style that goes hand in hard with String API: Int indexes :) Check this out:
#1666

Jolanrensen · 2026-02-20T14:39:28Z

+// Select the "firstName" column from the "fullName" column group
+// and the "age" column
+df.select { "fullName"["firstName"]<String>() and "age"<Int>() }
+// Takes only rows where the


could you add an extra newline in between these?

Jolanrensen · 2026-02-20T14:47:39Z

-    }
+// Get "fullName" column
+df.fullName
+// Rename "fullName" column into "name"


same here, a blank line after expressions make them easier to read and group

Jolanrensen · 2026-02-20T14:50:55Z

+<!---FUN simpleSelect-->
+
+```kotlin
+// Select a sub-dataframe with the "name" and "info" columns


a "sub-dataframe"? I'm not sure about that name. It might draw incorrect parallels with dataframe views from pandas and the like. Maybe "Create a new dataframe with the "name" and "info" columns from df"?

Jolanrensen · 2026-02-20T14:52:49Z

+
+<!---END-->
+
+Select the "age" subcolumn of the "info" column group and the "name" column


of from. I like "from" better because it hints you're "taking it out"

Jolanrensen · 2026-02-20T14:54:32Z

+
+<!---END-->
+
+Calculate the mean value of the ("info"->"age") column; specify the column type as a `col` type argument


I'm not sure about the "->" I think in logs we use a different notation for subcolumns, I think it was with a "/", but I'm not sure

Jolanrensen · 2026-02-20T14:56:33Z

+
+### Invoked String API
+
+> This API is outdated and may be hard to read and refactor;


That's an opinion ;P

Jolanrensen · 2026-02-20T14:56:44Z

+### Invoked String API
+
+> This API is outdated and may be hard to read and refactor;
+> it may be changed in the future.


this is fine

Jolanrensen · 2026-02-20T14:57:52Z

+
+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't specify the column kind in this case, but you can access nested columns using the 


You can, with <DataRow<*>> or <DataFrame<*>>. But it's not as obvious

Jolanrensen · 2026-02-20T14:58:32Z

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


I'd only use {} if you have more than 1 column :)

but then it would be the same example as the first... okay, you can keep it like this

AndreiKingsley added 2 commits January 21, 2026 23:30

Add String API page and update access API overview

0787a59

update info in extension properties API

1d598c2

AndreiKingsley requested review from Jolanrensen and koperagen January 21, 2026 20:17

AndreiKingsley changed the title ~~Add String API page and update access API overview + EP API~~ Add String API page, update access API overview and EP API Jan 21, 2026

Jolanrensen requested changes Jan 22, 2026

View reviewed changes

AndreiKingsley added 2 commits January 23, 2026 18:55

access apis website docs refactor

5e097df

access apis website docs fixes

cc59dd8

zaleslaw self-requested a review January 26, 2026 14:23

AndreiKingsley added 2 commits January 28, 2026 20:56

refine String API docs for clarity and consistency

bd986d5

add AccessApis.kt examples and refine String API documentation

972b819

AndreiKingsley marked this pull request as draft February 16, 2026 11:58

Jolanrensen reviewed Feb 16, 2026

View reviewed changes

Comment thread docs/StardustDocs/topics/extensionPropertiesApi.md Outdated

AndreiKingsley added 7 commits February 19, 2026 12:49

refine String API documentation

982dd5e

Merge branch 'master' into string-api-docs

581e998

string api korro

79c271e

apis korro examples

da253f8

apis korro fix

0984ad6

ktlint fix

c5ee9da

access apis korro update

c0dcd89

AndreiKingsley marked this pull request as ready for review February 19, 2026 11:29

AndreiKingsley requested a review from Jolanrensen February 19, 2026 11:30

string api ep fix

04e61cf

Jolanrensen reviewed Feb 20, 2026

View reviewed changes

Jolanrensen approved these changes Feb 20, 2026

View reviewed changes

AndreiKingsley added 3 commits February 23, 2026 16:31

refine String API docs for clarity and consistency

d803e34

update String API docs korro

f6387c1

update Access APIs docs korro

d406935

AndreiKingsley merged commit fcb738c into master Feb 23, 2026
3 checks passed

AndreiKingsley deleted the string-api-docs branch February 23, 2026 12:36

AndreiKingsley restored the string-api-docs branch February 23, 2026 13:57


		<!---END-->

		Select the "age" subcolumn of the "info" column group and the "name" column


		<!---END-->

		Calculate the mean value of the ("info"->"age") column; specify the column type as a `col` type argument


		### Invoked String API

		> This API is outdated and may be hard to read and refactor;

Conversation

AndreiKingsley commented Jan 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

koperagen commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

koperagen commented Jan 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Jolanrensen Feb 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

AndreiKingsley commented Jan 21, 2026 •

edited

Loading

koperagen commented Jan 23, 2026 •

edited

Loading

koperagen commented Jan 23, 2026 •

edited

Loading

Jolanrensen Feb 20, 2026 •

edited

Loading