Reference assets in a dataset

Reference files that already exist in object storage, behind HTTP URLs, or on a local filesystem by adding asset fields to your dataset schema and ingestion records.

Add structured STAC fields

Tilebox provides the following structured field types for STAC-compatible datasets. See dataset field types for the complete list of supported types.

Field type	Purpose
`Assets`	References files associated with a datapoint, including their locations, media types, roles, and optional metadata.
`Storage`	Describes reusable storage schemes.
`Authentication`	Describes reusable access methods.
`Links`	References related STAC resources.
`Provider`	Identifies organizations that produce, process, license, or host data.
`ProcessingSoftware`	Records software and versions used to process data.

Both Assets and Links can reference entries in the storage and authentication registries. In Python, AssetCollection combines assets with optional storage and authentication entries needed to access them. Add the assets, storage, and authentication fields explicitly when you create the dataset:

from tilebox.datasets import Client
from tilebox.datasets.data.datasets import DatasetKind
from tilebox.datasets.schema import Assets, Authentication, Storage

client = Client()
dataset = client.create_or_update_dataset(
    kind=DatasetKind.SPATIOTEMPORAL,
    code_name="imagery_catalog",
    fields=[
        {"name": "product_id", "type": str},
        {"name": "assets", "type": Assets},
        {"name": "storage", "type": Storage},
        {"name": "authentication", "type": Authentication},
    ],
    name="Imagery catalog",
)
collection = dataset.get_or_create_collection("products")

import (
	"github.com/tilebox/tilebox-go/datasets/v1"
	"github.com/tilebox/tilebox-go/datasets/v1/field"
	stacv1 "github.com/tilebox/tilebox-go/protogen/datasets/stac/v1"
)

fields := []datasets.Field{
	field.String("product_id"),
	field.Message("assets", &stacv1.Assets{}),
	field.Message("storage", &stacv1.Storage{}),
	field.Message("authentication", &stacv1.Authentication{}),
}

dataset, err := client.Datasets.CreateOrUpdate(
	ctx,
	datasets.KindSpatiotemporal,
	"imagery_catalog",
	"Imagery catalog",
	fields,
)

Prepare assets for ingestion

Construct assets from their source locations, then check and normalize the collection. This ensures that the storage client can read the referenced bytes. to_fields() converts the collection into fields for a complete datapoint record.

from tilebox.datasets.assets import (
    Asset,
    AssetCollection,
    AssetLocation,
    MediaType,
)
from shapely import box

assets = AssetCollection.from_assets([
    Asset(
        key="image",
        primary=AssetLocation("s3://example-bucket/scenes/scene-1.tif"),
        media_type=MediaType.CLOUD_OPTIMIZED_GEOTIFF,
        roles=frozenset({"data"}),
    ),
])

record = {
    "time": "2026-07-31T10:00:00Z",
    "geometry": box(16.25, 48.15, 16.35, 48.22),
    "product_id": "scene-1",
    **assets.to_fields(),
}

collection.ingest([record])

import stacv1 "github.com/tilebox/tilebox-go/protogen/datasets/stac/v1"

profileIndex := uint32(0)
href := "scenes/scene-1.tif"
mediaType := stacv1.KnownMediaType_KNOWN_MEDIA_TYPE_CLOUD_OPTIMIZED_GEOTIFF

assets := stacv1.Assets_builder{
	AccessProfiles: []*stacv1.AssetAccessProfile{
		stacv1.AssetAccessProfile_builder{
			BaseHref: "https://example-bucket.s3.eu-central-1.amazonaws.com/",
		}.Build(),
	},
	Assets: []*stacv1.Asset{
		stacv1.Asset_builder{
			Key: "image",
			Primary: stacv1.AssetLocation_builder{
				AccessProfileIndex: &profileIndex,
				Href:               &href,
			}.Build(),
			MediaType: stacv1.MediaType_builder{Known: &mediaType}.Build(),
			Roles: []stacv1.KnownAssetRole{
				stacv1.KnownAssetRole_KNOWN_ASSET_ROLE_DATA,
			},
		}.Build(),
	},
}.Build()

// Use the generated datapoint type for your dataset.
record := catalogv1.Scene_builder{
	Time:      timestamp,
	Geometry:  geometry,
	ProductId: new("scene-1"),
	Assets:    assets,
}.Build()

Pass the complete record to the standard datapoint ingestion API.

Add more asset metadata

Assets can also describe alternate locations, bands, and metadata from STAC extensions such as Raster, Electro-Optical, and Projection. See the Asset API reference for the available fields.

Build a spatio-temporal catalog

Create a dataset that combines searchable metadata with file references.

Read and download assets

Access the referenced files with the storage client.

Get Started

Agents and AI Tools

Datasets

Workflows

Reference assets in a dataset

Add structured STAC fields

Prepare assets for ingestion

Add more asset metadata

Build a spatio-temporal catalog

Read and download assets

​Add structured STAC fields

​Prepare assets for ingestion

​Add more asset metadata

Build a spatio-temporal catalog

Read and download assets

Add structured STAC fields

Prepare assets for ingestion

Add more asset metadata