Skip to content

Client.create_or_update_dataset

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

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.

You can append allowed enum values after ingesting data. To remove, rename, or reorder them, the dataset must be empty. Include the full custom field list when updating a dataset; see updating enum values.

Parameters

kind DatasetKind

The kind of the dataset.

code_name str

The code name of the dataset.

fields list[FieldDict] | None

The full custom field list 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

"enum"

A custom enum field. Set type to the string "enum" and list its allowed strings in enum_values. See scalar and repeated enum declarations.

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.

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.

For non-enum types, use list[T] to declare an array, such as list[str]. For custom enums, keep type="enum" and set repeated=True instead.

Field options

name str required

Set the name of the field

type type | Literal["enum"] required

Set the type of the field. Custom enums use the string "enum".

enum_values list[str]

Required for type="enum"; invalid on other field types. Supply 1–100 unique, nonempty, case-sensitive strings. Values can contain punctuation and Unicode characters. Add new values here before ingesting data that uses them.

repeated bool

Default: False

Make a custom enum field repeated, accepting zero or more declared values per datapoint. Use list[T] for other repeated field types.

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. Supported types are non-repeated str, bool, int, np.uint64, and float, plus scalar or repeated custom enums. A dataset can contain at most two queryable string fields; custom enums do not count toward this limit.

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.

Type to search…