# DataSet Operation

## ListAuthStorageConfig <a href="#listauthstorageconfig" id="listauthstorageconfig"></a>

**ListAuthStorageConfig**

Acquire the list of authentication configuration

**Request path**

> **GET** /v1/auth-storage-configs

**Request parameter**

**Query**

| Name   | Type   | Required | Descriptions                                                                                    |
| ------ | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| name   | string | No       | Configuration Name                                                                              |
| limit  | int    | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition |
| offset | int    | No       | The default is 0                                                                                |

**Request instance**

```
curl --location --request GET '{service}/v1/auth-storage-configs?name=aws_1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "configs": [
        {
            "name": "aws_1",
            "type": "s3",
            "endpoint": "s3.cn-northwest-1.amazonaws.com.cn",
            "accesskeyId": "AKIKU7KYZCWGOTEV5GNE",
            "bucketName": "graviti-210415"
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

## CreateDataset <a href="#createdataset" id="createdataset"></a>

**Create a dataset**

Create a TensorBay dataset with version control. The dataset name must be unique

**Request path**

> **POST** /v1/datasets

**Request parameter**

**Body**

| Name          | Type   | Required | Descriptions                                                                        |
| ------------- | ------ | -------- | ----------------------------------------------------------------------------------- |
| name          | string | Yes      | Dataset name                                                                        |
| type          | int    | No       | The default is 0, 0-normal dataset; 1-Fusion dataset                                |
| storageConfig | object | No       | Create parameters for using authenticated datasets; mutually exclusive with regions |
| ├─name        | string | Yes      | Configuration name                                                                  |
| ├─name        | path   | No       | Create storage path for datasets                                                    |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
   "name": "my first dataset",
   "type": 0,
   "storageConfig": {
        "name": "aws_1",
        "path": "graviti"
    }
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{
    "id": "154e35bae8954f09969ef8c9445efd2c"
}
```

* **id**: the ID of the created dataset

## DeleteDataset <a href="#deletedataset" id="deletedataset"></a>

**Delete a dataset**

> **DELETE** /v1/datasets/{id}

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name   | Type   | Required | Descriptions            |
| ------ | ------ | -------- | ----------------------- |
| commit | string | No       | Commit ID or commit tag |

**Request instance**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## UpdateDataset <a href="#updatedataset" id="updatedataset"></a>

**Update dataset information**

> **PATCH** /v1/datasets/{id}

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name | Type   | Required | Descriptions                                                       |
| ---- | ------ | -------- | ------------------------------------------------------------------ |
| name | string | No       | dataset name, and the provided value cannot be the empty value "". |

**Request instance**

```
curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c' \
--header 'x-token: {your_accesskey}'\
--data-raw '{
    "name": "my dataset",
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## ListDataset <a href="#listdataset" id="listdataset"></a>

**List datasets**

Return the list of datasets owned by the user:

* Individual users acquire the list of datasets under their personal accounts
* Team users acquire the list of datasets under their enterprise accounts

**Request path**

> **GET** /v1/datasets

**Request parameter**

**Query**

| Name           | Type   | Required | Descriptions                                                                                                           |
| -------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------- |
| limit          | int    | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition                        |
| offset         | int    | No       | The default is 0                                                                                                       |
| name           | string | No       | Dataset name                                                                                                           |
| needFuzzyQuery | bool   | No       | If true, fuzzy query of the dataset name is supported.                                                                 |
| sortBy         | string | No       | Currently sorting is based on created\_at and updated\_at while entering other content will return InvalidParamsValue. |
| orderBy        | string | No       | The default is desc (descending order). The valid content is asc (ascending order) and desc                            |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets?offset=0&limit=10'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "datasets": [
      {
        "id": "154e35bae8954f09969ef8c9445efd2c",
        "name": "my-great-data-set",
        "defaultBranch": "main",
        "type": 0,
        "updateTime": 1604977282,
        "owner": ""
      }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

* **datasets**: List of datasets
  * **id**: Dataset ID
  * **name**: Dataset name
  * **defaultBranch**: default branch name
  * **type**: the default is 0, 0-normal dataset, 1-Fusion dataset

## GetDataset <a href="#getdataset" id="getdataset"></a>

**Request path**

> **GET** /v1/datasets/{id}

**Request parameter**

**PATH**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "name": "my-great-data-set",
    "type": 1,
    "defaultBranch": "main",
    "commitId": "00000000000000000000000000000000",
    "updateTime": 1604977282,
    "owner": ""
}
```

