Skip to content

Document how to create a dataset with code #95

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
corentinmusard merged 2 commits into from
Dec 4, 2025
+295 −4
Merged

Document how to create a dataset with code #95

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
673bdaf
Document how to create a dataset with code
corentinmusard Dec 3, 2025
70d47ca
update reference
corentinmusard Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 110 additions & 0 deletions api-reference/go/datasets/Create.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,110 @@
---
title: Client.Datasets.Create
sidebarTitle: Create
icon: laptop-code
---

```go
func (datasetClient) Create(
ctx context.Context,
name string,
kind datasets.DatasetKind,
codeName string,
description string,
fields []Field,
) (*datasets.Dataset, error)
```

Create a dataset.

## Parameters

<ParamField path="name" type="string">
The name of the dataset
</ParamField>
<ParamField path="kind" type="datasets.DatasetKind">
The kind of the dataset
</ParamField>
<ParamField path="codeName" type="string">
The code name of the dataset
</ParamField>
<ParamField path="description" type="string">
The description of the dataset
</ParamField>
<ParamField path="fields" type="[]Field">
The fields of the dataset
</ParamField>

## Dataset kinds

<ParamField path="KindTemporal" type="datasets.DatasetKind">
A dataset that contains a timestamp field
</ParamField>
<ParamField path="KindSpatiotemporal" type="datasets.DatasetKind">
A dataset that contains a timestamp field and a geometry field
</ParamField>

## Field types

<ParamField path="field.String(name string)" type="Field">
A string field
</ParamField>
<ParamField path="field.Bytes(name string)" type="Field">
A bytes field
</ParamField>
<ParamField path="field.Bool(name string)" type="Field">
A boolean field
</ParamField>
<ParamField path="field.Int64(name string)" type="Field">
A 64-bit signed integer field
</ParamField>
<ParamField path="field.Uint64(name string)" type="Field">
A 64-bit unsigned integer field
</ParamField>
<ParamField path="field.Float64(name string)" type="Field">
A 64-bit floating-point number field
</ParamField>
<ParamField path="field.Duration(name string)" type="Field">
A duration field
</ParamField>
<ParamField path="field.Timestamp(name string)" type="Field">
A timestamp field
</ParamField>
<ParamField path="field.UUID(name string)" type="Field">
A UUID field
</ParamField>
<ParamField path="field.Geometry(name string)" type="Field">
A geometry field
</ParamField>

## Field options

<ParamField path="Repeated()">
Indicate that the field is an array
</ParamField>
<ParamField path="Description(description string)">
Set the description of the field to provide more context and details about the data
</ParamField>
<ParamField path="ExampleValue(exampleValue string)">
Set the example value of the field for documentation purposes
</ParamField>

## Returns

The created dataset object.

<RequestExample>
```go Go
dataset, err := client.Datasets.Create(ctx,
"My personal catalog",
datasets.KindSpatiotemporal,
"my_catalog",
"A description of my catalog",
[]Field{
field.String("field1"),
field.Int64("field2").Repeated(),
field.Geometry("field3").Description("Field 3").ExampleValue("Value 3"),
},
)
```
</RequestExample>
126 changes: 126 additions & 0 deletions api-reference/python/tilebox.datasets/Client.create_dataset.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
---
title: Client.create_dataset
icon: laptop-code
---

```python
def Client.create_dataset(
kind: DatasetKind,
code_name: str,
fields: list[FieldDict],
*,
name: str | None = None,
description: str | None = None
) -> Dataset
```

Create a dataset.

## Parameters

<ParamField path="kind" type="DatasetKind">
The kind of the dataset
</ParamField>
<ParamField path="code_name" type="str">
The code name of the dataset
</ParamField>
<ParamField path="fields" type="list[FieldDict]">
The fields of the dataset
</ParamField>
<ParamField path="name" type="str | None">
The name of the dataset
</ParamField>
<ParamField path="description" type="str | None">
A short description of the dataset
</ParamField>

## Dataset kinds

<ParamField path="DatasetKind.TEMPORAL" type="DatasetKind">
A dataset that contains a timestamp field
</ParamField>
<ParamField path="DatasetKind.SPATIOTEMPORAL" type="DatasetKind">
A dataset that contains a timestamp field and a geometry field
</ParamField>

## Field types

<ParamField path="str" type="type">
A string field
</ParamField>
<ParamField path="bytes" type="type">
A bytes field
</ParamField>
<ParamField path="bool" type="type">
A boolean field
</ParamField>
<ParamField path="int" type="type">
A 64-bit signed integer field
</ParamField>
<ParamField path="np.uint64" type="type">
A 64-bit unsigned integer field
</ParamField>
<ParamField path="float" type="type">
A 64-bit floating-point number field
</ParamField>
<ParamField path="datetime.timedelta" type="type">
A duration field
</ParamField>
<ParamField path="datetime.datetime" type="type">
A timestamp field
</ParamField>
<ParamField path="uuid.UUID" type="type">
A UUID field
</ParamField>
<ParamField path="shapely.Geometry" type="type">
A geometry field
</ParamField>

