Collections

Collections group data points within a dataset. They help represent logical groupings of data points that are commonly queried together. For example, if your dataset includes data from a specific instrument on different satellites, you can group the data points from each satellite into a collection. Refer to the examples below for common use cases when working with collections. These examples assume that you have already created a client and selected a dataset as shown below.

from tilebox.datasets import Client

client = Client()
datasets = client.datasets()
dataset = datasets.open_data.copernicus.landsat8_oli_tirs

package main

import (
	"context"
	"log"

	"github.com/tilebox/tilebox-go/datasets/v1"
)

func main() {
	ctx := context.Background()
	client := datasets.NewClient()

	dataset, err := client.Datasets.Get(ctx, "open_data.copernicus.landsat8_oli_tirs")
	if err != nil {
		log.Fatalf("Failed to get dataset: %v", err)
	}
}

Listing collections

To list the collections for a dataset, use the collections method on the dataset object.

collections = dataset.collections()
print(collections)

collections, err := client.Collections.List(ctx, dataset.ID)
if err != nil {
  log.Fatalf("Failed to list collections: %v", err)
}

log.Println(collections)

Output

{'L1GT': Collection L1GT: [2013-03-25T12:08:43.699 UTC, 2024-08-19T12:57:32.456 UTC] (154288 data points),
 'L1T': Collection L1T: [2013-03-26T09:33:19.763 UTC, 2020-08-24T03:21:50.000 UTC] (87958 data points),
 'L1TP': Collection L1TP: [2013-03-24T00:25:55.457 UTC, 2024-08-19T12:58:20.229 UTC] (322041 data points),
 'L2SP': Collection L2SP: [2015-01-01T07:53:35.391 UTC, 2024-08-12T12:52:03.243 UTC] (191110 data points)}

dataset.collections returns a dictionary mapping collection names to their corresponding collection objects. Each collection has a unique name within its dataset.

Creating collections

To create a collection in a dataset, use dataset.create_collection(). This method returns the created collection object.

collection = dataset.create_collection("My-collection")

collection, err := client.Collections.Create(ctx, dataset.ID, "My-collection")

You can use dataset.get_or_create_collection() to get a collection by its name. If the collection does not exist, it will be created.

collection = dataset.get_or_create_collection("My-collection")

collection, err := client.Collections.GetOrCreate(ctx, dataset.ID, "My-collection")

Accessing individual collections

Once you have listed the collections for a dataset using dataset.collections(), you can access a specific collection by retrieving it from the resulting dictionary with its name. Use collection.info() in Python or String() in Go to get details (name, availability, and count) about it.

collections = dataset.collections()
terrain_correction = collections["L1GT"]
collection_info = terrain_correction.info()
print(collection_info)

dataset, err := client.Datasets.Get(ctx, "open_data.copernicus.landsat8_oli_tirs")
if err != nil {
  log.Fatalf("Failed to get dataset: %v", err)
}

collection, err := client.Collections.Get(ctx, dataset.ID, "L1GT")
if err != nil {
  log.Fatalf("Failed to get collection: %v", err)
}

log.Println(collection.String())

Output

L1GT: [2013-03-25T12:08:43.699 UTC, 2024-08-19T12:57:32.456 UTC] (154288 data points)

You can also access a specific collection directly using the dataset.collection method on the dataset object. This method allows you to get the collection without having to list all collections first.

terrain_correction = dataset.collection("L1GT")
collection_info = terrain_correction.info()
print(collection_info)

dataset, err := client.Datasets.Get(ctx, "open_data.copernicus.landsat8_oli_tirs")
if err != nil {
  log.Fatalf("Failed to get dataset: %v", err)
}

collection, err := client.Collections.Get(ctx, dataset.ID, "L1GT")
if err != nil {
  log.Fatalf("Failed to get collection: %v", err)
}

log.Println(collection.String())

Output

L1GT: [2013-03-25T12:08:43.699 UTC, 2024-08-19T12:57:32.456 UTC] (154288 data points)

Deleting collections

Collections can be deleted from a dataset using the delete_collection method. To delete a collection, you need to have write permission on the dataset.

Deleting a collection will delete all data points in the collection.

dataset.delete_collection(collection)

err := client.Collections.Delete(ctx, dataset.ID, collection.ID)

Errors you may encounter

NotFoundError

If you attempt to access a collection with a non-existent name, a NotFoundError is raised. For example:

dataset.collection("Sat-X").info() # raises NotFoundError: 'No such collection Sat-X'

collection, err := client.Collections.Get(ctx, dataset.ID, "Sat-X")
if err != nil {
  log.Fatal(err) // prints 'failed to get collections: not_found: no such collection'
}

Next steps

Query Data

Learn how to query data from a collection.

Get Started

Agents and AI Tools

Datasets

Workflows

Listing collections

Creating collections

Accessing individual collections

Deleting collections

Errors you may encounter

NotFoundError

Next steps

Query Data