Skip to content

Commit 0606ff8

Browse files
AndreiKingsleyAndreiKingsley
committed
faq topic
1 parent b8e90f8 commit 0606ff8

File tree

2 files changed

+204
-0
lines changed

2 files changed

+204
-0
lines changed

‎docs/StardustDocs/d.tree

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -203,4 +203,5 @@
203203
<toc-element topic="gradleReference.md"/>
204204
</toc-element>
205205
<toc-element topic="_shadow_resources.md" hidden="true"/>
206+
<toc-element topic="FAQ.md"/>
206207
</instance-profile>

‎docs/StardustDocs/topics/FAQ.md

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

0 commit comments

Comments
 (0)