Note that the type can be a list of the types above, indicating that the field is an array, e.g. `list[str]`.

## Field options

<ParamField path="name" type="str" required>
Set the name of the field
</ParamField>
<ParamField path="type" type="type" required>
Set the type of the field
</ParamField>
<ParamField path="description" type="str">
Set the description of the field to provide more context and details about the data
</ParamField>
<ParamField path="example_value" type="str">
Set the example value of the field for documentation purposes
</ParamField>

## Returns

The created dataset object.

<RequestExample>
```python Python
from shapely import Geometry

dataset = client.create_dataset(
DatasetKind.SPATIOTEMPORAL,
"my_catalog",
[
{
"name": "field1",
"type": str,
},
{
"name": "field2",
"type": list[int],
},
{
"name": "field3",
"type": Geometry,
"description": "Field 3",
"example_value": "Value 3",
},
],
name="My personal catalog",
)
```
</RequestExample>
61 changes: 57 additions & 4 deletions datasets/concepts/datasets.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -92,10 +92,6 @@ When defining the data schema, you can specify each field's type. The following

Every type is also available as an array, allowing to ingest multiple values of the underlying type for each data point. The size of the array is flexible, and can be different for each data point.

## Creating a dataset

You can create a dataset in Tilebox using the [Tilebox Console](/console). Check out the [Creating a dataset](/guides/datasets/create) guide for an example of how to achieve this.

## Listing datasets

You can use [your client instance](/datasets/introduction#creating-a-datasets-client) to access the datasets available to you. To list all available datasets, use the `datasets` method of the client.
Expand Down Expand Up @@ -153,6 +149,63 @@ Once you have your dataset object, you can use it to [list the available collect
In python, if you're using an IDE or an interactive environment with auto-complete, you can use it on your client instance to discover the datasets available to you. Type `client.` and trigger auto-complete after the dot to do so.
</Tip>

## Creating a dataset

You can create a dataset in code or using the Console (cf [Creating a dataset using the Console](/guides/datasets/create)).

<CodeGroup>
```python Python
from datetime import timedelta
from tilebox.datasets import Client
from tilebox.datasets.data.datasets import DatasetKind

client = Client()

dataset = client.create_dataset(
DatasetKind.SPATIOTEMPORAL,
"my_landsat8_oli_tirs",
[
{
"name": "granule_name",
"type": str,
"description": "The name of the Landsat-8 granule.",
"example_value": "LE07_L1TP_174061_20010913_20200917_02_T1",
},
{
"name": "cloud_cover",
"type": float,
"description": "Cloud cover percentage",
"example_value": "91",
},
{
"name": "proj_shape",
"type": list[int],
"description": "Raster shape",
"example_value": "[6971, 7801]",
},
],
name="Personal Landsat-8 catalog",
description="This catalog contains metadata for Landsat-8 OLI-TIRS data.",
)
```
```go Go
dataset, err := client.Datasets.Create(ctx,
"Personal Landsat-8 catalog",
datasets.KindSpatiotemporal,
"my_landsat8_oli_tirs",
"This catalog contains metadata for Landsat-8 OLI-TIRS data.",
[]datasets.Field{
field.String("granule_name").Description("The name of the Earth View Granule").ExampleValue("20220830_185202_SN18_10N_552149_5297327"),
field.Float64("cloud_cover").Description("Cloud cover percentage").ExampleValue("91"),
field.Int64("proj_shape").Repeated().Description("Raster shape").ExampleValue("[6971, 7801]"),
}
)
```
</CodeGroup>

This code will create a new catalog with 7 fields in total.
4 of those fields are auto-generated by choosing the spatio-temporal dataset type, and 3 (`granule_name`, `cloud_cover`, `proj_shape`) are additional fields that are defined.

## Accessing a dataset

Each dataset has an automatically generated *slug* that can be used to access it. The *slug* is the name of the group, followed by a dot, followed by the dataset *code name*.
Expand Down
2 changes: 2 additions & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -166,6 +166,7 @@
"api-reference/python/tilebox.datasets/Client",
"api-reference/python/tilebox.datasets/Client.datasets",
"api-reference/python/tilebox.datasets/Client.dataset",
"api-reference/python/tilebox.datasets/Client.create_dataset",
"api-reference/python/tilebox.datasets/Dataset.collections",
"api-reference/python/tilebox.datasets/Dataset.collection",
"api-reference/python/tilebox.datasets/Dataset.create_collection",
Expand Down Expand Up @@ -210,6 +211,7 @@
{
"group": "datasets",
"pages": [
"api-reference/go/datasets/Create",
"api-reference/go/datasets/Get",
"api-reference/go/datasets/List",
"api-reference/go/datasets/Collections.Create",
Expand Down