# Data Schemas in Gradle projects

> For the complete documentation index, see [llms.txt](https://kotlin.github.io/dataframe/llms.txt).

> **Warning:**
> The current Gradle plugin is deprecated. Its latest release is 1.0.0-Beta4 and will not have future releases.
>
>
>
> At the moment, [data schema generation is handled via dedicated methods](dataschemagenerationmethods.html) instead of relying on the plugin. Our plans for the next iteration of this feature can be found in [Issue #1844](https://github.com/Kotlin/dataframe/issues/1844).

In Gradle projects, the Kotlin DataFrame library provides

1. Annotation processing for generation of extension properties

2. Annotation processing for [DataSchema](schemas.html) inference from datasets.

3. Gradle task for [DataSchema](schemas.html) inference from datasets.

## Configuration

To use the [extension properties API](extensionpropertiesapi.html) in Gradle project add the `dataframe` plugin as follows:

Kotlin DSL:

```KOTLIN
plugins {
    id("org.jetbrains.kotlinx.dataframe") version "1.0.0-rc02"
}

dependencies {
    implementation("org.jetbrains.kotlinx:dataframe:1.0.0-rc02")
}
```

Groovy DSL:

```GROOVY
plugins {
    id("org.jetbrains.kotlinx.dataframe") version "1.0.0-rc02"
}

dependencies {
    implementation 'org.jetbrains.kotlinx:dataframe:1.0.0-rc02'
}
```

## Annotation processing

Declare data schemas in your code and use them to access data in [DataFrame](dataframe.html) objects. A data schema is a class or interface annotated with [@DataSchema](schemas.html):

```KOTLIN
import org.jetbrains.kotlinx.dataframe.annotations.DataSchema

@DataSchema
interface Person {
    val name: String
    val age: Int
}
```

###  Execute the `assemble` task to generate type-safe accessors for schemas: 

```KOTLIN
val df = dataFrameOf("name", "age")(
    "Alice", 15,
    "Bob", 20,
).cast<Person>()
// age only available after executing `build` or `kspKotlin`!
val teens = df.filter { age in 10..19 }
teens.print()
```

## Schema inference

Specify schema with preferred method and execute the `assemble` task.

Method 1. Annotation processing:

The `@ImportDataSchema` annotation must be above the package directive. You can import schemas from a URL or from the relative path of a file. By default, a relative path is resolved against the project root directory. You can configure it by [passing](https://kotlinlang.org/docs/ksp-quickstart.html#pass-options-to-processors) the `dataframe.resolutionDir` option to the preprocessor. For example:

```KOTLIN
ksp {
    arg("dataframe.resolutionDir", file("data").absolutePath)
}
```

Note that due to incremental processing, imported schema will be re-generated only if some source code has changed from the previous invocation, at least one character.

For the following configuration, file `Repository.Generated.kt` will be generated to `build/generated/ksp/` folder in the same package as file containing the annotation.

```KOTLIN
@file:ImportDataSchema(
    "Repository",
    "https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv",
)

import org.jetbrains.kotlinx.dataframe.annotations.ImportDataSchema
import org.jetbrains.kotlinx.dataframe.api.*
```

See KDocs for `@ImportDataSchema` in IDE or [GitHub](https://github.com/Kotlin/dataframe/blob/master/core/src/main/kotlin/org/jetbrains/kotlinx/dataframe/annotations/ImportDataSchema.kt) for more details.

Method 2. Gradle task:

Put this in `build.gradle` or `build.gradle.kts` For the following configuration, file `Repository.Generated.kt` will be generated to `build/generated/dataframe/org/example` folder.

```KOTLIN
dataframes {
    schema {
        data = "https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv"
        name = "org.example.Repository"
    }
}
```

See [reference](gradle-plugin.html) and [examples](gradle-plugin.html#examples) for more details.

After `assemble`, the following code should compile and run:

```KOTLIN
// Repository.readCsv() has argument 'path' with default value https://raw.githubusercontent.com/Kotlin/dataframe/master/data/jetbrains_repositories.csv
val df = Repository.readCsv()
// Use generated properties to access data in rows
df.maxBy { stargazersCount }.print()
// Or to access columns in dataframe.
print(df.fullName.count { it.contains("kotlin") })
```

