Skip to main content

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 Array of String

List of tags that apply to the dataset.

Example:

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

version String (UUID)

UUID 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.

Create Tags​

Method and URL 
POST /v0/projects/{project_id}/catalog/{id}/collaboration/tag

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID of the dataset.

tags Body   Array of String

List of tags to apply to the dataset. Tags are case-insensitive. Each tag can be listed only once per dataset. Each tag can have a maximum of 128 characters. Tags cannot include the following special characters: /, :, [, or ].

Example:

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

Example​

Request 
curl -X POST "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$DATASET_ID/collaboration/tag" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
--data-raw '{
  "tags": ["NYC", "taxi", "2023"]
}'
Response 
{
  "tags": [
    "NYC",
    "taxi",
    "2023"
  ],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}

Response Status Codes​

200   OK

400   Bad Request; Tags already exist

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict

Retrieve Tags​

Method and URL 
GET /v0/projects/{project_id}/catalog/{id}/collaboration/tag

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID of the dataset.

Example​

Request 
curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$DATASET_ID/collaboration/tag" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'
Response 
{
  "tags": [
    "NYC",
    "taxi",
    "2023"
  ],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict

Modify Tags​

Method and URL 
POST /v0/projects/{project_id}/catalog/{id}/collaboration/tag

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID of the dataset whose tags you want to modify. The dataset must have existing tags for this operation.

tags Body   Array of 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 (list each tag only once per dataset). Each tag can have a maximum of 128 characters. Tags cannot include the following special characters: /, :, [, or ].

Example:

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

version Body   String (UUID)

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

Example​

Request 
curl -X POST "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$DATASET_ID/collaboration/tag" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
--data-raw '{
  "tags": ["NYC", "taxi", "2023", "archived"],
  "version": "923f759a7c-f20d-46e5-7d3a-8da86c23a3ce"
}'
Response 
{
  "tags": [
    "NYC",
    "taxi",
    "2023",
    "archived"
  ],
  "version": "3d24e9ab72-3da5-2fe1-8dd5-3ea68f52d6ea"
}

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict

Delete Tags​

Method and URL 
POST /v0/projects/{project_id}/catalog/{id}/collaboration/tag

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 console.

Parameters​

project_id Path   String (UUID)

id Path   String (UUID)

UUID of the dataset.

tags Body   Array of String

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

Example:

[]

version Body   String (UUID)

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

Example​

Request 
curl -X POST "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$DATASET_ID/collaboration/tag" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
--data-raw '{
  "tags": [],
  "version": "3d24e9ab72-3da5-2fe1-8dd5-3ea68f52d6ea"
}'
Response 
{
  "tags": [],
  "version": "e2c39997-362c-4b50-9fea-19205431119c"
}

Response Status Codes​

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict