Document queries across multiple collections

AGENTS.md

@@ -0,0 +1,146 @@
+# AGENTS.md
+
+## Purpose
+
+This repository contains the Mintlify source for [docs.tilebox.com](https://docs.tilebox.com). Use this file to keep documentation updates consistent with the current information architecture, writing style, and tooling.
+
+## Information Architecture
+
+Navigation is defined in `docs.json` and currently follows this top-level structure:
+
+1. `Documentation`: product docs, concepts, and capability docs for Datasets, Storage, and Workflows.
+2. `User Guides`: task-focused walkthroughs (mostly step-by-step procedures).
+3. `Languages & SDKs`: language-specific install and usage docs for Python and Go.
+4. `API Reference`: method-level reference pages for Python and Go clients.
+5. `Changelog`: product updates.
+
+When adding or moving pages:
+
+1. Keep `docs.json` in sync with actual files.
+2. Keep pages grouped by product area (`datasets/`, `workflows/`, `storage/`, `sdks/`, `guides/`, `api-reference/`).
+3. Preserve the current pattern where high-level landing pages link to deeper pages via `Card`/`HeroCard` blocks.
+
+## Diátaxis Mapping
+
+We follow [Diátaxis](https://diataxis.fr/). Pick one primary intent per page and keep it focused.
+
+1. Tutorial: onboarding learning journeys (for example `quickstart.mdx`).
+2. How-to guide: concrete goals via ordered steps (primarily under `guides/**`).
+3. Explanation: conceptual understanding and mental models (for example `datasets/concepts/**`, `workflows/concepts/**`, introductions).
+4. Reference: factual lookup docs (primarily `api-reference/**`, parameter tables, changelog entries).
+
+Practical rule: if a page starts drifting into multiple intents, split it into separate pages and cross-link them.
+
+## Writing Style And Tone
+
+Follow the existing house style:
+
+1. Audience: developers and technical users integrating Tilebox.
+2. Voice: direct, clear, and pragmatic; prefer active voice and short paragraphs.
+3. Person: usually second person (`you`) for guidance.
+4. Tense: present tense for behavior and capabilities.
+5. Scope: explain what the reader needs now; avoid broad marketing language.
+
+Common page flow patterns in this repo:
+
+1. Short context paragraph after frontmatter.
+2. `Related documentation` card section when useful.
+3. Step-by-step sections for procedures.
+4. `Next steps` links/cards at the end.
+
+## Terminology, Capitalization, And Naming
+
+Use consistent product language:
+
+1. `Tilebox` (capital T) everywhere.
+2. Product/module names: `Tilebox Console`, `Tilebox Datasets`, `Tilebox Workflows`.
+3. Generic references are lowercase: `datasets`, `workflows`, `client`, `collection`, `job`, `task`.
+4. Dataset kind names used in docs: `Timeseries` and `Spatio-temporal`.
+5. Keep acronyms uppercase (`API`, `SDK`, `MCP`, `UUID`, `UTC`).
+
+Heading style in the existing docs is mostly concise sentence-style phrases (with selective title casing). Match nearby pages rather than enforcing a new global style.
+
+## MDX And Mintlify Conventions
+
+For new non-reference pages, include frontmatter fields matching existing docs:
+
+1. `title`
+2. `description`
+3. `icon`
+4. Optional short `sidebarTitle` if the title is too long.
+
+Prefer existing Mintlify components and patterns:
+
+1. `CodeGroup` for multi-language examples (usually Python first, Go second when both exist).
+2. `Steps`/`Step` for procedural flows.
+3. `Tip`/`Note`/`Info`/`Warning` for callouts.
+4. `Columns` + `Card` for internal navigation.
+5. `Frame` for screenshots.
+
+Images should follow the existing light/dark pattern when both variants exist:
+
+```mdx
+<img src="/path/light.png" className="dark:hidden" />
+<img src="/path/dark.png" className="hidden dark:block" />
+```
+
+## Dev Tooling
+
+Core tooling used in this repo:
+
+1. Mintlify CLI for local preview and link checks.
+2. Vale for prose linting.
+3. `pre-commit` hook running Vale.
+4. GitHub Actions CI for Vale + broken link checks.
+
+Local setup and validation commands:
+
+```bash
+# install tooling
+npm i -g mintlify
+vale sync
+pre-commit install
+
+# run docs locally
+mintlify dev
+
+# lint prose
+vale .
+
+# check broken links
+mintlify broken-links
+
+# optional: run all hooks
+pre-commit run --all-files
+```
+
+CI notes:
+
+1. CI installs Node `24`.
+2. CI installs `mdx2vast` before running Vale.
+3. CI runs `vale sync && vale .` and `mintlify broken-links`.
+
+## Diagrams And Assets
+
+Workflow diagrams under `assets/workflows/diagrams/` are generated from `.d2` files via `generate.py`.
+
+When updating workflow diagrams:
+
+1. Edit the `.d2` source.
+2. Regenerate SVG assets with `python generate.py` from `assets/workflows/diagrams/`.
+3. Commit both source and generated SVG outputs.
+
+## Update Checklist For Agents
+
+For any substantial docs update, verify all of the following:
+
+1. Page intent matches a single Diátaxis category.
+2. Page is linked in `docs.json` in the correct section.
+3. Internal links resolve and `mintlify broken-links` passes.
+4. Vale warnings/errors are addressed or intentionally accepted.
+5. New screenshots/assets are optimized and use correct paths.
+6. Language and terminology match surrounding Tilebox docs.
+
+## Notes On API Reference Pages
+
+`api-reference/**` pages are reference-first and should remain concise and factual. Keep examples minimal and parameter descriptions explicit. Avoid turning reference pages into long tutorials; link to guides instead.

api-reference/go/datasets/As.mdx

@@ -35,7 +35,12 @@ endDate := time.Date(2021, 2, 24, 0, 0, 0, 0, time.UTC)
 queryInterval := query.NewTimeInterval(startDate, endDate)
 
 seq := datasets.As[*v1.Sentinel1Sar](
-    client.Datapoints.Query(ctx, collectionID, datasets.WithTemporalExtent(queryInterval)),
+    client.Datapoints.Query(
+      ctx,
+      datasetID,
+      datasets.WithCollectionIDs(collectionID),
+      datasets.WithTemporalExtent(queryInterval),
+    ),
 )
 ```
 </RequestExample>

api-reference/go/datasets/Collect.mdx

@@ -35,7 +35,12 @@ endDate := time.Date(2021, 2, 24, 0, 0, 0, 0, time.UTC)
 queryInterval := query.NewTimeInterval(startDate, endDate)
 
 datapoints, err := datasets.Collect(datasets.As[*v1.Sentinel1Sar](
-    client.Datapoints.Query(ctx, collectionID, datasets.WithTemporalExtent(queryInterval)),
+    client.Datapoints.Query(
+      ctx,
+      datasetID,
+      datasets.WithCollectionIDs(collectionID),
+      datasets.WithTemporalExtent(queryInterval),
+    ),
 ))
 ```
 </RequestExample>

api-reference/go/datasets/CollectAs.mdx

@@ -37,7 +37,12 @@ endDate := time.Date(2021, 2, 24, 0, 0, 0, 0, time.UTC)
 queryInterval := query.NewTimeInterval(startDate, endDate)
 
 datapoints, err := datasets.CollectAs[*v1.Sentinel1Sar](
-    client.Datapoints.Query(ctx, collectionID, datasets.WithTemporalExtent(queryInterval)),
+    client.Datapoints.Query(
+      ctx,
+      datasetID,
+      datasets.WithCollectionIDs(collectionID),
+      datasets.WithTemporalExtent(queryInterval),
+    ),
 )
 ```
 </RequestExample>

api-reference/go/datasets/Datapoints.GetInto.mdx

@@ -7,21 +7,21 @@ icon: layer-group
 ```go
 func (datapointClient) GetInto(
   ctx context.Context,
-  collectionIDs []uuid.UUID,
+  datasetID uuid.UUID,
   datapointID uuid.UUID,
   datapoint proto.Message,
   options ...QueryOption,
 ) error
 ```
 
-Get a data point by its id from one of the specified collections.
+Get a datapoint by its ID from one or more collections of the same dataset.
 
 The data point is stored in the `datapoint` parameter.
 
 ## Parameters
 
-<ParamField path="collectionIDs" type="[]uuid.UUID">
-  The ids of the collections to query
+<ParamField path="datasetID" type="uuid.UUID">
+  The ID of the dataset to query.
 </ParamField>
 <ParamField path="datapointID" type="uuid.UUID">
   The id of the datapoint to query
@@ -35,6 +35,12 @@ The data point is stored in the `datapoint` parameter.
 
 ## Options
 
+<ParamField path="WithCollections(collections ...*datasets.Collection)">
+  Restrict the lookup to specific dataset collections by collection object.
+</ParamField>
+<ParamField path="WithCollectionIDs(collectionIDs ...uuid.UUID)">
+  Restrict the lookup to specific dataset collections by collection ID.
+</ParamField>
 <ParamField path="WithSkipData()" default="false">
   Skip the data when querying datapoint.
   If set, only the required and auto-generated fields will be returned.
@@ -48,7 +54,10 @@ An error if data point could not be queried.
 ```go Go
 var datapoint v1.Sentinel1Sar
 err = client.Datapoints.GetInto(ctx,
-  []uuid.UUID{collection.ID}, datapointID, &datapoint,
+  dataset.ID,
+  datapointID,
+  &datapoint,
+  datasets.WithCollectionIDs(collection.ID),
 )
 ```
 </RequestExample>

api-reference/go/datasets/Datapoints.Query.mdx

@@ -7,23 +7,23 @@ icon: layer-group
 ```go
 func (datapointClient) Query(
     ctx context.Context,
-    collectionIDs []uuid.UUID,
+    datasetID uuid.UUID,
     options ...datasets.QueryOption,
 ) iter.Seq2[[]byte, error]
 ```
 
-Query a range of data points in the specified collections in a specified interval.
+Query datapoints from one or more collections of the same dataset.
 
 The datapoints are lazily queried and returned as a sequence of bytes.
 The output sequence can be transformed into a typed `proto.Message` using [CollectAs](/api-reference/go/datasets/CollectAs) or [As](/api-reference/go/datasets/As) functions.
 
 ## Parameters
 
-<ParamField path="collectionIDs" type="[]uuid.UUID">
-  The ids of the collections to query
+<ParamField path="datasetID" type="uuid.UUID">
+  The ID of the dataset to query.
 </ParamField>
 <ParamField path="options" type="[]datasets.QueryOption">
-  Options for querying data points
+  Options for querying datapoints.
 </ParamField>
 
 ## Options
@@ -36,6 +36,15 @@ The output sequence can be transformed into a typed `proto.Message` using [Colle
   Specify the geographical extent in which to query data.
   Optional, if not specified the query will return all results found globally.
 </ParamField>
+<ParamField path="WithSpatialExtentFilter(spatialExtent query.SpatialExtent)">
+  Specify a geographical extent with an explicit spatial filter mode and coordinate system.
+</ParamField>
+<ParamField path="WithCollections(collections ...*datasets.Collection)">
+  Restrict the query to specific dataset collections by collection object.
+</ParamField>
+<ParamField path="WithCollectionIDs(collectionIDs ...uuid.UUID)">
+  Restrict the query to specific dataset collections by collection ID.
+</ParamField>
 <ParamField path="WithSkipData()" default="false">
   Skip the data when querying datapoints.
   If set, only the required and auto-generated fields will be returned.
@@ -58,7 +67,12 @@ endDate := time.Date(2021, 2, 24, 0, 0, 0, 0, time.UTC)
 queryInterval := query.NewTimeInterval(startDate, endDate)
 
 datapoints, err := datasets.CollectAs[*v1.Sentinel1Sar](
-    client.Datapoints.Query(ctx, []uuid.UUID{collection.ID}, datasets.WithTemporalExtent(queryInterval)),
+    client.Datapoints.Query(
+      ctx,
+      dataset.ID,
+      datasets.WithCollectionIDs(collection.ID),
+      datasets.WithTemporalExtent(queryInterval),
+    ),
 )
 ```
 </RequestExample>

api-reference/go/datasets/Datapoints.QueryInto.mdx

@@ -7,20 +7,20 @@ icon: layer-group
 ```go
 func (datapointClient) QueryInto(
     ctx context.Context,
-    collectionIDs []uuid.UUID,
+    datasetID uuid.UUID,
     datapoints any,
     options ...datasets.QueryOption,
 ) error
 ```
 
-Query a range of data points in the specified collections in a specified interval.
+Query datapoints from one or more collections of the same dataset into a slice.
 
 QueryInto is a convenience function for [Query](/api-reference/go/datasets/Datapoints.Query), when no manual pagination or custom iteration is required.
 
 ## Parameters
 
-<ParamField path="collectionIDs" type="[]uuid.UUID">
-  The ids of the collections to query
+<ParamField path="datasetID" type="uuid.UUID">
+  The ID of the dataset to query.
 </ParamField>
 <ParamField path="datapoints" type="*[]proto.Message">
   The datapoints to query into
@@ -39,6 +39,15 @@ QueryInto is a convenience function for [Query](/api-reference/go/datasets/Datap
   Specify the geographical extent in which to query data.
   Optional, if not specified the query will return all results found globally.
 </ParamField>
+<ParamField path="WithSpatialExtentFilter(spatialExtent query.SpatialExtent)">
+  Specify a geographical extent with an explicit spatial filter mode and coordinate system.
+</ParamField>
+<ParamField path="WithCollections(collections ...*datasets.Collection)">
+  Restrict the query to specific dataset collections by collection object.
+</ParamField>
+<ParamField path="WithCollectionIDs(collectionIDs ...uuid.UUID)">
+  Restrict the query to specific dataset collections by collection ID.
+</ParamField>
 <ParamField path="WithSkipData()" default="false">
   Skip the data when querying datapoints.
   If set, only the required and auto-generated fields will be returned.
@@ -62,8 +71,9 @@ queryInterval := query.NewTimeInterval(startDate, endDate)
 
 var datapoints []*v1.Sentinel1Sar
 err := client.Datapoints.QueryInto(ctx,
-    []uuid.UUID{collection.ID},
+    dataset.ID,
     &datapoints,
+    datasets.WithCollectionIDs(collection.ID),
     datasets.WithTemporalExtent(queryInterval),
 )
 ```