Frequently Asked Questions

What is Kotlin DataFrame?

Kotlin DataFrame is an official open-source Kotlin framework written in pure Kotlin for working with tabular data.
Its goal is to reconcile Kotlin’s static typing with the dynamic nature of data,
providing a flexible and convenient idiomatic DSL for working with data in Kotlin.

Is Kotlin DataFrame a Multiplatform Library?

Not yet — Kotlin DataFrame currently supports only the JVM target.

We’re actively exploring multiplatform support.
To stay updated on progress, subscribe to the corresponding issue.

How to start with Kotlin DataFrame ?

If you're new to Kotlin DataFrame, the Quickstart guide is the perfect place to begin —
it gives a brief yet comprehensive introduction to the basics of working with DataFrame.

You can also check out other guides and examples
to explore various use cases and deepen your understanding of Kotlin DataFrame.

What is the best environment to use Kotlin DataFrame?

For the best experience, Kotlin DataFrame is most effective in an interactive environment.

• Kotlin Notebook is ideal for exploring Kotlin DataFrame.
  Everything works out of the box — interactivity, rich rendering of DataFrames and plots.
  You can instantly see the results of each operation, view the contents of your DataFrames after every transformation,
  inspect individual rows and columns, and explore data step-by-step in a live and interactive way.
  See the Quickstart Guide to get started quickly.

• Kotlin DataFrame Compiler Plugin for IDEA projects enhances your usual IntelliJ IDEA Kotlin projects by enabling compile-time
  extension properties generation.
  This allows you to work with DataFrames in a name- and type-safe manner,
  integrating seamlessly with the IDE.

Is DataFrame mutable?

No, DataFrame is a completely immutable structure.
Kotlin DataFrame follows the functional style of Kotlin —
each operation that modifies the data returns a new, updated DataFrame instance.

This means original data is never changed in-place, which improves code safety.

How do I interoperate with collections like List or Map?

DataFrame integrates seamlessly with Kotlin collections.

You can:

• Create a DataFrame from a Map using toDataFrame().

• Convert a DataFrame back to a Map using toMap().

• Create a DataColumn from a List using toColumn().

• Convert a DataColumn to a List of values.

• Convert a DataFrame<T> into a List<T> of data class instances corresponding to each row
  using toList().

Are there any limitations on the types used in a DataFrame?

No! You can store values of any Kotlin or Java types inside a DataFrame
and work with them in a type-safe manner using extension properties
across various operations.

For some commonly used types — such as
Kotlin basic types and
Kotlin date-time types—
there is built-in support for automatic conversion and parsing.

What data sources are supported?

Kotlin DataFrame supports all popular data sources — CSV, JSON, Excel, Apache Arrow, SQL databases, and more!
See the Data Sources section for a complete list of supported formats
and instructions on how to integrate them into your workflow.

Some sources — such as Apache Spark, Exposed,
and Multik — are not supported directly (yet),
but you can find official integration examples here.

If the data source you need isn't supported yet,
feel free to open an issue
and describe your use case — we’d love to hear from you!

I see magically appearing properties in examples. What is it?

These are extension properties — one of the key features of Kotlin DataFrame.

Extension properties correspond to the columns of a DataFrame, allowing you to access and select them in a type-safe and name-safe way.

They are generated automatically when working with Kotlin DataFrame in:

• Kotlin Notebook, where extension properties are generated after each cell execution.

• A Kotlin project in IntelliJ IDEA with the Kotlin DataFrame Compiler Plugin enabled, where the properties are generated at compile time.

I used the KProperties API in older versions, what should I use now that it's deprecated?

The KProperty API was a useful access mechanism in earlier versions.
However, with the introduction of extension properties and the Kotlin DataFrame compiler plugin, you now have a more flexible and powerful alternative.

Annotate your Kotlin class with @DataSchema,
and the plugin will automatically generate type-safe extension properties for your DataFrame. Or alternatively, call toDataFrame() on a list of Kotlin or Java objects, and the resulting DataFrame will have schema according to their properties or getters.

See compiler plugin examples.

How to visualize data from a DataFrame?

Kandy is a Kotlin plotting library
designed to integrate seamlessly with Kotlin DataFrame.
It provides a convenient and idiomatic Kotlin DSL for building charts,
leveraging all Kotlin DataFrame features — including extension properties.

See the Kandy Quick Start Guide and explore the Examples Gallery.

Can I work with hierarchical/nested data?

Yes, Kotlin DataFrame is designed to work with hierarchical data.

You can read JSON or any other nested format into a DataFrame with hierarchical structure — using FrameColumn (a column of dataframes) and ColumnGroup (a column with nested subcolumns).

Both dataframe schemas and extension properties fully support nested data structures, allowing type-safe access and transformations at any depth.

See Hierarchical data structures for more information.

Also, you can transform your data into grouped structures using groupBy or pivot.

Does Kotlin DataFrame support OpenAPI schemas?

Yes — the experimental dataframe-openapi module adds support for OpenAPI JSON schemas.
You can use it to parse and work with OpenAPI-defined structures directly in Kotlin DataFrame.

See the OpenAPI Guide for details and examples.

Does Kotlin DataFrame support geospatial data?

Yes — the experimental dataframe-geo module provides functionality for working with geospatial data,
including support for reading and writing GeoJSON and Shapefile formats, as well as tools for manipulating geometry types.

See the GeoDataFrame Guide for details and examples with beautiful Kandy geo visualizations.

What is the difference between Compiler Plugin, Gradle Plugin, and KSP Plugin?

All these plugins relate to working with dataframe schemas, but they serve different purposes:

• Gradle Plugin and KSP Plugin are used to generate data schemas from external sources as part of the Gradle build process.

  • Gradle Plugin: You declare the data source in your build.gradle.kts file
    using the dataframes { ... } block.

  • KSP Plugin: You annotate your Kotlin file with @ImportDataSchema file annotation,
    and the schema will be generated via Kotlin Symbol Processing.

  See Data Schemas in Gradle Projects for more.

• Compiler Plugin provides on-the-fly generation of extension properties based on an existing schema during compilation, and updates the DataFrame schema seamlessly after operations. However, when reading data from files or external sources (like SQL), the initial DataFrame schema cannot be inferred automatically — you need to specify it manually or generate it using the generate..() methods.

How do I contribute or report an issue?

We’re always happy to receive contributions!

If you’d like to contribute, please refer to our
contributing guidelines.

To report bugs or suggest improvements, open an issue on the
DataFrame GitHub repository.

You’re also welcome to ask questions or discuss anything related to Kotlin DataFrame in the
#datascience channel on Kotlin Slack.
If you’re not yet a member, you can request an invitation.