Client.create_or_update_dataset

def Client.create_or_update_dataset(
    kind: DatasetKind,
    code_name: str,
    fields: list[FieldDict] | None = None,
    *,
    name: str | None = None,
) -> DatasetClient

Copy

Create a dataset, or update the existing dataset with the same code name.

New non-queryable fields can be added to a non-empty dataset. Changing whether an existing field is queryable or adding a new queryable field is only supported while the dataset is empty.

Parameters

kind DatasetKind

The kind of the dataset.

code_name str

The code name of the dataset.

fields list[FieldDict] | None

The custom fields of the dataset. Defaults to an empty field list.

name str | None

The display name of the dataset. Defaults to the code name when creating a dataset, and to the existing name when updating a dataset.

Dataset kinds

DatasetKind.TEMPORAL DatasetKind

A dataset that contains a timestamp field

DatasetKind.SPATIOTEMPORAL DatasetKind

A dataset that contains a timestamp field and a geometry field

Field types

str type

A string field

bytes type

A bytes field

bool type

A boolean field

int type

A 64-bit signed integer field

np.uint64 type

A 64-bit unsigned integer field

float type

A 64-bit floating-point number field

datetime.timedelta type

A duration field

datetime.datetime type

A timestamp field

uuid.UUID type

A UUID field

shapely.Geometry type

A geometry field

Assets type

STAC asset metadata. Import from tilebox.datasets.schema.

Authentication type

STAC authentication metadata. Import from tilebox.datasets.schema.

Links type

STAC link metadata. Import from tilebox.datasets.schema.

ProcessingSoftware type

STAC processing software metadata. Import from tilebox.datasets.schema.

Provider type

STAC provider metadata. Import from tilebox.datasets.schema.

Storage type

STAC storage metadata. Import from tilebox.datasets.schema.

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

Field options

name str required

Set the name of the field

type type required

Set the type of the field

description str

Set the description of the field to provide more context and details about the data

example_value str

Set the example value of the field for documentation purposes

source_json_pointer str | None

Optional. Set the RFC 6901 path to this field in the source JSON, such as /properties/eo:cloud_cover. This is useful when transforming datapoints to JSON because Tilebox can reconstruct nested source objects from flattened dataset fields.

queryable bool

Make the field available for server-side custom field filters. Queryable fields must be non-repeated str, bool, int, np.uint64, or float fields. A dataset can contain at most two queryable string fields.

json_schema_ref str | None

Optional. Set a JSON Schema reference URI or URI fragment for the field. Use this when the field follows a well-known schema, such as a STAC extension. Tilebox emits the reference as $ref when advertising the field in STAC queryables.

roles list[FieldRole] | list[Literal["primary_title"]]

Set semantic display roles for the field. The only currently supported role is primary_title.

Queryable string values can contain at most 1,024 Unicode code points. See Queryable fields for schema constraints and Filter by custom fields for query syntax.

Returns

A DatasetClient for the created or updated dataset.

Request example

Python

from shapely import Geometry
from tilebox.datasets import Client
from tilebox.datasets.data.datasets import DatasetKind

client = Client()

dataset = client.create_or_update_dataset(
    kind=DatasetKind.SPATIOTEMPORAL,
    code_name="my_catalog",
    fields=[
        {
            "name": "platform",
            "type": str,
            "queryable": True,
        },
        {
            "name": "cloud_cover",
            "type": float,
            "queryable": True,
        },
        {
            "name": "shape",
            "type": list[int],
        },
        {
            "name": "footprint",
            "type": Geometry,
            "description": "Source product footprint",
            "example_value": "POLYGON ((11 46, 12 46, 12 47, 11 47, 11 46))",
        },
    ],
    name="My personal catalog",
)

Copy