## CreateBranch <a href="#createbranch" id="createbranch"></a>

**Create a branch**

Create a branch

**Request path**

> **POST** /v1/datasets/{id}/branches

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type   | Required | Descriptions                                                                        |
| ------ | ------ | -------- | ----------------------------------------------------------------------------------- |
| name   | string | Yes      | The name of the created branch                                                      |
| commit | string | Yes      | The commit that branch is based on. It can be commit ID, commit tag, or branch name |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json'\
--data-raw '{
  "name": main2,
  "commit": "fde63f357daf46088639e9f57fd81cad"
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{}
```

## DeleteBranch <a href="#deletebranch" id="deletebranch"></a>

**Delete branch**

Delete branch

**Request path**

> **DELETE** /v1/datasets/{id}/branches

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name | Type   | Required | Descriptions |
| ---- | ------ | -------- | ------------ |
| name | string | Yes      | Branch name  |

**Request instance**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json'\
--data-raw '{
  "name": main2
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## ListBranch <a href="#listbranch" id="listbranch"></a>

**Acquire a branch list**

Acquire a list of dataset branches

**Request path**

> **GET** /v1/datasets/{id}/branches

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type | Required | Descriptions                                                                                    |
| ------ | ---- | -------- | ----------------------------------------------------------------------------------------------- |
| limit  | int  | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition |
| offset | int  | No       | The default is 0                                                                                |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/branches?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "branches": [
        {
            "name": "main",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "committer": {
                "name": "graviti",
                "date": 1616579313
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

## CreateDraft <a href="#createdraft" id="createdraft"></a>

**Create a dataset draft**

Create a TensorBay dataset draft. Only one draft can be created on a branch

**Request path**

> **POST** /v1/datasets/{id}/drafts

**Request parameter**

**Path**

| Name | Required | Descriptions |
| ---- | -------- | ------------ |
| id   | Yes      | Dataset ID   |

**Body**

| Name       | Type   | Required | Descriptions                                     |
| ---------- | ------ | -------- | ------------------------------------------------ |
| title      | string | No       | Draft name                                       |
| branchName | string | No       | Branch name. The default branch is named as main |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "my first draft",
  "branchName": "main"
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{
    "draftNumber": 1
}
```

* **draftNumber**: draft number

## ListDraft <a href="#listdraft" id="listdraft"></a>

**Acquire a list of dataset drafts**

Acquire a list of dataset drafts

**Request path**

> **GET** /v1/datasets/{id}/drafts

**Request parameter**

**Path**

| Name | Required | Descriptions |
| ---- | -------- | ------------ |
| id   | Yes      | Dataset ID   |

**Query**

| Name   | Type | Required | Descriptions                                                                                    |
| ------ | ---- | -------- | ----------------------------------------------------------------------------------------------- |
| limit  | int  | No       | Need to be greater than 0 and the default is 128 with a maximum of 128 for a single acquisition |
| offset | int  | No       | The default is 0                                                                                |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/drafts?limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
  "drafts": [
    {
      "draftNumber": "1",
      "branchName": "main",
      "title": "my first draft"
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}
```

## CommitDataset <a href="#commitdataset" id="commitdataset"></a>

**Commit a dataset**

Update a dataset with a pending status to a committed status. Once a dataset is published, it cannot be modified.

**Request path**

> **POST** /v1/datasets/{id}

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name        | Type   | Required | Descriptions                                                            |
| ----------- | ------ | -------- | ----------------------------------------------------------------------- |
| draftNumber | int    | Yes      | Draft number                                                            |
| title       | string | yes      | The number of characters of the submitted title should be less than 255 |
| tag         | string | No       | Dataset version tag. The number of characters should range from 2 to 80 |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c'\
--header 'x-token: {your_accesskey}'\
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": "1",
  "title": "checkout a new version dataset",
  "tag": "v1.0"
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
  "commitId": "fde63f357daf46088639e9f57fd81cad"
}
```

## ListCommit <a href="#listcommit" id="listcommit"></a>

**list commits**

Acquire a list of dataset commits

**Request path**

> **GET** /v1/datasets/{id}/commits

**Request parameter** **Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type   | Required | Descriptions                                                             |
| ------ | ------ | -------- | ------------------------------------------------------------------------ |
| commit | string | No       | Commit ID, commit tag, or branch name. The default is the default branch |
| limit  | int    | No       | The default is set to 128. The maximum value for a single time is 128    |
| offset | int    | No       | The default is 0                                                         |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/commits?commit=main&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
  "commits": [
    {
      "parentCommitId": "0d213a06a85d46fa8662946bdb1afe7e",
      "commitId": "fde63f357daf46088639e9f57fd81cad",
      "title": "checkout a new version dataset",
      "committer": {
        "date": 1617268600,
        "name": "graviti"
      }
    }
  ],
  "offset": 0,
  "recordSize": 1,
  "totalCount": 10
}
```

## CreateTag <a href="#createtag" id="createtag"></a>

**Create a tag**

Create a tag

**Request path**

> **POST** /v1/datasets/{id}/tags

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name   | Type   | Required | Descriptions                                                 |
| ------ | ------ | -------- | ------------------------------------------------------------ |
| commit | string | Yes      | Commit ID, commit tag, or branch name                        |
| name   | string | Yes      | Tag name. The number of characters should range from 2 to 80 |

**Request instance**

```
curl --location --request POST '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "commit": "fde63f357daf46088639e9f57fd81cad",
  "name": "v1"
}'
```

**Output**

```
# Response status
HttpStatus 201
# Response result
{}
```

## DeleteTag <a href="#deletetag" id="deletetag"></a>

**Delete a tag**

Delete a tag

**Request path**

> **DELETE** /v1/datasets/{id}/tags

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name | Type   | Required | Descriptions |
| ---- | ------ | -------- | ------------ |
| name | string | Yes      | tag name     |

**Request instance**

```
curl --location --request DELETE '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "v1"
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## ListTag <a href="#listtag" id="listtag"></a>

