Skip to content

Commit 03190bb

Browse files
AndreiKingsleyAndreiKingsley
authored
Merge pull request #1316 from Kotlin/faq
faq topic
2 parents 07e3c90 + b1679c3 commit 03190bb

File tree

2 files changed

+209
-0
lines changed

2 files changed

+209
-0
lines changed

‎docs/StardustDocs/d.tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -190,4 +190,5 @@
190190
</toc-element>
191191
<toc-element topic="_shadow_resources.md" hidden="true"/>
192192
<toc-element topic="Support.md"/>
193+
<toc-element topic="FAQ.md"/>
193194
</instance-profile>

‎docs/StardustDocs/topics/FAQ.md

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# Frequently Asked Questions
2+
3+
Here's a list of frequently asked questions about Kotlin DataFrame.
4+
If you haven’t found an answer to yours, feel free to ask it on:
5+
6+
- [GitHub Issues](https://github.com/Kotlin/dataframe/issues)
7+
- [#datascience](https://slack-chats.kotlinlang.org/c/datascience) channel in Kotlin Slack
8+
([request an invite](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up?_gl=1*1ssyqy3*_gcl_au*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*FPAU*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*_ga*MTE0ODQ1MzY3OS4xNzM4OTY1NzM3*_ga_9J976DJZ68*czE3NTE1NDUxODUkbzIyNyRnMCR0MTc1MTU0NTE4NSRqNjAkbDAkaDA.)).
9+
10+
## What is Kotlin DataFrame?
11+
12+
**Kotlin DataFrame** is an official open-source Kotlin framework written in pure
13+
Kotlin for working with tabular data.
14+
Its goal is to reconcile Kotlin’s static typing with the dynamic nature of data,
15+
providing a flexible and convenient idiomatic DSL for working with data in Kotlin.
16+
17+
## Is Kotlin DataFrame a Multiplatform Library?
18+
19+
Not yet — Kotlin DataFrame currently supports only the **JVM** target.
20+
21+
We’re actively exploring multiplatform support.
22+
To stay updated on progress, subscribe to the
23+
[corresponding issue](https://github.com/Kotlin/dataframe/issues/24).
24+
25+
### Does Kotlin DataFrame work on Android?
26+
27+
Yes — Kotlin DataFrame can be used in Android projects.
28+
29+
There is no dedicated Android artifact yet, but you can include the standard **JVM artifact**
30+
by setting up a [custom Gradle configuration](gettingStartedGradleAdvanced.md).
31+
32+
## How to start with Kotlin DataFrame ?
33+
34+
If you're new to Kotlin DataFrame, the [Quickstart guide](quickstart.md) is the perfect place to begin —
35+
it gives a brief yet comprehensive introduction to the basics of working with DataFrame.
36+
37+
You can also check out [other guides and examples](Guides-And-Examples.md)
38+
to explore various use cases and deepen your understanding of Kotlin DataFrame.
39+
40+
## What is the best environment to use Kotlin DataFrame?
41+
42+
For the best experience, Kotlin DataFrame is most effective in an interactive environment.
43+
44+
- **[Kotlin Notebook](gettingStartedKotlinNotebook.md)** is ideal for exploring Kotlin DataFrame.
45+
Everything works out of the box — interactivity, rich rendering of DataFrames and plots.
46+
You can instantly see the results of each operation, view the contents of your DataFrames after every transformation,
47+
inspect individual rows and columns, and explore data step-by-step in a live and interactive way.
48+
See the [](quickstart.md) to get started quickly.
49+
50+
- **[Kotlin DataFrame Compiler Plugin for IDEA projects](Compiler-Plugin.md)** enhances your usual
51+
[IntelliJ IDEA](https://www.jetbrains.com/idea/) Kotlin projects by enabling compile-time
52+
[extension properties](extensionPropertiesApi.md) generation.
53+
This allows you to work with DataFrames in a name- and type-safe manner,
54+
integrating seamlessly with the IDE.
55+
56+
## Is `DataFrame` mutable?
57+
58+
No, [`DataFrame`](DataFrame.md) is a completely immutable structure.
59+
Kotlin DataFrame follows the functional style of Kotlin —
60+
each [operation](operations.md) that modifies the data returns a new, updated `DataFrame` instance.
61+
62+
This means original data is never changed in-place, which improves code safety.
63+
64+
## How do I interoperate with collections like `List` or `Map`?
65+
66+
[`DataFrame`](DataFrame.md) integrates seamlessly with Kotlin collections.
67+
68+
You can:
69+
- Create a `DataFrame` from a `Map` using [`toDataFrame()`](createDataFrame.md#todataframe).
70+
- Convert a `DataFrame` back to a `Map` using [`toMap()`](toMap.md).
71+
- Create a [`DataColumn`](DataColumn.md) from a `List` using [`toColumn()`](createColumn.md#tocolumn).
72+
- Convert a `DataColumn` to a `List` of values.
73+
- Convert a `DataFrame<T>` into a `List<T>` of data class instances corresponding to each row
74+
using [`toList()`](toList.md).
75+
76+
## Are there any limitations on the types used in a DataFrame?
77+
78+
No! You can store values of **any Kotlin or Java types** inside a [`DataFrame`](DataFrame.md)
79+
and work with them in a type-safe manner using [extension properties](extensionPropertiesApi.md)
80+
across various [operations](operations.md).
81+
82+
For some commonly used types — such as
83+
[Kotlin basic types](https://kotlinlang.org/docs/basic-types.html) and
84+
[Kotlin date-time types](https://github.com/Kotlin/kotlinx-datetime) —
85+
there is built-in support for automatic conversion and parsing.
86+
87+
## What data sources are supported?
88+
89+
<!------TODO data sources---->
90+
91+
Kotlin DataFrame supports all popular data sources — CSV, JSON, Excel, Apache Arrow, SQL databases, and more!
92+
See the [Data Sources section](Data-Sources.md) for a complete list of supported formats
93+
and instructions on how to integrate them into your workflow.
94+
95+
Some sources — such as Apache Spark, [Exposed](https://www.jetbrains.com/help/exposed/home.html),
96+
and [Multik](https://github.com/Kotlin/multik) — are not supported directly (yet),
97+
but you can find [official integration examples here](Integrations.md).
98+
99+
If the data source you need isn't supported yet,
100+
feel free to open an [issue](https://github.com/Kotlin/dataframe/issues)
101+
and describe your use case — we’d love to hear from you!
102+
103+
## I see magically appearing properties in examples. What is it?
104+
105+
These are [extension properties](extensionPropertiesApi.md) — one of the key features of Kotlin DataFrame.
106+
107+
Extension properties correspond to the columns of a [`DataFrame`](DataFrame.md), allowing you to access and select them
108+
in a **type-safe** and **name-safe** way.
109+
110+
They are generated automatically when working with Kotlin DataFrame in:
111+
112+
- [Kotlin Notebook](gettingStartedKotlinNotebook.md), where extension properties are generated
113+
after each cell execution.
114+
- A Kotlin project in [IntelliJ IDEA](https://www.jetbrains.com/idea/) with the
115+
[](Compiler-Plugin.md) enabled, where the properties are generated at compile time.
116+
117+
## I used the KProperties API in older versions, what should I use now that it's deprecated?
118+
119+
The KProperty API was a useful access mechanism in earlier versions.
120+
However, with the introduction of [extension properties](extensionPropertiesApi.md)
121+
and the [Kotlin DataFrame compiler plugin](Compiler-Plugin.md),
122+
you now have a more flexible and powerful alternative.
123+
124+
Annotate your Kotlin class with [`@DataSchema`](Compiler-Plugin.md#dataschema-declarations),
125+
and the plugin will automatically generate type-safe extension properties
126+
for your [`DataFrame`](DataFrame.md).
127+
Or alternatively, call [`toDataFrame()`](createDataFrame.md#todataframe) on a list of Kotlin or Java objects,
128+
and the resulting `DataFrame` will have schema according to their properties or getters.
129+
130+
See [compiler plugin examples](Compiler-Plugin.md#examples).
131+
132+
## How to visualize data from a DataFrame?
133+
134+
[Kandy](https://kotlin.github.io/kandy) is a Kotlin plotting library
135+
designed to integrate seamlessly with Kotlin DataFrame.
136+
It provides a convenient and idiomatic Kotlin DSL for building charts,
137+
leveraging all Kotlin DataFrame features — including [extension properties](extensionPropertiesApi.md).
138+
139+
See the [Kandy Quick Start Guide](https://kotlin.github.io/kandy/quick-start-guide.html)
140+
and explore the [Examples Gallery](https://kotlin.github.io/kandy/examples.html).
141+
142+
## Can I work with hierarchical/nested data?
143+
144+
Yes, Kotlin DataFrame is designed to work with hierarchical data.
145+
146+
You can read JSON or any other nested format into a [`DataFrame`](DataFrame.md)
147+
with hierarchical structure — using `FrameColumn`
148+
(a column of data frames) and `ColumnGroup` (a column with nested subcolumns).
149+
150+
Both [dataframe schemas](schemas.md) and [extension properties](extensionPropertiesApi.md)
151+
fully support nested data structures, allowing type-safe access and transformations at any depth.
152+
153+
See [](hierarchical.md) for more information.
154+
155+
Also, you can transform your data into grouped structures using [`groupBy`](groupBy.md) or [`pivot`](pivot.md).
156+
157+
## Does Kotlin DataFrame support OpenAPI schemas?
158+
159+
Yes — the experimental `dataframe-openapi` module adds support for OpenAPI JSON schemas.
160+
You can use it to parse and work with OpenAPI-defined structures directly in Kotlin DataFrame.
161+
162+
See the [OpenAPI Guide](https://github.com/Kotlin/dataframe/blob/master/examples/notebooks/json/KeyValueAndOpenApi.ipynb)
163+
for details and examples.
164+
165+
## Does Kotlin DataFrame support geospatial data?
166+
167+
Yes — the experimental `dataframe-geo` module provides functionality for working with geospatial data,
168+
including support for reading and writing GeoJSON and Shapefile formats, as well as tools for manipulating geometry types.
169+
170+
See the [GeoDataFrame Guide](https://kotlin.github.io/kandy/geo-plotting-guide.html) for details
171+
and examples with beautiful [Kandy](https://kotlin.github.io/kandy) geo visualizations.
172+
173+
## What is the difference between Compiler Plugin, Gradle Plugin, and KSP Plugin?
174+
175+
All these plugins relate to working with [dataframe schemas](schemas.md), but they serve different purposes:
176+
177+
- **[Gradle Plugin](DataSchemaGenerationGradle.md)** and **[KSP Plugin](https://github.com/Kotlin/dataframe/tree/master/plugins/symbol-processor)**
178+
are used to **generate data schemas** from external sources as part of the Gradle build process.
179+
180+
- **Gradle Plugin**: You declare the data source in your `build.gradle.kts` file
181+
using the `dataframes { ... }` block.
182+
183+
- **KSP Plugin**: You annotate your Kotlin file with `@ImportDataSchema` file annotation,
184+
and the schema will be generated via Kotlin Symbol Processing.
185+
186+
See [Data Schemas in Gradle Projects](https://kotlin.github.io/dataframe/schemasgradle.html) for more.
187+
188+
- **[Compiler Plugin](Compiler-Plugin.md)**
189+
provides **on-the-fly generation** of [extension properties](extensionPropertiesApi.md)
190+
based on an existing schema **during compilation**.
191+
However, when reading data from files or external sources (like SQL),
192+
the schema cannot be inferred automatically — you need to
193+
specify it manually or use the Gradle or KSP plugin to generate it.
194+
195+
## How do I contribute or report an issue?
196+
197+
We’re always happy to receive contributions!
198+
199+
If you’d like to contribute, please refer to our
200+
[contributing guidelines](https://github.com/Kotlin/dataframe/blob/master/CONTRIBUTING.md).
201+
202+
To report bugs or suggest improvements, open an issue on the
203+
[DataFrame GitHub repository](https://github.com/Kotlin/dataframe/issues).
204+
205+
You’re also welcome to ask questions or discuss anything related to Kotlin DataFrame in the
206+
[#datascience](https://slack-chats.kotlinlang.org/c/datascience) channel on Kotlin Slack.
207+
If you’re not yet a member, you can
208+
[request an invitation](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up?_gl=1*1ssyqy3*_gcl_au*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*FPAU*MTk5NzUwODYzOS4xNzQ2NzkxMDMz*_ga*MTE0ODQ1MzY3OS4xNzM4OTY1NzM3*_ga_9J976DJZ68*czE3NTE1NDUxODUkbzIyNyRnMCR0MTc1MTU0NTE4NSRqNjAkbDAkaDA.).

0 commit comments

Comments
 (0)