Skip to content

Migration guide #1631

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

Open
AndreiKingsley wants to merge 3 commits into
base: master
Choose a base branch
from
+166 −1
Open

Migration guide #1631

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b141780
init migration guide
AndreiKingsley Nov 28, 2025
f6c2114
Merge branch 'master' into migration_guide
AndreiKingsley Dec 9, 2025
86a17a4
init 1.0 migration guide; add deprecation and removals
AndreiKingsley Dec 10, 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
4 changes: 3 additions & 1 deletion docs/StardustDocs/d.tree
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -225,5 +225,7 @@
<toc-element topic="_shadow_resources.md" hidden="true"/>
<toc-element topic="Support.md"/>
<toc-element topic="FAQ.md"/>
<toc-element topic="Migration-From-Plugins.md"/>
<toc-element topic="MigrationTo_1_0.md">
<toc-element topic="Migration-From-Plugins.md"/>
</toc-element>
</instance-profile>
163 changes: 163 additions & 0 deletions docs/StardustDocs/topics/MigrationTo_1_0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,163 @@
# Migration to 1.0

## Deprecations and removals

As we move toward version 1.0, many functions have been changed, deprecated, or removed.
This section provides a complete overview of all API changes to help you migrate to 1.0.

### Migration to Deephaven CSV

