Skip to content

Commit c6f42b0

Browse files
corentinmusardcorentinmusard
committed
Add Go datasets api reference
1 parent efbb709 commit c6f42b0

39 files changed

+494
-40
lines changed

‎.pre-commit-config.yaml

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
repos:
22
- repo: https://github.com/errata-ai/vale
3-
rev: v3.9.3
3+
rev: v3.9.5
44
hooks:
55
- id: vale

‎.vale.ini

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ MinAlertLevel = warning
1010
[formats]
1111
mdx = md
1212

13-
[*.{md, mdx}]
13+
[*.{md,mdx}]
1414

1515
# Ignore react components starting with export const
1616
# Ignore code blocks in triple backticks

‎api-reference/go/datasets/Client.Datasets.Get.mdx

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Client.Datasets.Get
3+
icon: laptop-code
4+
---
5+
6+
```go
7+
client.Datasets.Get(
8+
ctx context.Context,
9+
slug string,
10+
) (*Dataset, error)
11+
```
12+
13+
Get a dataset by its slug.
14+
15+
## Parameters
16+
17+
<ParamField path="slug" type="string">
18+
The slug of the dataset
19+
</ParamField>
20+
21+
## Returns
22+
23+
A dataset object.
24+
25+
<RequestExample>
26+
```go Go
27+
s1_sar, err := client.Datasets.Get(ctx,
28+
"open_data.copernicus.sentinel1_sar"
29+
)
30+
```
31+
</RequestExample>
32+
33+
## Errors
34+
35+
<ParamField path="not_found" type="No such dataset">
36+
The specified dataset does not exist.
37+
</ParamField>

‎api-reference/go/datasets/Client.Datasets.List.mdx

+20
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
---
2+
title: Client.Datasets.List
3+
icon: laptop-code
4+
---
5+
6+
```go
7+
client.Datasets.List(ctx context.Context) ([]*Dataset, error)
8+
```
9+
10+
Fetch all available datasets.
11+
12+
## Returns
13+
14+
A list of all available datasets.
15+
16+
<RequestExample>
17+
```go Go
18+
datasets, err := client.Datasets.List(ctx)
19+
```
20+
</RequestExample>

‎api-reference/go/datasets/client.Collections.Create.mdx

+36
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
---
2+
title: Client.Collections.Create
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Collections.Create(
8+
ctx context.Context,
9+
datasetID uuid.UUID,
10+
collectionName string,
11+
) (*Collection, error)
12+
```
13+
14+
Create a collection in the dataset.
15+
16+
## Parameters
17+
18+
<ParamField path="datasetID" type="uuid.UUID">
19+
The id of the dataset
20+
</ParamField>
21+
<ParamField path="collectionName" type="string">
22+
The name of the collection
23+
</ParamField>
24+
25+
## Returns
26+
27+
The created collection object.
28+
29+
<RequestExample>
30+
```go Go
31+
collection, err := client.Collections.Create(ctx,
32+
datasetID,
33+
"My-collection",
34+
)
35+
```
36+
</RequestExample>

‎api-reference/go/datasets/client.Collections.Get.mdx

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
---
2+
title: Client.Collections.Get
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Collections.Get(
8+
ctx context.Context,
9+
datasetID uuid.UUID,
10+
name string,
11+
) (*Collection, error)
12+
```
13+
14+
Get a dataset by its slug.
15+
16+
## Parameters
17+
18+
<ParamField path="datasetID" type="uuid.UUID">
19+
The id of the dataset
20+
</ParamField>
21+
<ParamField path="name" type="string">
22+
The name of the collection
23+
</ParamField>
24+
25+
## Returns
26+
27+
The created collection object.
28+
29+
<RequestExample>
30+
```go Go
31+
collection, err := client.Collections.Get(ctx,
32+
datasetID,
33+
"My-collection",
34+
)
35+
```
36+
</RequestExample>
37+
38+
## Errors
39+
40+
<ParamField path="not_found" type="No such dataset">
41+
The specified dataset does not exist.
42+
</ParamField>

‎api-reference/go/datasets/client.Collections.List.mdx

+37
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
title: Client.Collections.List
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Collections.List(
8+
ctx context.Context,
9+
datasetID uuid.UUID,
10+
) ([]*Collection, error)
11+
```
12+
13+
List the available collections in a dataset.
14+
15+
## Parameters
16+
17+
<ParamField path="datasetID" type="uuid.UUID">
18+
The id of the dataset
19+
</ParamField>
20+
21+
## Returns
22+
23+
A list of collection objects.
24+
25+
<RequestExample>
26+
```go Go
27+
collections, err := client.Collections.List(ctx,
28+
datasetID,
29+
)
30+
```
31+
</RequestExample>
32+
33+
## Errors
34+
35+
<ParamField path="not_found" type="No such dataset">
36+
The specified dataset does not exist.
37+
</ParamField>

‎api-reference/go/datasets/client.Datapoints.Delete.mdx

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
title: Client.Datapoints.Delete
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Datapoints.Delete(
8+
ctx context.Context,
9+
collectionID uuid.UUID,
10+
datapoints any,
11+
) (*DeleteResponse, error)
12+
```
13+
14+
Delete data points from a collection.
15+
16+
Data points are identified and deleted by their ids.
17+
18+
## Parameters
19+
20+
<ParamField path="collectionID" type="uuid.UUID">
21+
The id of the collection
22+
</ParamField>
23+
<ParamField path="datapoints" type="[]proto.Message">
24+
The datapoints to delete from the collection
25+
</ParamField>
26+
27+
## Returns
28+
29+
The number of data points that were deleted.
30+
31+
<RequestExample>
32+
```go Go
33+
var datapoints []*tileboxv1.Sentinel1Sar
34+
// assuming the slice is filled with datapoints
35+
36+
deleteResponse, err := client.Datapoints.Delete(ctx,
37+
collectionID,
38+
datapoints,
39+
)
40+
```
41+
</RequestExample>