**List tags**

Acquire a list of dataset tags

**Request path**

> **GET** /v1/datasets/{id}/tags

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name   | Type   | Required | Descriptions                                                          |
| ------ | ------ | -------- | --------------------------------------------------------------------- |
| name   | string | 否        | tag name                                                              |
| limit  | int    | No       | The default is set to 128. The maximum value for a single time is 128 |
| offset | int    | No       | The default is 0                                                      |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/tags?name=v1&limit=1&offset=0' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "tags": [
        {
            "name": "v1",
            "commitId": "fde63f357daf46088639e9f57fd81cad",
            "parentCommitId": "f68b1375454f459b8a486b8d1f4d9ddb",
            "title": "first commit",
            "committer": {
                "name": "graviti",
                "date": 1617268600
            }
        }
    ],
    "offset": 0,
    "recordSize": 1,
    "totalCount": 1
}
```

## updateNote <a href="#updatenote" id="updatenote"></a>

**Update a dataset note**

Update a dataset note

**Request path**

> **PATCH** /v1/datasets/{id}/notes

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Body**

| Name                | Type      | Required | Descriptions                                    |
| ------------------- | --------- | -------- | ----------------------------------------------- |
| draftNumber         | int       | Yes      | draft number                                    |
| binPointCloudFields | string\[] | No       | Dimension name of the point cloud in bin format |
| isContinuous        | bool      | No       | Is it continuous                                |

**Request instance**

```
curl --location --request PATCH '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "draftNumber": 1,
  "fileFormat": {
    "draftNumber": 1,
    "binPointCloudFields": [
       "X",
       "Y",
       "Z",
       "Intensity"
    ],
    "isContinuous": true
}'
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{}
```

## GetNote <a href="#getnote" id="getnote"></a>

**Get note**

Get the note of a dataset

**Request path**

> **GET** /v1/datasets/{id}/notes

**Request parameter**

**Path**

| Name | Descriptions | Value      |
| ---- | ------------ | ---------- |
| id   | Yes          | Dataset ID |

**Query**

| Name        | Type   | Required | Descriptions                                                                                        |
| ----------- | ------ | -------- | --------------------------------------------------------------------------------------------------- |
| draftNumber | int    | No       | Draft number. Only one of draft and commit should exist, but they should not exist at the same time |
| commit      | string | No       | Commit ID, commit tag, or branch name                                                               |

**Request instance**

```
curl --location --request GET '{service}/v1/datasets/154e35bae8954f09969ef8c9445efd2c/notes?draftNumber=1' \
--header 'x-token: {your_accesskey}' \
--header 'Content-Type: application/json' 
```

**Output**

```
# Response status
HttpStatus 200
# Response result
{
    "isContinuous": true，
    "binPointCloudFields": [
        "X",
        "Y",
        "Z",
        "Intensity"
    ]
}
```