All CSV (as well as TSV) IO was migrated to a new, fast, and efficient
[Deephaven CSV](https://github.com/deephaven/deephaven-csv) implementation.
It significantly improves CSV IO performance and brings many new parametrization options.

All related methods are now located in the separate [`dataframe-csv`](Modules.md#dataframe-csv) module
(which is included by default in the general [`dataframe`](Modules.md#dataframe-general) artifact
and in `%use dataframe` in [Kotlin Notebook](SetupKotlinNotebook.md)).

Functions were also renamed to the correct CamelCase spelling.

All new functions keep the same arguments as before and additionally introduce new ones.
Also, [there are new arguments that expose Deephaven CSV features](read.md#unlocking-deephaven-csv-features).


See [](read.md#read-from-csv).

> All outdated CSV IO functions raise `WARNING` in 1.0 and will raise `ERROR` in 1.1.

| 0.15 | 1.0 |
|-------------------------------------------------|-------------------------------------------------|
| `CSV`/`TSV` | `CsvDeephaven`/`TsvDeephaven` |
| `DataFrame.readCSV(..)`/`DataFrame.readTSV(..)` | `DataFrame.readCsv(..)`/`DataFrame.readTsv(..)` |
| `DataFrame.read(delimeter=.., ..)` | `DataFrame.readCsv(delimeter=.., ..)` |
| `df.writeCSV(..)`/`df.writeTSV(..)` | `df.writeCsv(..)`/`df.writeTsv(..)` |
| `df.toCSV(..)` | `df.toCsvStr(..)` |

### Migration to Standard Library `Instant`

Since Kotlin 2.1.20,
[`Instant` is now part of the standard library](https://kotlinlang.org/docs/whatsnew2120.html#new-time-tracking-functionality)
(as `kotlin.time.Instant`).
You can still use the old (deprecated) `kotlinx.datetime.Instant` type, but its support will be removed in Kotlin DataFrame 1.1.

> New `Instant` in the Kotlin Standard Library becomes stable in 2.3.0.
> In earlier versions, all related operations should be marked with the `@OptIn(ExperimentalTime::class)` annotation.
{style="note"}

For now, each `Instant`-related operation has been split into two new ones —
one for the new stdlib `kotlin.time.Instant` and one for the old deprecated `kotlinx.datetime.Instant`.
The behavior of old operations remains unchanged: they work with `kotlinx.datetime.Instant` and raise `ERROR` in 1.0.
In version 1.1, they will be returned and will operate on the new stdlib `kotlin.time.Instant`.

Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

important to mention ParserOptions.parseExperimentalInstant

<table>
<tr>
<th>0.15</th>
<th>1.0</th>
<th>Note</th>
</tr>
<tr>
<td rowspan="2"><code>col.convertToInstant()</code></td>
<td><code>col.convertToDeprecatedInstant()</code></td>
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
</tr>
<tr>
<td><code>col.convertToStdlibInstant()</code></td>
<td>Will be renamed back into <code>convertToInstant() in 1.1</code></td>
</tr>
<tr>
<td rowspan="2"><code>df.convert { columns }.toInstant()</code></td>
<td><code>df.convert { columns }.convertToDeprecatedInstant()</code></td>
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
</tr>
<tr>
<td><code>df.convert { columns }.convertToStdlibInstant()</code></td>
<td>Will be renamed back into <code>convertToInstant() in 1.1</code></td>
</tr>
<tr>
<td rowspan="2"><code>ColType.Instant</code></td>
<td><code>ColType.DeprecatedInstant</code></td>
<td><code>WARNING</code> in 1.0, <code>ERROR</code> in 1.1</td>
</tr>
<tr>
<td><code>ColType.StdlibInstant</code></td>
<td>Will be renamed back into <code>Instant</code> in 1.1</td>
</tr>
</table>

#### Deprecation of `cols()` in Columns Selection DSL

`cols()` overloads without arguments, which select all columns of a DataFrame or
all subcolumns inside a column group in the [Columns Selection DSL](ColumnSelectors.md),
are deprecated in favor of `all()` and `allCols()` respectively.
These replacements allow the [Compiler Plugin](Compiler-Plugin.md) to fully support such selections.

`colsAtAnyDepth()`, `colsInGroups()`, and `single()` overloads with a `predicate` argument
that filters columns are also deprecated for better Compiler Plugin support.
Use `.filter(predicate)` for filtering instead.

| 0.15 | 1.0 |
|--------------------------------------------------|------------------------------------------------------------------|
| `df.select { cols() }` | `df.select { all() }` |
| `df.select { colGroup.cols() }` | `df.select { colGroup.allCols() }` |
| `df.select { colsAtAnyDepth { predicate } }` | `df.select { colsAtAnyDepth().filter { predicate } }` |
| `df.select { colsInGroups { predicate } }` | `df.select { colsInGroups().filter { predicate } }` |
| `df.select { single { predicate } }` | `df.select { cols().filter { predicate }.single() }` |
| `df.select { colGroup.singleCol { predicate } }` | `df.select { colGroup.allCols().filter { predicate }.single() }` |
| `df.select { colSet.single { predicate } }` | `df.select { colSet.filter { predicate }.single() }` |



Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do we also want to mention new functions/arguments? Like move {}.toStart(insideGroup=true)?

Copy link
Collaborator Author

@AndreiKingsley AndreiKingsley Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe this should be in "New Features" section.

### Removed functions and classes

The next functions and classes raise `ERROR` in 1.0 and will be removed in 1.1.

| 0.15 | 1.0 | Reason |
|----------------------------------------------------------------|------------------------------------------------------------------------------|----------------------------------------|
| `DataColumn.createFrameColumn(name, df, startIndices)` | `df.chunked(name, startIndices)` | Replaced with an other function. |
Copy link
Collaborator

@Jolanrensen Jolanrensen Dec 11, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

*another

| `DataColumn.createWithTypeInference(name, values, nullable)` | `DataColumn.createByInference(name, values, TypeSuggestion.Infer, nullable)` | Replaced with an other function. |
| `DataColumn.create(name, values, infer)` | `DataColumn.createByType(name, values, infer)` | Replaced with an other function. |
| `col.isComparable()` | `col.valuesAreComparable()` | Renamed to better reflect its purpose. |
| `df.minus { columns }` | `df.remove { columns }` | Replaced with an other function. |
| `df.move { columns }.toLeft()`/`df.moveToLeft{ columns }` | `df.move { columns }.toStart()`/`df.moveToStart { columns }` | Renamed to better reflect its purpose. |
| `df.move { columns }.toRight()`/`df.moveToRight{ columns }` | `df.move { columns }.toEnd()`/`df.moveToEnd{ columns }` | Renamed to better reflect its purpose. |
| `row.rowMin()`/`row.rowMinOrNull()` | `row.rowMinOf()`/`row.rowMinOfOrNull()` | Renamed to better reflect its purpose. |
| `row.rowMax()`/`row.rowMaxOrNull()` | `row.rowMaxOf()`/`AnyRow.rowMaxOfOrNull()` | Renamed to better reflect its purpose. |
| `row.rowPercentile()`/`row.rowPercentileOrNull()` | `row.rowPercentileOf()`/`row.rowPercentileOfOrNull()` | Renamed to better reflect its purpose. |
| `row.rowMedian()`/`row.rowMedianOrNull()` | `row.rowMedianOf()`/`row.rowMedianOfOrNull()` | Renamed to better reflect its purpose. |
| `df.convert { columns }.to { converter }` | `df.convert { columns }.asColumn { converter }` | Renamed to better reflect its purpose. |
| `df.toHTML(..)`/`df.toStandaloneHTML()` | `df.toHtml(..)`/`df.toStandaloneHtml()` | Renamed to the correct CamelCase. |
| `df.writeHTML()` | `df.writeHtml()` | Renamed to the correct CamelCase. |
| `asURL(fileOrUrl)`/`isURL(path)` | `asUrl(fileOrUrl)`/`isUrl(path)` | Renamed to the correct CamelCase. |
| `df.convert { columns }.toURL()`/`df.convertToURL { columns }` | `df.convert { columns }.toUrl()`/`df.convertToUrl { columns }` | Renamed to the correct CamelCase. |
| `df.filterBy(column)` | `df.filter { column }` | Replaced with an other function. |
| `FormattingDSL` | `FormattingDsl` | Renamed to the correct CamelCase. |
| `RGBColor` | `RgbColor` | Renamed to the correct CamelCase. |
| `df.insert(column).after(columnPath)` | `df.insert(column).after { columnPath }` | Replaced with an other function. |
| `CompareResult.Equals` / `CompareResult.isEqual()` | `CompareResult.Matches` / `CompareResult.matches()` | Renamed to better reflect its purpose. |
| `CompareResult.isSuperOrEqual()` | `CompareResult.isSuperOrMatches()` | Renamed to better reflect its purpose. |

The next functions and classes raise `WARNING` in 1.0 and `ERROR` in 1.1.

| 0.15 | 1.0 | Reason |
|----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------|
| `df.split { columns }.default(..)` / `df.split { columns }.into(..)` / `df.split { columns }.inward(..)` | `df.split { columns }.by(..).default(..)` / `df.split { columns }.by(..).into(..)` / `df.split { columns }.by(..).inward(..)` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
| `dataFrameOf(header, values)` | `dataFrameOf(header).withValues(values)` | Replaced with an other function. |
| `df.generateCode(..)` | `df.generateInterfaces(..)` | Replaced with an other function. |
| `df.select { mapToColumn(name, infer) { body } }` | `df.select { expr(name, infer) { body } }` | Removed duplicated functionality. |
| `stringCol.length()` | `stringCol.map { it?.length ?: 0 }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
| `stringCol.lowercase()` / `stringCol.uppercase()` | `stringCol.map { it?.lowercase() }` / `stringCol.map { it?.uppercase() }` | Removed a shortcut to clarify the behaviour; Only for `String` columns. |
| `df.add(columns)` / `df.add(dataframes)` | `df.addAll(columns)` / `df.addAll(dataframes)` | Renamed to to improve completion. |
| `row.isEmpty()` / `row.isNotEmpty()` | `row.values().all { it == null }` / `row.values().all { it == null }` | Removed a shortcut to clarify the behaviour; |
| `row.getRow(index)` / `row.getRowOrNull(index)` / `row.getRows(indices)` | `row.df().getRow(index)` / `row.df().getRowOrNull(index)` / `row.df().getRows(indices)` | Removed a shortcut to clarify the behaviour; |
| `df.copy()` | `df.columns().toDataFrame().cast()` | Removed a shortcut to clarify the behaviour; |
| `KeyValueProperty<T>` | `NameValueProperty<T>` | Removed duplicated functionality. |

<!--TODO (https://github.com/Kotlin/dataframe/issues/1630)

## Modules

## Compiler Plugin

## Changes in working with JDBC

-->