ajet/df-research
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init research

Browse Source
This commit is contained in:
Adam Jeniski
2026-02-08 11:20:43 -10:00
commit bdf064f54d
3041 changed files with 1592200 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
dataframe/docs/StardustDocs/topics/setup/Modules.md
Vendored
+614
View File
@@ -0,0 +1,614 @@
# Modules
Kotlin DataFrame is composed of modules, allowing you to include only the functionality you need.
In addition, Kotlin DataFrame provides several [plugins](#plugins)
that significantly enhance the development experience
— making it more convenient, powerful, and enjoyable to work with.
<table>
<thead>
<tr>
<th>Module</th>
<th>Function</th>
</tr>
</thead>
<tbody>
<tr><td colspan="2"><strong><a href="#dataframe-general">General</a></strong></td></tr>
<tr>
<td><a href="#dataframe-general"><code>dataframe</code></a></td>
<td>General artifact – combines all core and IO artifacts except experimental ones.</td>
</tr>
<tr>
<td colspan="2"><strong><a href="#core-modules">Core</a></strong></td></tr>
<tr>
<td><code><a href="#dataframe-core">dataframe-core</a></code></td>
<td>The <a href="DataFrame.md">DataFrame</a> API and its implementation.</td>
</tr>
<tr><td colspan="2"><strong><a href="#io-modules">IO</a></strong></td></tr>
<tr>
<td><code><a href="#dataframe-json">dataframe-json</a></code></td>
<td>Provides support for JSON format writing and reading.</td>
</tr>
<tr>
<td><code><a href="#dataframe-csv">dataframe-csv</a></code></td>
<td>Provides support for CSV format writing and reading.</td>
</tr>
<tr>
<td><code><a href="#dataframe-excel">dataframe-excel</a></code></td>
<td>Provides support for XSL/XLSX format writing and reading.</td>
</tr>
<tr>
<td><code><a href="#dataframe-jdbc">dataframe-jdbc</a></code></td>
<td>Provides support for JDBC data sources reading.</td>
</tr>
<tr>
<td><code><a href="#dataframe-arrow">dataframe-arrow</a></code></td>
<td>Provides support for <a href="https://arrow.apache.org">Apache Arrow</a> format writing and reading. Provides support for reading <a href="https://parquet.apache.org/">Apache Parquet</a> files through <a href="https://arrow.apache.org/docs/java/dataset.html">Apache Arrow Dataset</a></td>
</tr>
<tr><td colspan="2"><strong><a href="#experimental-modules">Experimental modules</a></strong></td></tr>
<tr>
<td><code><a href="#dataframe-geo">dataframe-geo</a></code></td>
<td>Provides a new API for working with geospatial data and IO for geographic formats (GeoJSON, Shapefile).</td>
</tr>
<tr>
<td><code><a href="#dataframe-openapi">dataframe-openapi</a></code></td>
<td>Provides support for <a href="https://www.openapis.org">OpenAPI JSON format</a> reading and writing.</td>
</tr>
<tr>
<td><code><a href="#dataframe-openapi-generator">dataframe-openapi-generator</a></code></td>
<td>Provides <a href="schemas.md">schema generation</a> from OpenAPI specifications. Requires <code>dataframe-openapi</code>.</td>
</tr>
<tr><td colspan="2"><strong><a href="#plugins">Plugins</a></strong></td></tr>
<tr>
<td><code><a href="#kotlin.plugin.dataframe">kotlin.plugin.dataframe</a></code></td>
<td>Kotlin compiler plugin. Provides compile-time <a href="extensionPropertiesApi.md">extension properties</a> generation.
</td>
</tr>
<tr>
<td><code><a href="#kotlinx.dataframe">kotlinx.dataframe</a></code></td>
<td>Gradle plugin. Provides <a href="schemas.md">schemas generation</a> using Gradle.</td>
</tr>
<tr>
<td><code><a href="#ksp-plugin">kotlinx.dataframe:symbol-processor-all</a></code></td>
<td>KSP plugin. Provides <a href="schemas.md">schemas generation</a> using KSP.</td>
</tr>
</tbody>
</table>
## Configure the repository
All Kotlin DataFrame modules are available from the Maven Central repository.
To use them, add the appropriate dependency into your repositories mapping:
<tabs>
<tab title="Kotlin DSL">
```kotlin
repositories {
mavenCentral()
}
```
</tab>
<tab title="Groovy DSL">
```kotlin
repositories {
mavenCentral()
}
```
</tab>
</tabs>
## `dataframe` - general Kotlin DataFrame dependency {id="dataframe-general"}
General-purpose artifact that includes all [core](#core-modules) and [IO](#io-modules) modules.
Does **not** include any [experimental modules](#experimental-modules).
Recommended if you don’t need fine-grained control over individual module dependencies.
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe:%dataFrameVersion%'
}
```
</tab>
</tabs>
## Core Kotlin DataFrame modules {id="core-modules"}
#### `dataframe-core`
The core [DataFrame](DataFrame.md) API and its implementation.
Includes all core functionality for working with data structures, expressions, schema management, and operations.
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-core:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-core:%dataFrameVersion%'
}
```
</tab>
</tabs>
## IO Kotlin DataFrame modules {id="io-modules"}
#### `dataframe-json` {id="dataframe-json"}
Provides all logic for DataFrame to be able to work with
JSON data sources; [reading](https://kotlin.github.io/dataframe/read.html#read-from-json)
and [writing](https://kotlin.github.io/dataframe/write.html#writing-to-json).
It's based on [Kotlinx Serialization](https://github.com/Kotlin/kotlinx.serialization).
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-json:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-json:%dataFrameVersion%'
}
```
</tab>
</tabs>
#### `dataframe-csv` {id="dataframe-csv"}
Provides support for reading and writing CSV files.
Supports standard CSV format features such as delimiters, headers, and quotes.
Based on high-performance [Deephaven CSV](https://github.com/deephaven/deephaven-csv).
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%'
}
```
</tab>
</tabs>
Note that `dataframe-json` is included with `dataframe-csv` by default.
This is to support JSON structures inside CSV files.
If you don't need this functionality, you can exclude it like so:
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%") {
exclude("org.jetbrains.kotlinx", "dataframe-json")
}
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation('org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%') {
exclude group: 'org.jetbrains.kotlinx', module: 'dataframe-json'
}
}
```
</tab>
</tabs>
#### `dataframe-excel` {id="dataframe-excel"}
Provides support for reading and writing Excel files (`.xls` and `.xlsx`).
Compatible with standard spreadsheet editors and supports embedded structured data.
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-excel:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-excel:%dataFrameVersion%'
}
```
</tab>
</tabs>
Note that `dataframe-json` is included with `dataframe-excel` by default.
This is to support JSON structures inside Excel files.
If you don't need this functionality, you can exclude it like so:
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-excel:%dataFrameVersion%") {
exclude("org.jetbrains.kotlinx", "dataframe-json")
}
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation('org.jetbrains.kotlinx:dataframe-excel:%dataFrameVersion%') {
exclude group: 'org.jetbrains.kotlinx', module: 'dataframe-json'
}
}
```
</tab>
</tabs>
#### `dataframe-jdbc` {id="dataframe-jdbc"}
Provides all logic for DataFrame to be able to work with
SQL databases that implement the JDBC protocol.
See [Read from SQL databases](https://kotlin.github.io/dataframe/readsqldatabases.html) for more information
about how to use it.
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-jdbc:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-jdbc:%dataFrameVersion%'
}
```
</tab>
</tabs>
#### `dataframe-arrow` {id="dataframe-arrow"}
Provides all logic and tests for DataFrame to be able to work with
[Apache Arrow](https://arrow.apache.org).
See [Read Apache Arrow formats](https://kotlin.github.io/dataframe/read.html#read-apache-arrow-formats) and
[Writing to Apache Arrow formats](https://kotlin.github.io/dataframe/write.html#writing-to-apache-arrow-formats)
for more information about how to use it.
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-arrow:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-arrow:%dataFrameVersion%'
}
```
</tab>
</tabs>
## Experimental Kotlin DataFrame modules {id="experimental-modules"}
These modules are experimental and may be unstable.
#### `dataframe-geo`
Provides a new API for working with geospatial data,
including reading and writing geospatial formats (GeoJSON, Shapefile),
and performing geometry-aware operations.
See [Geo guide](https://kotlin.github.io/kandy/geo-plotting-guide.html) for more details and examples.
Requires [OSGeo Repository](https://repo.osgeo.org).
<tabs>
<tab title="Kotlin DSL">
```kotlin
repositories {
maven("https://repo.osgeo.org/repository/release")
}
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-geo:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
repositories {
maven {
url 'https://repo.osgeo.org/repository/release'
}
}
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-geo:%dataFrameVersion%'
}
```
</tab>
</tabs>
#### `dataframe-openapi`
Provides functionality to support auto-generated data schemas from OpenAPI 3.0.0 specifications.
This module is a companion to [`dataframe-openapi-generator`](#dataframe-openapi-generator):
- `dataframe-openapi-generator` is used internally by the Gradle plugin and Jupyter integration
to generate data schemas from OpenAPI specs.
In the Gradle plugin, it powers the `dataschemas {}` DSL and the `@file:ImportDataSchema()` annotation.
In Jupyter, it enables the `importDataSchema()` function.
- `dataframe-openapi` must be added as a dependency to the user project in order to use those generated data schemas.
See:
- [Import OpenAPI Schemas in Gradle project](https://kotlin.github.io/dataframe/schemasimportopenapigradle.html)
- [Import Data Schemas, e.g. from OpenAPI, in Jupyter](https://kotlin.github.io/dataframe/schemasimportopenapijupyter.html)
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-openapi:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-openapi:%dataFrameVersion%'
}
```
</tab>
</tabs>
#### `dataframe-openapi-generator`
Provides the logic and tooling necessary to import OpenAPI 3.0.0 specifications
as auto-generated data schemas for Kotlin DataFrame.
This module works in conjunction with [`dataframe-openapi`](#dataframe-openapi):
- `dataframe-openapi-generator` is used internally by the Gradle plugin and Jupyter integration
to generate data schemas from OpenAPI specifications.
- In Gradle, it enables the `dataschemas {}` DSL and the `@file:ImportDataSchema()` annotation.
- In Jupyter, it powers the `importDataSchema()` function.
- `dataframe-openapi` must be added as a dependency to the user project to actually use the generated schemas.
See:
- [Import OpenAPI Schemas in Gradle project](https://kotlin.github.io/dataframe/schemasimportopenapigradle.html)
- [Import Data Schemas, e.g. from OpenAPI, in Jupyter](https://kotlin.github.io/dataframe/schemasimportopenapijupyter.html)
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe-openapi-generator:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe-openapi-generator:%dataFrameVersion%'
}
```
</tab>
</tabs>
## Plugins
<!-- TODO improve compiler plugin setup after release--->
#### `kotlin.plugin.dataframe` — Kotlin DataFrame Compiler Plugin {id="kotlin.plugin.dataframe"}
[Kotlin DataFrame Compiler Plugin](Compiler-Plugin.md) enables automatic generation of
[extension properties](extensionPropertiesApi.md) and updates [data schemas](schemas.md)
on-the-fly in Gradle projects, making development with Kotlin DataFrame faster,
more convenient, and fully type- and name-safe.
> Requires Kotlin 2.2.20-Beta1 or higher.
> { style = "note" }
To enable the plugin in your Gradle project, add it to the `plugins` section:
<tabs>
<tab title="Kotlin DSL">
```kotlin
plugins {
kotlin("plugin.dataframe") version "%compilerPluginKotlinVersion%"
}
```
</tab>
<tab title="Groovy DSL">
```groovy
plugins {
id 'org.jetbrains.kotlin.plugin.dataframe' version '%compilerPluginKotlinVersion%'
}
```
</tab>
</tabs>
Due to [this issue](https://youtrack.jetbrains.com/issue/KT-66735), incremental compilation must be disabled for now.
Add the following line to your `gradle.properties` file:
```properties
kotlin.incremental=false
```
Published as a Kotlin official plugin.
[Source code is available in the Kotlin repository](https://github.com/JetBrains/kotlin/tree/master/plugins/kotlin-dataframe).
#### `kotlinx.dataframe` – Gradle Plugin {id="kotlinx.dataframe"}
> The current Gradle plugin is **under consideration for deprecation**
> and may be officially marked as deprecated in future releases.
>
> At the moment, **[data schema generation is handled via dedicated methods](DataSchemaGenerationMethods.md)** instead of relying on the plugin.
{style="warning"}
The Gradle plugin allows generating [data schemas](schemas.md) from samples of data
(of supported formats) like JSON, CSV, Excel files, or URLs, as well as from data fetched from SQL databases
using Gradle.
See the [Gradle Plugin Reference](Gradle-Plugin.md) for installation
and usage instructions in Gradle projects.
> By default, the Gradle plugin also applies the [KSP plugin](#ksp-plugin).
<tabs>
<tab title="Kotlin DSL">
```kotlin
plugins {
id("org.jetbrains.kotlinx.dataframe") version "%dataFrameVersion%"
}
```
</tab>
<tab title="Groovy DSL">
```groovy
plugins {
id 'org.jetbrains.kotlinx.dataframe' version '%dataFrameVersion%'
}
```
</tab>
</tabs>
#### `kotlinx.dataframe:symbol-processor-all` – KSP Plugin {id="ksp-plugin"}
> The KSP plugin is **not compatible with [KSP2](https://github.com/google/ksp?tab=readme-ov-file#ksp2-is-here)**
> and may **not work properly with Kotlin 2.1 or newer**.
>
> At the moment, **[data schema generation is handled via dedicated methods](DataSchemaGenerationMethods.md)** instead of relying on the plugin.
{style="warning"}
The Gradle plugin allows generating [data schemas](schemas.md) from samples of data
(of supported formats) like JSON, CSV, Excel files, or URLs, as well as from data fetched from SQL databases
using Kotlin Symbol Processing (KSP).
This is useful for projects where you prefer or require schema generation at the source level.
See [Data Schemas in Gradle Projects](schemasGradle.md) for usage details.
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
ksp("org.jetbrains.kotlinx.dataframe:symbol-processor-all:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
ksp 'org.jetbrains.kotlinx.dataframe:symbol-processor-all:%dataFrameVersion%'
}
```
</tab>
</tabs>
dataframe/docs/StardustDocs/topics/setup/Setup.md
Vendored
+39
View File
@@ -0,0 +1,39 @@
[//]: # (title: Setup Kotlin DataFrame)
<web-summary>
Install Kotlin DataFrame in your preferred environment — Kotlin Notebook, Android, Jupyter, or Datalore
— and start working with data right away.
</web-summary>
<card-summary>
Install Kotlin DataFrame in your preferred environment — Kotlin Notebook, Gradle, Android, Jupyter, or Datalore
— and start working with data right away.
</card-summary>
<link-summary>
Step-by-step setup guide for using Kotlin DataFrame in different environments like Kotlin Notebook, Android, and Jupyter.
</link-summary>
Kotlin DataFrame is supported in multiple environments — choose the one that suits you best and follow the setup steps.
- [**Setup in Kotlin Notebook**](SetupKotlinNotebook.md) — one-line Kotlin DataFrame setup for powerful interactive
[Kotlin notebooks in IntelliJ IDEA and Android Studio](https://kotlinlang.org/docs/kotlin-notebook-overview.html).
No configuration required, full IDE support.
Perfect for learning Kotlin DataFrame basics and experimenting, and a great professional tool
for [data analysis](https://kotlinlang.org/docs/data-analysis-overview.html).
- [**Setup in Gradle**](SetupGradle.md) — add Kotlin DataFrame to your Gradle project for convenient data handling
in your Kotlin applications.
- [**Setup in Maven**](SetupMaven.md) — add Kotlin DataFrame to your Maven project for convenient data handling
in your Kotlin applications.
- [**Setup on Android**](SetupAndroid.md) — use Kotlin DataFrame in your Android apps to simplify local data processing
and transformation.
- [**Setup on Datalore**](SetupDatalore.md) — run Kotlin DataFrame in
[JetBrains Datalore](https://www.jetbrains.com/datalore/) notebooks,
great for sharing and remote collaboration.
- [**Setup in Jupyter**](SetupJupyter.md) — integrate Kotlin DataFrame
into interactive notebooks using the Kotlin Jupyter kernel.
dataframe/docs/StardustDocs/topics/setup/SetupAndroid.md
Vendored
+145
View File
@@ -0,0 +1,145 @@
[//]: # (title: Setup Kotlin DataFrame on Android)
<web-summary>
Integrate Kotlin DataFrame into your Android app using the standard JVM dependency and simple Gradle configuration.
</web-summary>
<card-summary>
Set up Kotlin DataFrame in Android — configure it easily using Gradle and start working with structured data.
</card-summary>
<link-summary>
How to use Kotlin DataFrame in your Android project with Gradle setup and compiler plugin support.
</link-summary>
> See an [Android project example](https://github.com/Kotlin/dataframe/tree/master/examples/android-example).
Kotlin DataFrame doesn't provide a dedicated Android artifact yet,
but you can add the Kotlin DataFrame JVM dependency to your Android project with minimal configuration:
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
// Core Kotlin DataFrame API, CSV and JSON IO.
// See custom Gradle setup:
// https://kotlin.github.io/dataframe/setupcustomgradle.html
implementation("org.jetbrains.kotlinx:dataframe-core:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-json:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%")
// You can add any additional IO modules you like, except for 'dataframe-arrow'.
// Apache Arrow is not supported well on Android.
}
android {
defaultConfig {
minSdk = 21
}
// Requires Java 8 or higher
compileOptions {
sourceCompatibility = JavaVersion.VERSION_1_8
targetCompatibility = JavaVersion.VERSION_1_8
}
kotlinOptions {
jvmTarget = "1.8"
}
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile> {
kotlinOptions.jvmTarget = "1.8"
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
// Core Kotlin DataFrame API, CSV and JSON IO.
// See custom Gradle setup:
// https://kotlin.github.io/dataframe/setupcustomgradle.html
implementation 'org.jetbrains.kotlinx:dataframe-core:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-json:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%'
// You can add any additional IO modules you like, except for 'dataframe-arrow'.
// Apache Arrow is not supported well on Android.
}
android {
defaultConfig {
minSdk 21
}
// Requires Java 8 or higher
compileOptions {
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
kotlinOptions {
jvmTarget = "1.8"
}
}
tasks.withType(org.jetbrains.kotlin.gradle.tasks.KotlinCompile).configureEach {
kotlinOptions.jvmTarget = "1.8"
}
```
</tab>
</tabs>
This setup adds the [Kotlin DataFrame core](Modules.md#dataframe-core)
as well as a subset of the [IO modules](Modules.md#io-modules)
(excluding [experimental ones](Modules.md#experimental-modules)).
For flexible configuration, see [Custom configuration](SetupCustomGradle.md).
## Kotlin DataFrame Compiler Plugin
[Kotlin DataFrame Compiler Plugin](Compiler-Plugin.md) enables automatic generation
of [extension properties](extensionPropertiesApi.md) and updates [data schemas](schemas.md)
on-the-fly in Android projects, making development with Kotlin DataFrame
faster, more convenient, and fully type- and name-safe.
> Requires Kotlin 2.2.20-Beta1 or higher.
> { style = "note" }
To enable the plugin in your Gradle project, add it to the `plugins` section:
<tabs>
<tab title="Kotlin DSL">
```kotlin
plugins {
kotlin("plugin.dataframe") version "%compilerPluginKotlinVersion%"
}
```
</tab>
<tab title="Groovy DSL">
```groovy
plugins {
id 'org.jetbrains.kotlin.plugin.dataframe' version '%compilerPluginKotlinVersion%'
}
```
</tab>
</tabs>
Due to [this issue](https://youtrack.jetbrains.com/issue/KT-66735), incremental compilation must be disabled for now.
Add the following line to your `gradle.properties` file:
```properties
kotlin.incremental=false
```
## Next Steps
* Once Kotlin DataFrame is set up in your Android project, continue with the [](quickstart.md)
to learn the basics of working with DataFrames.
* Explore [detailed guides and real-world examples](Guides-And-Examples.md)
to see how Kotlin DataFrame helps in different data tasks.
* Check out the
[Android project example](https://github.com/Kotlin/dataframe/tree/master/examples/android-example)
and more [IDEA examples on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples).
* Learn more about the [compiler plugin](Compiler-Plugin.md).
dataframe/docs/StardustDocs/topics/setup/SetupCustomGradle.md
Vendored
+71
View File
@@ -0,0 +1,71 @@
# Custom Gradle Configuration
<web-summary>
Add Kotlin DataFrame to your Gradle project and configure only the modules you need for data processing and IO.
</web-summary>
<card-summary>
Modular setup for Kotlin DataFrame — include just the dependencies required for your use case.
</card-summary>
<link-summary>
How to configure Kotlin DataFrame in Gradle using only the relevant modules for your project.
</link-summary>
Kotlin DataFrame is composed of multiple [modules](Modules.md),
allowing you to include only the functionality you need.
To use Kotlin DataFrame in a [Gradle project](SetupGradle.md) — including [Android](SetupAndroid.md) —
you can configure your Gradle buildscript (`build.gradle.kts` or `build.gradle`) with selected dependencies:
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
// Core API and runtime
implementation("org.jetbrains.kotlinx:dataframe-core:%dataFrameVersion%")
// Optional IO format support
implementation("org.jetbrains.kotlinx:dataframe-json:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-excel:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-jdbc:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-arrow:%dataFrameVersion%")
// Experimental features
implementation("org.jetbrains.kotlinx:dataframe-geo:%dataFrameVersion%")
implementation("org.jetbrains.kotlinx:dataframe-openapi:%dataFrameVersion%")
// Only needed if you generate @DataSchema from OpenAPI specs
implementation("org.jetbrains.kotlinx:dataframe-openapi-generator:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
// Core API and runtime
implementation 'org.jetbrains.kotlinx:dataframe-core:%dataFrameVersion%'
// Optional IO format support
implementation 'org.jetbrains.kotlinx:dataframe-json:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-csv:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-excel:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-jdbc:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-arrow:%dataFrameVersion%'
// Experimental features
implementation 'org.jetbrains.kotlinx:dataframe-geo:%dataFrameVersion%'
implementation 'org.jetbrains.kotlinx:dataframe-openapi:%dataFrameVersion%'
// Only needed if you generate @DataSchema from OpenAPI specs
implementation 'org.jetbrains.kotlinx:dataframe-openapi-generator:%dataFrameVersion%'
}
```
</tab>
</tabs>
dataframe/docs/StardustDocs/topics/setup/SetupDatalore.md
Vendored
+39
View File
@@ -0,0 +1,39 @@
[//]: # (title: Setup Kotlin DataFrame on Datalore)
<web-summary>
Set up Kotlin DataFrame on Datalore —
a cloud-based platform with Kotlin notebook support for collaborative data analysis.
</web-summary>
<card-summary>
Set up Kotlin DataFrame on Datalore —
a cloud-based platform with Kotlin notebook support for collaborative data analysis.
</card-summary>
<link-summary>
Set up Kotlin DataFrame on Datalore —
a cloud-based platform with Kotlin notebook support for collaborative data analysis.
</link-summary>
[**Datalore**](https://www.jetbrains.com/datalore/) is a free data analysis platform
with [Kotlin Jupyter notebooks](https://github.com/Kotlin/kotlin-jupyter) support.
It's perfect for collaboration and sharing.
To get started with Kotlin DataFrame on Datalore, first create a Kotlin notebook:
<img src="dataloreCreateNotebook.png" alt="Installation on Datalore" width="705"/>
To use Kotlin DataFrame in the notebook with the Kotlin Jupyter Kernel,
follow the same steps as described in the [Setup in Kotlin Notebook](SetupKotlinNotebook.md).
The easiest way is shown in this screenshot:
<img src="dataloreSetupNotebook.png" alt="Datalore notebook" width="705"/>
## Next Steps
* Once you’ve successfully set up Kotlin DataFrame on Datalore,
you can move on to the [](quickstart.md) to learn the basics of working
with Kotlin DataFrame inside a notebook.
* For more advanced use cases, explore our collection of
[detailed guides and real-world examples](Guides-And-Examples.md),
showcasing how Kotlin DataFrame can help with a variety of data tasks.
dataframe/docs/StardustDocs/topics/setup/SetupGradle.md
Vendored
+147
View File
@@ -0,0 +1,147 @@
# Setup Kotlin DataFrame in Gradle
<web-summary>
Set up Kotlin DataFrame in your Gradle project, configure dependencies, and start using the API with full IDE support.
</web-summary>
<card-summary>
Learn how to add Kotlin DataFrame to your Gradle project.
</card-summary>
<link-summary>
Guide for integrating Kotlin DataFrame in a Gradle-based project, with setup instructions and example code.
</link-summary>
Kotlin DataFrame can be added as a usual Gradle dependency
to your Kotlin project (for now only Kotlin/JVM is supported).
## Create a Kotlin project
1. In IntelliJ IDEA, select **File** | **New** | **Project**.
2. In the panel on the left, select **New Project**.
3. Name the new project and change its location, if necessary.
> Select the **Create Git repository** checkbox to place the new project under version control.
> You can enable this later at any time.
> {type="tip"}
4. From the **Language** list, select **Kotlin**.
5. Select the **Gradle** build system.
6. From the **JDK list**, select the [JDK](https://www.oracle.com/java/technologies/downloads/)
that you want to use in your project. The minimum supported version is JDK 8.
* If the JDK is installed on your computer, but not defined in the IDE, select **Add JDK**
and specify the path to the JDK home directory.
* If you don't have the necessary JDK on your computer, select **Download JDK**.
7. From the **Gradle DSL** list, select **Kotlin** or **Groovy**.
8. Select the **Add sample code** checkbox to create a file with a sample `"Hello World!"` application.
9. Click **Create**.
You have successfully created a project with Gradle.
## Add Kotlin DataFrame Gradle dependency
In your Gradle build file (`build.gradle` or `build.gradle.kts`), add the Kotlin DataFrame library as a dependency:
<tabs>
<tab title="Kotlin DSL">
```kotlin
dependencies {
implementation("org.jetbrains.kotlinx:dataframe:%dataFrameVersion%")
}
```
</tab>
<tab title="Groovy DSL">
```groovy
dependencies {
implementation 'org.jetbrains.kotlinx:dataframe:%dataFrameVersion%'
}
```
</tab>
</tabs>
This will add [general Kotlin DataFrame dependency](Modules.md#dataframe-general),
i.e., [core API and implementation](Modules.md#dataframe-core) as well as all
[IO modules](Modules.md#io-modules) (excluding [experimental ones](Modules.md#experimental-modules)).
For flexible dependencies configuration see [Custom configuration](SetupCustomGradle.md).
## Hello World
Let’s create your first [`DataFrame`](DataFrame.md) — a simple "Hello, World!" style example:
```kotlin
import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
import org.jetbrains.kotlinx.dataframe.api.print
fun main() {
val df = dataFrameOf(
"name" to listOf("Alice", "Bob"),
"age" to listOf(25, 30)
)
df.print()
}
```
## Kotlin DataFrame Compiler Plugin
[Kotlin DataFrame Compiler Plugin](Compiler-Plugin.md) enables automatic generation of
[extension properties](extensionPropertiesApi.md) and updates [data schemas](schemas.md)
on-the-fly in Gradle projects, making development with Kotlin DataFrame faster,
more convenient, and fully type- and name-safe.
> Requires Kotlin 2.2.20-Beta1 or higher.
> { style = "note" }
To enable the plugin in your Gradle project, add it to the `plugins` section:
<tabs>
<tab title="Kotlin DSL">
```kotlin
plugins {
kotlin("plugin.dataframe") version "%compilerPluginKotlinVersion%"
}
```
</tab>
<tab title="Groovy DSL">
```groovy
plugins {
id 'org.jetbrains.kotlin.plugin.dataframe' version '%compilerPluginKotlinVersion%'
}
```
</tab>
</tabs>
Due to the [known issue](https://youtrack.jetbrains.com/issue/KT-66735), incremental compilation must be disabled for now.
Add the following line to your `gradle.properties` file:
```properties
kotlin.incremental=false
```
## Project Example
See [the Gradle example project with the Kotlin DataFrame Compiler Plugin enabled on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-gradle-example).
You can also
[download this project](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-gradle-example.zip).
## Next Steps
* Once you’ve set up Kotlin DataFrame in your Gradle project, continue with the [](quickstart.md)
to learn the basics of working with Kotlin DataFrame.
* Explore [detailed guides and real-world examples](Guides-And-Examples.md)
to see how Kotlin DataFrame helps with different data tasks.
* Check out various
[IDEA examples using Kotlin DataFrame on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples).
* Learn more about the [compiler plugin](Compiler-Plugin.md).
dataframe/docs/StardustDocs/topics/setup/SetupJupyter.md
Vendored
+28
View File
@@ -0,0 +1,28 @@
[//]: # (title: Setup Kotlin DataFrame in Jupyter)
<web-summary>
Run Kotlin DataFrame inside Jupyter notebooks using the Kotlin Jupyter kernel — ideal for interactive data exploration and analysis.
</web-summary>
<card-summary>
Use Kotlin DataFrame in Jupyter with the Kotlin kernel — an easy way to explore, clean, and analyze data interactively.
</card-summary>
<link-summary>
How to set up Kotlin DataFrame in Jupyter using the Kotlin Jupyter kernel for interactive data work.
</link-summary>
[Kotlin Jupyter kernel](https://github.com/Kotlin/kotlin-jupyter) allows you to run Kotlin code
in interactive [Jupyter notebooks](https://jupyter.org).
Kotlin DataFrame is fully integrated and works seamlessly within these environments.
To use Kotlin DataFrame in a Jupyter notebook with the Kotlin Jupyter Kernel,
follow the same steps as described in the [Setup in Kotlin Notebook](SetupKotlinNotebook.md).
## Next Steps
* Once you’ve successfully set up Kotlin DataFrame in Jupyter, you can move on to the [](quickstart.md)
to learn the basics of working with Kotlin DataFrame inside a notebook.
* For more advanced use cases, explore our collection of
[detailed guides and real-world examples](Guides-And-Examples.md),
showcasing how Kotlin DataFrame can help with a variety of data tasks.
dataframe/docs/StardustDocs/topics/setup/SetupKotlinNotebook.md
Vendored
+134
View File
@@ -0,0 +1,134 @@
# Setup Kotlin DataFrame in Kotlin Notebook
<web-summary>
Use Kotlin DataFrame directly in Kotlin Notebook — write code, explore results, and refine your analysis step by step in a live environment.
</web-summary>
<card-summary>
Start analyzing data with Kotlin DataFrame in Kotlin Notebook — live code execution,
rich tables, and zero configuration required.
</card-summary>
<link-summary>
Follow a step-by-step introduction to Kotlin DataFrame in Kotlin Notebook: setup, first DataFrame, and interactive output — all in one place.
</link-summary>
[**Kotlin Notebook**](https://kotlinlang.org/docs/kotlin-notebook-overview.html) is an interactive environment
integrated into [IntelliJ IDEA](https://www.jetbrains.com/idea/) (and can be easily added in
[Android Studio](https://developer.android.com/studio)), designed for fast, iterative,
and visual data exploration with Kotlin.
The Kotlin Notebook plugin transforms IntelliJ IDEA into a powerful data science workspace,
combining Kotlin’s strong language features with live code execution,
interactive data exploration, and rich visualizations.
It’s perfect for working with Kotlin DataFrame — letting you write code, view results instantly,
and refine your analysis step by step.
## Create a Kotlin notebook
<tip>
Before version 2025.1, Kotlin Notebook is unavailable in IntelliJ IDEA Community Edition
and not bundled in IntelliJ IDEA Ultimate Edition by default.
</tip>
* Make sure the [Kotlin Notebook plugin is enabled](https://kotlinlang.org/docs/kotlin-notebook-set-up-env.html).
* Open an IntelliJ IDEA project (either new or existing).
* In the project view, create a new Kotlin Notebook file:
Press <shortcut key="$NewFile"/> or right-click the project tree, then select
<ui-path>Kotlin Notebook</ui-path>.
![Create Kotlin Notebook file](new_ktn_file.png){width="200"}
For more details, see
[Get started with Kotlin Notebook](https://kotlinlang.org/docs/get-started-with-kotlin-notebooks.html)
on the official [Kotlin Documentation](https://kotlinlang.org/docs/home.html) website.
## Integrate Kotlin DataFrame
In the new notebook file, execute the following cell to add the Kotlin DataFrame library:
```
%use dataframe
```
This will load all necessary dependencies, add required imports, and enable rich DataFrame rendering in the notebook.
### Specify a version
By default, if no version is specified, the version bundled with the notebook kernel is used.
You can explicitly define the version you want:
```
%use dataframe(1.0.0-Beta4n)
```
Or use the latest stable version of Kotlin DataFrame
(specified in [Kotlin Jupyter descriptors](https://github.com/Kotlin/kotlin-jupyter-libraries)):
```
%useLatestDescriptors
%use dataframe
```
> For version `1.0.0-Beta4`, in notebooks use version `1.0.0-Beta4n` instead.
> The regular version [does not work with statistical functions](https://github.com/Kotlin/dataframe/issues/1116).
> The `n` version includes a [patch](https://github.com/Kotlin/dataframe/pull/1435) that resolves this issue.
>
> When using `%use dataframe` in the latest kernel version
> or with the `%useLatestDescriptors` this version is applied **automatically**.
>
> If you want to include `kandy`, list it **after** `dataframe`:
> ```kotlin
> %useLatestDescriptors
> %use dataframe, kandy
> // or
> %use dataframe(1.0.0-Beta4n), kandy(0.8.3)
> ```
> {style="warning"}
## Hello World
Let’s create your first [`DataFrame`](DataFrame.md) in the notebook — a simple "Hello, World!" style example:
```kotlin
val df = dataFrameOf(
"name" to listOf("Alice", "Bob"),
"age" to listOf(25, 30)
)
```
To display it, run a cell with the `DataFrame` variable in the last line (or simply a cell containing the variable):
```kotlin
df
```
You will see the content of this `DataFrame` rendered as an interactive table directly in the cell output:
![df_output](df_output.png) {height="168"}
## Next Steps
* Once you’ve successfully set up Kotlin DataFrame in Kotlin Notebook,
you can move on to the [](quickstart.md)
which walks you through the basics of working with Kotlin DataFrame inside a notebook.
* For more advanced use cases, explore our collection of
[detailed guides and real-world examples](Guides-And-Examples.md),
showcasing how Kotlin DataFrame can help with a variety of data tasks.
* Discover powerful [](Kotlin-DataFrame-Features-in-Kotlin-Notebook.md)that
make exploring and understanding your data easier and more effective.
## Memory Errors?
* If you are experiencing `OutOfMemoryError`s and heap space errors, you can adjust Notebook's
memory settings independently of IntelliJ IDEA's memory settings.
* In IntelliJ IDEA, go to Settings... Tools... Kotlin Notebook and increase the `Max heap size`
dataframe/docs/StardustDocs/topics/setup/SetupMaven.md
Vendored
+126
View File
@@ -0,0 +1,126 @@
# Setup Kotlin DataFrame in Maven
<web-summary>
Set up Kotlin DataFrame in your Maven project, configure dependencies, and start using the API with full IDE support.
</web-summary>
<card-summary>
Learn how to add Kotlin DataFrame to your Maven project.
</card-summary>
<link-summary>
Guide for integrating Kotlin DataFrame in a Maven project, with setup instructions and example code.
</link-summary>
Kotlin DataFrame can be added as a usual Maven dependency to your Kotlin project.
## Create a Kotlin project
1. In IntelliJ IDEA, select **File** | **New** | **Project**.
2. In the panel on the left, select **New Project**.
3. Name the new project and change its location, if necessary.
> Select the **Create Git repository** checkbox to place the new project under version control.
> You can enable this later at any time.
> {type="tip"}
4. From the **Language** list, select **Kotlin**.
5. Select the **Maven** build system.
6. From the **JDK list**, select the [JDK](https://www.oracle.com/java/technologies/downloads/)
that you want to use in your project. The minimum supported version is JDK 8.
* If the JDK is installed on your computer, but not defined in the IDE, select **Add JDK**
and specify the path to the JDK home directory.
* If you don't have the necessary JDK on your computer, select **Download JDK**.
7. Select the **Add sample code** checkbox to create a file with a sample `"Hello World!"` application.
8. Click **Create**.
You have successfully created a project with Maven.
## Add Kotlin DataFrame Maven dependency
In your Maven build file (`pom.xml`), add the Kotlin DataFrame library as a dependency:
```xml
<dependency>
<groupId>org.jetbrains.kotlinx</groupId>
<artifactId>dataframe</artifactId>
<version>%dataFrameVersion%</version>
</dependency>
```
This will add [general Kotlin DataFrame dependency](Modules.md#dataframe-general),
i.e., [core API and implementation](Modules.md#dataframe-core) as well as all
[IO modules](Modules.md#io-modules) (excluding [experimental ones](Modules.md#experimental-modules)).
You can add only the [core API module](Modules.md#dataframe-core)
and the specific [modules](Modules.md) you need.
## Hello World
Let’s create your first [`DataFrame`](DataFrame.md) — a simple "Hello, World!" style example:
```kotlin
import org.jetbrains.kotlinx.dataframe.api.dataFrameOf
import org.jetbrains.kotlinx.dataframe.api.print
fun main() {
val df = dataFrameOf(
"name" to listOf("Alice", "Bob"),
"age" to listOf(25, 30)
)
df.print()
}
```
## Kotlin DataFrame Compiler Plugin
[Kotlin DataFrame Compiler Plugin](Compiler-Plugin.md) enables automatic generation of
[extension properties](extensionPropertiesApi.md) and updates [data schemas](schemas.md)
on-the-fly in Maven projects, making development with Kotlin DataFrame faster,
more convenient, and fully type- and name-safe.
> Requires Kotlin 2.2.20-Beta1 or higher and IntelliJ IDEA 2025.3 or higher.
> { style = "note" }
To enable the plugin in your Maven project, add it to the `plugins` section:
```xml
<plugin>
<artifactId>kotlin-maven-plugin</artifactId>
<groupId>org.jetbrains.kotlin</groupId>
<version>%compilerPluginKotlinVersion%</version>
<configuration>
<compilerPlugins>
<plugin>kotlin-dataframe</plugin>
</compilerPlugins>
</configuration>
<dependencies>
<dependency>
<groupId>org.jetbrains.kotlin</groupId>
<artifactId>kotlin-maven-dataframe</artifactId>
<version>%compilerPluginKotlinVersion%</version>
</dependency>
</dependencies>
</plugin>
```
## Project Example
See [the Maven example project with the Kotlin DataFrame Compiler Plugin enabled on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/kotlin-dataframe-plugin-maven-example).
You can also
[download this project](https://github.com/Kotlin/dataframe/raw/example-projects-archives/kotlin-dataframe-plugin-maven-example.zip).
## Next Steps
* Once you’ve set up Kotlin DataFrame in your Maven project, continue with the [](quickstart.md)
to learn the basics of working with Kotlin DataFrame.
* Explore [detailed guides and real-world examples](Guides-And-Examples.md)
to see how Kotlin DataFrame helps with different data tasks.
* Check out various
[IDEA examples using Kotlin DataFrame on GitHub](https://github.com/Kotlin/dataframe/tree/master/examples/idea-examples).
* Learn more about the [compiler plugin](Compiler-Plugin.md).