# Datasets ## Create a dataset `client.datasets.create(DatasetCreateParamsbody, RequestOptionsoptions?): Dataset` **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: DatasetCreateParams` - `data: Array>` Items to be included in the dataset - `name: string` - `description?: string` - `files?: Array>` Files to be associated to the dataset - `tags?: Array` The tags associated with the entity ### Returns - `Dataset` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `current_version_num: number` - `name: string` - `tags: Array | null` The tags associated with the entity - `archived_at?: string` The date and time when the entity was archived in ISO format. - `description?: string` - `object?: "dataset"` - `"dataset"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const dataset = await client.datasets.create({ data: [{ foo: 'bar' }], name: 'name' }); console.log(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(DatasetListParamsquery?, RequestOptionsoptions?): CursorPage` **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` - `ending_before?: string` - `include_archived?: boolean` - `limit?: number` - `name?: string` - `sort_by?: string` - `sort_order?: SortOrder` - `"asc"` - `"desc"` - `starting_after?: string` - `tags?: Array` ### Returns - `Dataset` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `current_version_num: number` - `name: string` - `tags: Array | null` The tags associated with the entity - `archived_at?: string` The date and time when the entity was archived in ISO format. - `description?: string` - `object?: "dataset"` - `"dataset"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); // Automatically fetches more pages as needed. for await (const dataset of client.datasets.list()) { console.log(dataset.id); } ``` #### 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(stringdatasetID, RequestOptionsoptions?): DatasetArchiveResponse` **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 - `DatasetArchiveResponse` - `id: string` - `deleted: boolean` - `object?: "dataset"` - `"dataset"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const response = await client.datasets.archive('dataset_id'); console.log(response.id); ``` #### Response ```json { "id": "id", "deleted": true, "object": "dataset" } ``` ## Update or restore a dataset `client.datasets.update(stringdatasetID, DatasetUpdateParamsparams, RequestOptionsoptions?): Dataset` **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` - `params: DatasetUpdateParams` - `dataset: PartialDatasetRequestBase | RestoreRequest` - `PartialDatasetRequestBase` - `description?: string` - `name?: string` - `tags?: Array` The tags associated with the entity - `RestoreRequest` - `restore: true` Set to true to restore the entity from the database. - `true` ### Returns - `Dataset` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `current_version_num: number` - `name: string` - `tags: Array | null` The tags associated with the entity - `archived_at?: string` The date and time when the entity was archived in ISO format. - `description?: string` - `object?: "dataset"` - `"dataset"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const dataset = await client.datasets.update('dataset_id', { dataset: {} }); console.log(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.retrieve(stringdatasetID, DatasetRetrieveParamsquery?, RequestOptionsoptions?): Dataset` **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: DatasetRetrieveParams` - `include_archived?: boolean` ### Returns - `Dataset` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `current_version_num: number` - `name: string` - `tags: Array | null` The tags associated with the entity - `archived_at?: string` The date and time when the entity was archived in ISO format. - `description?: string` - `object?: "dataset"` - `"dataset"` ### Example ```typescript import SGPClient from 'scale-gp'; const client = new SGPClient({ accountID: 'My Account ID', apiKey: process.env['SGP_API_KEY'], // This is the default and can be omitted }); const dataset = await client.datasets.retrieve('dataset_id'); console.log(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 - `Dataset` - `id: string` The unique identifier of the entity. - `created_at: string` The date and time when the entity was created in ISO format. - `created_by: Identity` The identity that created the entity. - `id: string` - `type: "user" | "service_account"` - `"user"` - `"service_account"` - `object?: "identity"` - `"identity"` - `current_version_num: number` - `name: string` - `tags: Array | null` The tags associated with the entity - `archived_at?: string` The date and time when the entity was archived in ISO format. - `description?: string` - `object?: "dataset"` - `"dataset"` ### Dataset Archive Response - `DatasetArchiveResponse` - `id: string` - `deleted: boolean` - `object?: "dataset"` - `"dataset"`