From 673bdaf92140a3ee6cf98f6b66283e853783a424 Mon Sep 17 00:00:00 2001 From: Corentin Musard Date: Wed, 3 Dec 2025 17:39:54 +0100 Subject: [PATCH 1/2] Document how to create a dataset with code --- api-reference/go/datasets/Create.mdx | 68 +++++++++++++++ .../Client.create_dataset.mdx | 82 +++++++++++++++++++ datasets/concepts/datasets.mdx | 61 +++++++++++++- docs.json | 2 + 4 files changed, 209 insertions(+), 4 deletions(-) create mode 100644 api-reference/go/datasets/Create.mdx create mode 100644 api-reference/python/tilebox.datasets/Client.create_dataset.mdx diff --git a/api-reference/go/datasets/Create.mdx b/api-reference/go/datasets/Create.mdx new file mode 100644 index 0000000..94b6d01 --- /dev/null +++ b/api-reference/go/datasets/Create.mdx @@ -0,0 +1,68 @@ +--- +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 + + + The name of the dataset + + + The kind of the dataset + + + The code name of the dataset + + + The description of the dataset + + + The fields of the dataset + + +## Field options + + + Indicate that the field is an array + + + Set the description of the field to provide more context and details about the data + + + Set the example value of the field for documentation purposes + + +## Returns + +The created dataset object. + + +```go Go +dataset, err := client.Datasets.Create(ctx, + "My personal catalog", + datasets.KindSpatiotemporal, + "my_catalog", + "A summary of my catalog", + []Field{ + field.String("field1"), + field.Int64("field2").Repeated(), + field.Geometry("field3").Description("Field 3").ExampleValue("Value 3"), + }, +) +``` + diff --git a/api-reference/python/tilebox.datasets/Client.create_dataset.mdx b/api-reference/python/tilebox.datasets/Client.create_dataset.mdx new file mode 100644 index 0000000..581ce8b --- /dev/null +++ b/api-reference/python/tilebox.datasets/Client.create_dataset.mdx @@ -0,0 +1,82 @@ +--- +title: Client.create_dataset +icon: laptop-code +--- + +```python +def Client.create_dataset( + kind: DatasetKind, + code_name: str, + fields: list[FieldDict], + *, + name: str | None = None, + summary: str | None = None +) -> Dataset +``` + +Create a dataset. + +## Parameters + + + The kind of the dataset + + + The code name of the dataset + + + The fields of the dataset + + + The name of the dataset + + + A short summary of the dataset + + +## Field options + + + Set the name of the field + + + Set the type of the field + + + Set the description of the field to provide more context and details about the data + + + Set the example value of the field for documentation purposes + + +## Returns + +The created dataset object. + + +```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", +) +``` + diff --git a/datasets/concepts/datasets.mdx b/datasets/concepts/datasets.mdx index 455bbcf..55aa24b 100644 --- a/datasets/concepts/datasets.mdx +++ b/datasets/concepts/datasets.mdx @@ -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. @@ -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. +## Creating a dataset + +You can create a dataset in code or using the Console (cf [Creating a dataset using the Console](/guides/datasets/create)). + + +```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", + summary="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]"), + } +) +``` + + +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*. diff --git a/docs.json b/docs.json index df26ac6..97c5cb5 100644 --- a/docs.json +++ b/docs.json @@ -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", @@ -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", From 70d47ca2e3e8501569c66f2b221e9c77cc947e27 Mon Sep 17 00:00:00 2001 From: Corentin Musard Date: Thu, 4 Dec 2025 10:38:34 +0100 Subject: [PATCH 2/2] update reference --- api-reference/go/datasets/Create.mdx | 48 ++++++++++++++++-- .../Client.create_dataset.mdx | 50 +++++++++++++++++-- datasets/concepts/datasets.mdx | 2 +- 3 files changed, 93 insertions(+), 7 deletions(-) diff --git a/api-reference/go/datasets/Create.mdx b/api-reference/go/datasets/Create.mdx index 94b6d01..ae35fe7 100644 --- a/api-reference/go/datasets/Create.mdx +++ b/api-reference/go/datasets/Create.mdx @@ -35,15 +35,57 @@ Create a dataset. The fields of the dataset +## Dataset kinds + + + A dataset that contains a timestamp field + + + A dataset that contains a timestamp field and a geometry field + + +## Field types + + + A string field + + + A bytes field + + + A boolean field + + + A 64-bit signed integer field + + + A 64-bit unsigned integer field + + + A 64-bit floating-point number field + + + A duration field + + + A timestamp field + + + A UUID field + + + A geometry field + + ## Field options Indicate that the field is an array - + Set the description of the field to provide more context and details about the data - + Set the example value of the field for documentation purposes @@ -57,7 +99,7 @@ dataset, err := client.Datasets.Create(ctx, "My personal catalog", datasets.KindSpatiotemporal, "my_catalog", - "A summary of my catalog", + "A description of my catalog", []Field{ field.String("field1"), field.Int64("field2").Repeated(), diff --git a/api-reference/python/tilebox.datasets/Client.create_dataset.mdx b/api-reference/python/tilebox.datasets/Client.create_dataset.mdx index 581ce8b..f88d52e 100644 --- a/api-reference/python/tilebox.datasets/Client.create_dataset.mdx +++ b/api-reference/python/tilebox.datasets/Client.create_dataset.mdx @@ -10,7 +10,7 @@ def Client.create_dataset( fields: list[FieldDict], *, name: str | None = None, - summary: str | None = None + description: str | None = None ) -> Dataset ``` @@ -30,10 +30,54 @@ Create a dataset. The name of the dataset - - A short summary of the dataset + + A short description of the dataset +## Dataset kinds + + + A dataset that contains a timestamp field + + + A dataset that contains a timestamp field and a geometry field + + +## Field types + + + A string field + + + A bytes field + + + A boolean field + + + A 64-bit signed integer field + + + A 64-bit unsigned integer field + + + A 64-bit floating-point number field + + + A duration field + + + A timestamp field + + + A UUID field + + + A geometry field + + +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 diff --git a/datasets/concepts/datasets.mdx b/datasets/concepts/datasets.mdx index 55aa24b..d379516 100644 --- a/datasets/concepts/datasets.mdx +++ b/datasets/concepts/datasets.mdx @@ -185,7 +185,7 @@ dataset = client.create_dataset( }, ], name="Personal Landsat-8 catalog", - summary="This catalog contains metadata for Landsat-8 OLI-TIRS data.", + description="This catalog contains metadata for Landsat-8 OLI-TIRS data.", ) ``` ```go Go