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,
) -> DatasetClientCreate 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.
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.
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.