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

**Python**

```python title="Python"
from tilebox.datasets import Client

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

**Go**

```go title="Go"
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**

```python title="Python"
collections = dataset.collections()
print(collections)
```

**Go**

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

log.Println(collections)
```

```plaintext title="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](/docs/api-reference/python/tilebox.datasets/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()](/docs/api-reference/python/tilebox.datasets/Dataset.create_collection). This method returns the created collection object.

**Python**

```python title="Python"
collection = dataset.create_collection("My-collection")
```

**Go**

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

You can use [dataset.get\_or\_create\_collection()](/docs/api-reference/python/tilebox.datasets/Dataset.get_or_create_collection) to get a collection by its name. If the collection does not exist, it will be created.

**Python**

```python title="Python"
collection = dataset.get_or_create_collection("My-collection")
```

**Go**

```go title="Go"
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()](/docs/api-reference/python/tilebox.datasets/Dataset.collections), you can access a specific collection by retrieving it from the resulting dictionary with its name. Use [collection.info()](/docs/api-reference/python/tilebox.datasets/Collection.info) in Python or `String()` in Go to get details (name, availability, and count) about it.

**Python**

```python title="Python"
collections = dataset.collections()
terrain_correction = collections["L1GT"]
collection_info = terrain_correction.info()
print(collection_info)
```

**Go**

```go title="Go"
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())
```

```plaintext title="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](/docs/api-reference/python/tilebox.datasets/Dataset.collection) method on the dataset object. This method allows you to get the collection without having to list all collections first.

**Python**

```python title="Python"
terrain_correction = dataset.collection("L1GT")
collection_info = terrain_correction.info()
print(collection_info)
```

**Go**

```go title="Go"
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())
```

```plaintext title="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.

**Python**

```python title="Python"
dataset.delete_collection(collection)
```

**Go**

```go title="Go"
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**

```python title="Python"
dataset.collection("Sat-X").info() # raises NotFoundError: 'No such collection Sat-X'
```

**Go**

```go title="Go"
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](/docs/datasets/query/querying-data)

Learn how to query data from a collection.