# Datasets ## Create a dataset `client.Datasets.New(ctx, body) (*Dataset, error)` **post** `/v5/datasets` Create a dataset and populate it with its initial items in a single call. Use this when the dataset does not exist yet: it creates the dataset and seeds it with the items you provide. To add more items to a dataset that already exists, use POST /v5/dataset-items/batch instead. A name is required, and the request must include at least one item in `data`; the optional `files` field associates files with the created items. The provided items are inserted as dataset items as a side effect of creation, and any `tags` are attached to the dataset. The returned dataset is at version 1. ### Parameters - `body DatasetNewParams` - `Data param.Field[[]map[string, any]]` Items to be included in the dataset - `Name param.Field[string]` - `Description param.Field[string]` - `Files param.Field[[]map[string, string]]` Files to be associated to the dataset - `Tags param.Field[[]string]` The tags associated with the entity ### Returns - `type Dataset struct{…}` - `ID string` The unique identifier of the entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `CurrentVersionNum int64` - `Name string` - `Tags []string` The tags associated with the entity - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `Description string` - `Object DatasetObject` - `const DatasetObjectDataset DatasetObject = "dataset"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) dataset, err := client.Datasets.New(context.TODO(), sgpdev.DatasetNewParams{ Data: []map[string]any{map[string]any{ "foo": "bar", }}, Name: "name", }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", dataset.ID) } ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "current_version_num": 0, "name": "name", "tags": [ "string" ], "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "object": "dataset" } ``` ## List datasets `client.Datasets.List(ctx, query) (*CursorPage[Dataset], error)` **get** `/v5/datasets` Return a paginated list of the account's datasets. Archived datasets are excluded unless `include_archived` is set to true. Results can be narrowed by `tags` and by the standard filterable parameters; a `name` filter matches as a case-insensitive substring rather than an exact match. ### Parameters - `query DatasetListParams` - `EndingBefore param.Field[string]` - `IncludeArchived param.Field[bool]` - `Limit param.Field[int64]` - `Name param.Field[string]` - `SortBy param.Field[string]` - `SortOrder param.Field[SortOrder]` - `StartingAfter param.Field[string]` - `Tags param.Field[[]string]` ### Returns - `type Dataset struct{…}` - `ID string` The unique identifier of the entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `CurrentVersionNum int64` - `Name string` - `Tags []string` The tags associated with the entity - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `Description string` - `Object DatasetObject` - `const DatasetObjectDataset DatasetObject = "dataset"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) page, err := client.Datasets.List(context.TODO(), sgpdev.DatasetListParams{ }) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", page) } ``` #### Response ```json { "has_more": true, "items": [ { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "current_version_num": 0, "name": "name", "tags": [ "string" ], "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "object": "dataset" } ], "total": 0, "limit": 0, "object": "list" } ``` ## Archive a dataset `client.Datasets.Archive(ctx, datasetID) (*DatasetArchiveResponse, error)` **delete** `/v5/datasets/{dataset_id}` Soft-delete a dataset by archiving it; the row is retained and can be restored later. This sets the dataset's `archived_at` timestamp rather than permanently removing it, and cascades the same archival to the dataset's items and versions. Archiving is not idempotent: if the dataset is already archived the call fails. The dataset can be brought back with the PATCH restore request. The response reports the dataset id with `deleted` set to true. ### Parameters - `datasetID string` ### Returns - `type DatasetArchiveResponse struct{…}` - `ID string` - `Deleted bool` - `Object DatasetArchiveResponseObject` - `const DatasetArchiveResponseObjectDataset DatasetArchiveResponseObject = "dataset"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) response, err := client.Datasets.Archive(context.TODO(), "dataset_id") if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", response.ID) } ``` #### Response ```json { "id": "id", "deleted": true, "object": "dataset" } ``` ## Update or restore a dataset `client.Datasets.Update(ctx, datasetID, body) (*Dataset, error)` **patch** `/v5/datasets/{dataset_id}` Update a dataset's fields, or restore a previously archived dataset. The request body is a union discriminated by its contents: a body of `{"restore": true}` triggers a restore, and any other body is treated as a partial update of the dataset's `name`, `description`, and `tags`. Restore clears `archived_at` on the dataset and cascades the un-archival to its items and versions; restoring a dataset that is not archived returns it unchanged. A partial update on an archived dataset fails, since archived datasets cannot be modified. ### Parameters - `datasetID string` - `body DatasetUpdateParams` - `Dataset param.Field[DatasetUpdateParamsDatasetUnion]` - `type DatasetUpdateParamsDatasetPartialDatasetRequestBase struct{…}` - `Description string` - `Name string` - `Tags []string` The tags associated with the entity - `type RestoreRequestParam struct{…}` - `Restore bool` Set to true to restore the entity from the database. - `const RestoreRequestRestoreTrue RestoreRequestRestore = true` ### Returns - `type Dataset struct{…}` - `ID string` The unique identifier of the entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `CurrentVersionNum int64` - `Name string` - `Tags []string` The tags associated with the entity - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `Description string` - `Object DatasetObject` - `const DatasetObjectDataset DatasetObject = "dataset"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) dataset, err := client.Datasets.Update( context.TODO(), "dataset_id", sgpdev.DatasetUpdateParams{ OfPartialDatasetRequestBase: &sgpdev.DatasetUpdateParamsDatasetPartialDatasetRequestBase{ }, }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", dataset.ID) } ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "current_version_num": 0, "name": "name", "tags": [ "string" ], "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "object": "dataset" } ``` ## Get a dataset `client.Datasets.Get(ctx, datasetID, query) (*Dataset, error)` **get** `/v5/datasets/{dataset_id}` Retrieve a single dataset by its id. By default an archived dataset is not returned; set `include_archived` to true to fetch a dataset regardless of whether it has been archived. ### Parameters - `datasetID string` - `query DatasetGetParams` - `IncludeArchived param.Field[bool]` ### Returns - `type Dataset struct{…}` - `ID string` The unique identifier of the entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `CurrentVersionNum int64` - `Name string` - `Tags []string` The tags associated with the entity - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `Description string` - `Object DatasetObject` - `const DatasetObjectDataset DatasetObject = "dataset"` ### Example ```go package main import ( "context" "fmt" "github.com/scaleapi/sgp-dev-go" "github.com/scaleapi/sgp-dev-go/option" ) func main() { client := sgpdev.NewClient( option.WithAPIKey("My API Key"), option.WithAccountID("My Account ID"), ) dataset, err := client.Datasets.Get( context.TODO(), "dataset_id", sgpdev.DatasetGetParams{ }, ) if err != nil { panic(err.Error()) } fmt.Printf("%+v\n", dataset.ID) } ``` #### Response ```json { "id": "id", "created_at": "2019-12-27T18:11:19.117Z", "created_by": { "id": "id", "type": "user", "object": "identity" }, "current_version_num": 0, "name": "name", "tags": [ "string" ], "archived_at": "2019-12-27T18:11:19.117Z", "description": "description", "object": "dataset" } ``` ## Domain Types ### Dataset - `type Dataset struct{…}` - `ID string` The unique identifier of the entity. - `CreatedAt Time` The date and time when the entity was created in ISO format. - `CreatedBy Identity` The identity that created the entity. - `ID string` - `Type IdentityType` - `const IdentityTypeUser IdentityType = "user"` - `const IdentityTypeServiceAccount IdentityType = "service_account"` - `Object IdentityObject` - `const IdentityObjectIdentity IdentityObject = "identity"` - `CurrentVersionNum int64` - `Name string` - `Tags []string` The tags associated with the entity - `ArchivedAt Time` The date and time when the entity was archived in ISO format. - `Description string` - `Object DatasetObject` - `const DatasetObjectDataset DatasetObject = "dataset"`