Collections

Collections organize data points within a dataset into logical groups that are commonly queried together, such as groupings by satellite or instrument.

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.

Python
Go

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.

Python
Go

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)

{'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.

Python
Go

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.

Python
Go

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.

Python
Go

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())

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.

Python
Go

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())

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.

Python
Go

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:

Python
Go

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.