Tag

Use the Catalog API to create, update, and retrieve tags (also called labels).

Tag Object

{
  "tags": [
    "NYC",
    "taxi",
    "2023"
  ],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}

Tag Attributes

tags

[String]

List of tags that apply to the dataset.

Example ["NYC", "taxi", "2023"]

---

version

String (UUID)

Unique identifier of the set of tags. Dremio changes the version whenever any of the tags change and uses the version value to ensure that updates apply to the most recent version of the set of tags.

Example 923f759a7c-f20d-46e5-7d3a-8da86c23a3ce

Creating Tags

Create one or more tags for the specified dataset.

Method and URL

POST /v0/projects/{project-id}/catalog/{id}/collaboration/tag

Parameters

project-id

path

String (UUID)

Unique identifier of the project that contains the dataset for which you want to add tags.

Example 1df71752-69b7-47d9-9e6c-990e6b194aa4

---

id

path

String (UUID)

Unique identifier of the dataset for which you want to add tags.

Example 1bcab7b3-ee82-44c1-abcc-e86d56078d4d

---

tags

body

[String]

List of tags to apply to the dataset. Tags are case-insensitive. Each tag can be listed only once for each dataset. Each tag can have a maximum of 128 characters.

Example ["NYC", "taxi", "2023"]

Example Request

curl -X POST 'https://api.dremio.cloud/v0/projects/1df71752-69b7-47d9-9e6c-990e6b194aa4/catalog/1bcab7b3-ee82-44c1-abcc-e86d56078d4d/collaboration/tag' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "tags": ["NYC", "taxi", "2023"]
}'

Example Response

{
  "tags": [
    "NYC",
    "taxi",
    "2023"
  ],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}

Response Status Codes

200

OK

400

Bad Request

401

Unauthorized

404

Not Found

---

Retrieving Tags

Retrieve the tags applied to the specified dataset.

Method and URL

GET /v0/projects/{project-id}/catalog/{id}/collaboration/tag

Parameters

project-id

path

String (UUID)

Unique identifier of the project that contains the dataset whose tags you want to retrieve.

Example 1df71752-69b7-47d9-9e6c-990e6b194aa4

---

id

path

String (UUID)

Unique identifier of the dataset whose tags you want to retrieve.

Example 1bcab7b3-ee82-44c1-abcc-e86d56078d4d

Example Request

curl -X GET 'https://api.dremio.cloud/v0/projects/1df71752-69b7-47d9-9e6c-990e6b194aa4/catalog/1bcab7b3-ee82-44c1-abcc-e86d56078d4d/collaboration/tag' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Example Response

{
  "tags": [
    "NYC",
    "taxi",
    "2023"
  ],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}

Response Status Codes

200

OK

400

Bad Request

401

Unauthorized

404

Not Found

409

Conflict

---

Updating Tags

Update the tags for the specified dataset.

Method and URL

POST /v0/projects/{project-id}/catalog/{id}/collaboration/tag

Parameters

project-id

path

String (UUID)

Unique identifier of the project that contains the dataset whose tags you want to update.

Example 1df71752-69b7-47d9-9e6c-990e6b194aa4

---

id

path

String (UUID)

Unique identifier of the dataset whose tags you want to update.

Example 1bcab7b3-ee82-44c1-abcc-e86d56078d4d

---

tags

body

[String]

List of tags to apply to the dataset. If you want to keep any of the existing tags, include them in the tags array. Tags are case-insensitive and must be distinct (in other words, list each tag only once for each dataset). Each tag may have a maximum of 128 characters.

Example ["NYC", "taxi", "2023", "archived"]

---

version

body

String (UUID)

Unique identifier of the most recent set of tags. Dremio uses the version value to ensure that you are updating the most recent version of the tags.

Example 923f759a7c-f20d-46e5-7d3a-8da86c23a3ce

Example Request

curl -X POST 'https://api.dremio.cloud/v0/projects/1df71752-69b7-47d9-9e6c-990e6b194aa4/catalog/1bcab7b3-ee82-44c1-abcc-e86d56078d4d/collaboration/tag' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "tags": ["NYC", "taxi", "2023", "archived"],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}'

Example Response

{
  "tags": [
    "NYC",
    "taxi",
    "2023",
    "archived"
  ],
  "version": "3d24e9ab72-3da5-2fe1-8dd5-3ea68f52d6ea"
}

Response Status Codes

200

OK

400

Bad Request

401

Unauthorized

404

Not Found

409

Conflict

---

Deleting Tags

Delete the tags for the specified dataset.

note

Deleting tags means sending an empty array to replace the existing tags with no tags. The tag object will still exist, but it will contain an empty tags array and no tags will appear for the dataset in the Dremio UI.

Method and URL

POST /v0/projects/{project-id}/catalog/{id}/collaboration/tag

Parameters

project-id

path

String (UUID)

Unique identifier for the project that contains the dataset whose tags you want to remove.

Example 1df71752-69b7-47d9-9e6c-990e6b194aa4

---

id

path

String (UUID)

Unique identifier of the dataset whose tags you want to remove.

Example 1bcab7b3-ee82-44c1-abcc-e86d56078d4d

---

tags

body

[String]

Empty array to represent deletion of all tags for the dataset.

Example []

---

version

body

String (UUID)

Unique identifier of the most recent set of tags. Dremio uses the version value to ensure that you are deleting tags from the most recent version.

Example 3d24e9ab72-3da5-2fe1-8dd5-3ea68f52d6ea

Example Request

curl -X POST 'https://api.dremio.cloud/v0/projects/1df71752-69b7-47d9-9e6c-990e6b194aa4/catalog/1bcab7b3-ee82-44c1-abcc-e86d56078d4d/collaboration/tag' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "tags": [],
  "version": "3d24e9ab72-3da5-2fe1-8dd5-3ea68f52d6ea"
}'

Example Response

{
  "tags": [],
  "version": "e2c39997-362c-4b50-9fea-19205431119c"
}

Response Status Codes

200

OK

400

Bad Request

401

Unauthorized

404

Not Found

409

Conflict

---