‎api-reference/go/datasets/client.Datapoints.DeleteIDs.mdx

+39
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
---
2+
title: Client.Datapoints.DeleteIDs
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Datapoints.DeleteIDs(
8+
ctx context.Context,
9+
collectionID uuid.UUID,
10+
datapointIDs []uuid.UUID,
11+
) (*DeleteResponse, error)
12+
```
13+
14+
Delete data points from a collection.
15+
16+
## Parameters
17+
18+
<ParamField path="collectionID" type="uuid.UUID">
19+
The id of the collection
20+
</ParamField>
21+
<ParamField path="datapointIDs" type="[]uuid.UUID">
22+
The ids of the data points to delete from the collection
23+
</ParamField>
24+
25+
## Returns
26+
27+
The number of data points that were deleted.
28+
29+
<RequestExample>
30+
```go Go
31+
deleteResponse, err := client.Datapoints.DeleteIDs(ctx,
32+
collectionID,
33+
[]uuid.UUID{
34+
uuid.MustParse("0195c87a-49f6-5ffa-e3cb-92215d057ea6"),
35+
uuid.MustParse("0195c87b-bd0e-3998-05cf-af6538f34957"),
36+
},
37+
)
38+
```
39+
</RequestExample>

‎api-reference/go/datasets/client.Datapoints.Ingest.mdx

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Client.Datapoints.Ingest
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Datapoints.Ingest(
8+
ctx context.Context,
9+
collectionID uuid.UUID,
10+
datapoints any,
11+
allowExisting bool,
12+
) (*IngestResponse, error)
13+
```
14+
15+
Ingest data points into a collection.
16+
17+
## Parameters
18+
19+
<ParamField path="collectionID" type="uuid.UUID">
20+
The id of the collection
21+
</ParamField>
22+
<ParamField path="datapoints" type="[]proto.Message">
23+
The datapoints to ingest
24+
</ParamField>
25+
<ParamField path="allowExisting" type="bool">
26+
Datapoint fields are used to generate a deterministic unique `UUID` for each
27+
datapoint in a collection. Duplicate data points result in the same ID being generated.
28+
If `allowExisting` is `true`, `ingest` will skip those datapoints, since they already exist.
29+
If `allowExisting` is `false`, `ingest` will raise an error if any of the generated datapoint IDs already exist.
30+
</ParamField>
31+
32+
## Returns
33+
34+
The list of datapoint ids that were ingested, including the IDs of existing data points in case of duplicates and
35+
`allowExisting=true`.
36+
37+
<RequestExample>
38+
```go Go
39+
datapoints := []*tileboxv1.Modis{
40+
tileboxv1.Modis_builder{
41+
Time: timestamppb.New(time.Now()),
42+
GranuleName: proto.String("Granule 1"),
43+
}.Build(),
44+
tileboxv1.Modis_builder{
45+
Time: timestamppb.New(time.Now().Add(-5 * time.Hour)),
46+
GranuleName: proto.String("Past Granule 2"),
47+
}.Build(),
48+
}
49+
50+
ingestResponse, err := client.Datapoints.Ingest(ctx,
51+
collectionID,
52+
datapoints
53+
false,
54+
)
55+
```
56+
</RequestExample>
57+
58+
## Errors
59+
60+
<ParamField path="ArgumentError" type="found existing datapoints with same id">
61+
If `allowExisting` is `False` and any of the datapoints attempting to ingest already exist.
62+
</ParamField>

‎api-reference/go/datasets/client.Datapoints.Load.mdx

+52
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: Client.Datapoints.Load
3+
icon: layer-group
4+
---
5+
6+
```go
7+
client.Datapoints.Load(
8+
ctx context.Context,
9+
collectionID uuid.UUID,
10+
interval interval.LoadInterval,
11+
options ...LoadOption,
12+
) iter.Seq2[[]byte, error]
13+
```
14+
15+
Load a range of data points in this collection in a specified interval.
16+
17+
The datapoints are loaded in a lazy manner, and returned as a sequence of bytes.
18+
The output sequence can be transformed into a typed `proto.Message` using `CollectAs` or `As` functions.
19+
20+
## Parameters
21+
22+
<ParamField path="collectionID" type="uuid.UUID">
23+
The id of the collection
24+
</ParamField>
25+
<ParamField path="interval" type="interval.LoadInterval">
26+
The interval for which to load data points
27+
</ParamField>
28+
<ParamField path="options" type="[]LoadOption">
29+
Options for loading data points
30+
</ParamField>
31+
32+
## Returns
33+
34+
A sequence of bytes containing the requested data points as bytes.
35+
36+
<RequestExample>
37+
```go Go
38+
import (
39+
"time"
40+
"github.com/tilebox/tilebox-go/interval"
41+
datasets "github.com/tilebox/tilebox-go/datasets/v1"
42+
)
43+
44+
startDate := time.Date(2014, 10, 4, 0, 0, 0, 0, time.UTC)
45+
endDate := time.Date(2021, 2, 24, 0, 0, 0, 0, time.UTC)
46+
loadInterval := interval.NewStandardTimeInterval(startDate, endDate)
47+
48+
datapoints, err := datasets.CollectAs[*tileboxv1.Sentinel1Sar](
49+
client.Datapoints.Load(ctx, collectionID, loadInterval),
50+
)
51+
```
52+
</RequestExample>

0 commit comments

Comments
 (0)