---
title: "Client.create_or_update_dataset"
description: "Create a dataset, or update the existing dataset with the same code name."
image: "https://tilebox.com/images/tilebox-docs-social-preview.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://tilebox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Client.create_or_update_dataset

import { Fragment } from "astro/jsx-runtime";

import ApiReference from "@docs/components/ApiReference.astro";

import ParamField from "@docs/components/ParamField.astro";

```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.

## Parameters

**kind**

type: DatasetKind

The kind of the dataset.
**code_name**

type: str

The code name of the dataset.
**fields**

type: list[FieldDict] | None

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

type: 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**

type: DatasetKind

A dataset that contains a timestamp field
**DatasetKind.SPATIOTEMPORAL**

type: DatasetKind

A dataset that contains a timestamp field and a geometry field

## Field types

**str**

type: type

A string field
**bytes**

type: type

A bytes field
**bool**

type: type

A boolean field
**int**

type: type

A 64-bit signed integer field
**np.uint64**

type: type

A 64-bit unsigned integer field
**float**

type: type

A 64-bit floating-point number field
**datetime.timedelta**

type: type

A duration field
**datetime.datetime**

type: type

A timestamp field
**uuid.UUID**

type: type

A UUID field
**shapely.Geometry**

type: type

A geometry field
**Assets**

type: type

STAC asset metadata. Import from `tilebox.datasets.schema`.
**Authentication**

type: type

STAC authentication metadata. Import from `tilebox.datasets.schema`.
**Links**

type: type

STAC link metadata. Import from `tilebox.datasets.schema`.
**ProcessingSoftware**

type: type

STAC processing software metadata. Import from `tilebox.datasets.schema`.
**Provider**

type: type

STAC provider metadata. Import from `tilebox.datasets.schema`.
**Storage**

type: 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**

type: str

required: true

Set the name of the field
**type**

type: type

required: true

Set the type of the field
**description**

type: str

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

type: str

Set the example value of the field for documentation purposes
**source_json_pointer**

type: 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**

type: 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**

type: 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**

type: 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](/docs/datasets/concepts/datasets#queryable-fields) for schema constraints and
[Filter by custom fields](/docs/datasets/query/filter-by-fields) for query syntax.

## Returns

A `DatasetClient` for the created or updated dataset.

<h2 id="request-example">Usage example</h2>

```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",
)
```

Source: https://tilebox.com/docs/api-reference/python/tilebox.datasets/Client.create_or_update_dataset/index.mdx