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

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

<CodeGroup>
  ```python Python theme={"system"}
  from tilebox.datasets import Client

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

  ```go Go theme={"system"}
  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)
  	}
  }
  ```
</CodeGroup>

## Listing collections

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

<CodeGroup>
  ```python Python theme={"system"}
  collections = dataset.collections()
  print(collections)
  ```

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

  log.Println(collections)
  ```
</CodeGroup>

```plaintext Output theme={"system"}
{'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](/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()](/api-reference/python/tilebox.datasets/Dataset.create_collection). This method returns the created collection object.

<CodeGroup>
  ```python Python theme={"system"}
  collection = dataset.create_collection("My-collection")
  ```

  ```go Go theme={"system"}
  collection, err := client.Collections.Create(ctx, dataset.ID, "My-collection")
  ```
</CodeGroup>

You can use [dataset.get\_or\_create\_collection()](/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.

<CodeGroup>
  ```python Python theme={"system"}
  collection = dataset.get_or_create_collection("My-collection")
  ```

  ```go Go theme={"system"}
  collection, err := client.Collections.GetOrCreate(ctx, dataset.ID, "My-collection")
  ```
</CodeGroup>

## Accessing individual collections

Once you have listed the collections for a dataset using [dataset.collections()](/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()](/api-reference/python/tilebox.datasets/Collection.info) in Python or `String()` in Go to get details (name, availability, and count) about it.

<CodeGroup>
  ```python Python theme={"system"}
  collections = dataset.collections()
  terrain_correction = collections["L1GT"]
  collection_info = terrain_correction.info()
  print(collection_info)
  ```

  ```go Go theme={"system"}
  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())
  ```
</CodeGroup>

```plaintext Output theme={"system"}
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](/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.

<CodeGroup>
  ```python Python theme={"system"}
  terrain_correction = dataset.collection("L1GT")
  collection_info = terrain_correction.info()
  print(collection_info)
  ```

  ```go Go theme={"system"}
  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())
  ```
</CodeGroup>

```plaintext Output theme={"system"}
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.

<Warning>
  Deleting a collection will delete all data points in the collection.
</Warning>

<CodeGroup>
  ```python Python theme={"system"}
  dataset.delete_collection(collection)
  ```

  ```go Go theme={"system"}
  err := client.Collections.Delete(ctx, dataset.ID, collection.ID)
  ```
</CodeGroup>

## Errors you may encounter

### NotFoundError

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

<CodeGroup>
  ```python Python theme={"system"}
  dataset.collection("Sat-X").info() # raises NotFoundError: 'No such collection Sat-X'
  ```

  ```go Go theme={"system"}
  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'
  }
  ```
</CodeGroup>

## Next steps

<Columns cols={2}>
  <Card title="Query Data" icon="server" href="/datasets/query/querying-data" horizontal>
    Learn how to query data from a collection.
  </Card>
</Columns>