Folder

Use the Catalog API to retrieve information about folders and the child objects they contain, as well as to create, update, and delete folders.

Folder Object

{
  "entityType": "folder",
  "id": "ffbe8c1d-1db7-48d1-9c58-f452838fedc0",
  "path": [
    "reporting",
    "test-folder"
  ],
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "children": [
    {
      "id": "1fdcf5c3-5c95-4e50-a7a3-d0aa58056c99",
      "path": [
        "reporting",
        "test-folder",
        "view-zip-codes"
      ],
      "tag": "a535d578-7921-4e56-b8c9-ada85d445fe6",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2021-12-01T17:33:07.786Z"
    },
    {
      "id": "f1ec2376-882e-406f-b37d-c97e8804b662",
      "path": [
        "reporting",
        "test-folder",
        "test-sub-folder"
      ],
      "tag": "eb3c936d-e476-4bfd-9738-1619e9da4c32",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "f460cfd7-8c8d-4295-ae3e-99dcc9162500",
      "path": [
        "reporting",
        "test-folder",
        "SF-weather"
      ],
      "tag": "75428c7f-7e69-473e-5312-7e5543eb9fda",
      "type": "DATASET",
      "datasetType": "PROMOTED",
      "createdAt": "1970-01-01T00:00:00.000Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "63022041-783d-557e-8ead-271f5ea25812",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "a430ed7f-7142-4e1f-ba7d-94173afdc9a3",
    "ownerType": "USER"
  }
}

Folder Attributes

entityType String

Specifies the type of container. For folders, the type is FOLDER.

id String

Unique identifier of the folder. For folders that are not in an Arctic source, the id may be a UUID like 1acab7b3-ee82-44c1-abcc-e86d56078d4d or a text path. For folders in an Arctic source, the id is a JSON string like {"tableKey":["myArcticSource","myFolder"],"contentId":"65b24a53-c56e-4037-8ffc-f25297614c3c","versionContext":{"type":"BRANCH","value":"main"}}.

path Array of String

The path for a folder.

Example: ["reporting", "test-folder"]

tag String

Identifies the instance of the folder. Dremio Cloud changes this tag whenever a change is made to the folder. Immutable by the user.

Example: 676e73e0-8b51-44d0-972d-ef80c29ac0c6

children Object

List of items inside a folder.

accessControlList Object

Information about users and roles with privileges on the folder and the specific privileges each user or role has. May include a users array, a roles array, or both, depending on the configured access and privileges. The accessControlList object is empty if folder-specific access control privileges are not set. For folders in Arctic sources and the primary Arctic catalog, the folder object does not include the accessControlList object.

owner Object

Information about the folder's owner. For folders whose id is a UUID and folders in Arctic sources and the primary Arctic catalog, the folder object does not include the owner object.

Attributes of the `children` Object

id String

Unique identifier of the object in the folder. For objects in folders in non-Arctic sources, the id is a UUID like 1acab7b3-ee82-44c1-abcc-e86d56078d4d. For objects in folders in Arctic sources and the primary Arctic catalog, the id is a JSON string like {"tableKey":["myArcticSource","myFolder"],"contentId":"65b24a53-c56e-4037-8ffc-f25297614c3c","versionContext":{"type":"BRANCH","value":"main"}}.

path Array of String

Identifies the path to the object.

tag String

Identifies the instance of the object. Dremio Cloud changes this tag whenever a change is made to the object. Immutable by the user.

Example: eb3a759b-e289-4bfd-9718-1619b9db4c02

type String

The type of the object. For folders, the type is CONTAINER. For datasets, the type is DATASET.

Enum: CONTAINER, DATASET

datasetType String

If the object type is a dataset, the dataset type is identified.

Enum: VIRTUAL, PROMOTED

containerType String

If the object type is a folder. the container type is FOLDER.

createdAt Array of String

The date and time that the object was created.

Attributes of the `accessControlList` Object

users Object

Information about the users that have been granted privileges on the folder and the privileges each user has.

roles Object

Information about the roles that have been granted privileges on the folder and the privileges each role has.

Attributes of the `owner` Object

ownerId String (UUID)

Unique identifier for the folder's owner.

Example: a430ed7f-7142-4e1f-ba7d-94173afdc9a3

ownerType String

Type of owner.

Enum: USER, ROLE

Example: USER

Attributes of the `roles` Object

id String

The ID of the role.

Example: 1e5f38e4-8209-46dc-96f0-cfbd3276dbd8

permissions Array of String

The privileges that the role has on the folder. Read Privileges for more information.

Attributes of the `users` Object

id String

The ID of the user.

permissions Array of String

The privileges that the user has on the folder.

Enum: SELECT, ALTER

Adding a Folder

Add a folder in an Arctic source.

note

Adding folders in non-Arctic sources is not supported.

Adding a Folder

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

Parameters

project-id Path String (UUID)

The UUID for the project that you want to add a folder for.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6

entityType Body String

The type of catalog object. For folders, the type is FOLDER.

path Body Array of String

Identifies the path where you want to add a folder. Includes the name of the new folder as the last item in the list.

Example: ["mySource", "newFolder"]

Example Request

curl -X POST 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/catalog' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json' \
-d '{
    "entityType": "folder",
    "path": ["mySource", "newFolder"]
    }'

note

When you add a folder in an Arctic source, the response object displays the folder id as a UUID. To get the JSON string id for the folder, retrieve the folder by path.

Example Response

{
  "entityType": "folder",
  "id": "cc9d3b9c-4917-a7b4-40f2-2dc2ba7a455c",
  "path": [
    "mySource",
    "newFolder"
  ],
  "tag": "9e3c3407-6ae2-824a-9384-eab4db6f6cda",
  "permissions": [],
  "owner": {
    "ownerId": "ee4aa4cf-84bb-895b-492b-82856d0f1fb0",
    "ownerType": "USER"
  }
}

Responses

200   OK

400   Bad Request

401   Unauthorized

Retrieving a Folder by ID

Get the folder metadata by providing the folder ID.

Retrieving a Folder by ID

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

Parameters

project-id Path String (UUID)

The UUID for the project that contains the folder.

id Path String

The identifier for the folder that you want to retrieve. For folders in non-Arctic sources, the id may be a UUID or a text path. If the id is a text path, use URL-encoded format to replace special characters with their UTF-8-equivalent characters: %3A for a colon; %2F for a forward slash, and %20 for a space. For example, if the id value is dremio:/Samples/samples.dremio.com/Dremio University, the encoded id is dremio%3A%2FSamples%2Fsamples.dremio.com%2FDremio%20University. For folders in Arctic sources and the primary Arctic catalog, the id is a JSON string like {"tableKey":["myArcticSource","myFolder"],"contentId":"65b24a53-c56e-4037-8ffc-f25297614c3c","versionContext":{"type":"BRANCH","value":"main"}}.

Example Request

curl -X GET 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/catalog/ffbe8c1d-1db7-48d1-9c58-f452838fedc0' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "entityType": "folder",
  "id": "ffbe8c1d-1db7-48d1-9c58-f452838fedc0",
  "path": ["reporting","test-folder"],
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "accessControlList": {},
  "permissions": [],
  "owner": {
    "ownerId": "a430ed7f-7142-4e1f-ba7d-94173afdc9a3",
    "ownerType": "USER"
  }
}

Responses

200   OK

400   Bad Request

401   Unauthorized

404   Not Found

Retrieving a Folder by Path

Get the folder metadata by providing the folder's path.

Retrieving a Folder by Path

GET /v0/projects/{project-id}/catalog/by-path/{path}

Parameters

project-id Path String (UUID)

The UUID for the project that contains the folder.

path Path String

Folder's location within Dremio, using forward slashes as separators. For example, for the "samples.dremio.com" folder within the source "Samples," the path is Samples/samples.dremio.com. If the name of any component in the path includes special characters for URLs, such as spaces, use URL encoding to replace the special characters with their UTF-8-equivalent characters. For example, "Dremio University" should be Dremio%20University in the URL path.

Example Request

curl -X GET 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/catalog/by-path/reporting/test-folder' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'

Example Response

{
  "entityType": "folder",
  "id": "ffbe8c1d-1db7-48d1-9c58-f452838fedc0",
  "path": ["reporting","test-folder"],
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "accessControlList": {},
  "permissions": [],
  "owner": {
    "ownerId": "a430ed7f-7142-4e1f-ba7d-94173afdc9a3",
    "ownerType": "USER"
  }
}

Responses

200   OK

400   Bad Request

401   Unauthorized

404   Not Found

Updating a Folder

Update a folder in a non-Arctic source.

note

Updating folders in Arctic sources and the primary Arctic catalog is not supported.

Updating a Folder

PUT  /v0/projects/{project-id}/catalog/{id}

Parameters

project-id Path String (UUID)

The UUID for the project that contains the folder you want to update.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6

id Path String

The identifier for the folder that you want to update. For folders in non-Arctic sources, the id may be a UUID or a text path. If the id is a text path, use URL-encoded format to replace special characters with their UTF-8-equivalent characters: %3A for a colon; %2F for a forward slash, and %20 for a space. For example, if the id value is dremio:/Samples/samples.dremio.com/Dremio University, the encoded id is dremio%3A%2FSamples%2Fsamples.dremio.com%2FDremio%20University.

Example: ffbe8c1d-1db7-48d1-9c58-f452838fedc0

entityType Body String

The type of catalog object. For folders, the type is FOLDER.

id Body String

Unique identifier of the folder.

Example: ffbe8c1d-1db7-48d1-9c58-f452838fedc0

path Body Array of String

Path of the location where the folder is saved within Dremio, expressed as an array. The path consists of the source, followed by any folder and subfolders, followed by the target folder itself as the last item in the array.

Example: ["reporting","new-folder"]

tag Body String (UUID) Optional

Unique identifier for the version of the folder you want to update. If you provide a tag in the request body, Dremio uses the tag value to ensure that you are requesting to update the most recent version of the folder. If you do not provide a tag, Dremio automatically updates the most recent version of the folder.

Example: b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801

accessControlList Body Object

Object used to specify which users and roles should have privileges on the folder and the specific privileges each user and role has. May include a users array, a roles array, or both. If you omit the accessControlList object in a PUT request, Dremio removes all existing user and role access settings from the folder. To keep existing user and role access settings while making other updates, duplicate the existing accessControlList array in the PUT request. Not supported for folders in Arctic sources and the primary Arctic catalog.

Parameters of the `accessControlList` Object

roles Body Array of Object

The roles that should have privileges on the folder and the privileges each role should have.

users Body Array of Object

The users that should have privileges on the folder and the privileges each role should have.

Parameters of the `roles` Object

id Body String

The ID of the role.

Example: 0f2d94e0-bb5e-4c03-8c6f-62d379d10889

permissions Body Array of String

The privileges that the role should have on the folder. Read Privileges for more information.

Parameters of the `users` Object

id Body String

The ID of the user.

Example: 737a038f-c6cd-4fd3-a77a-59f692727ba5

permissions Body Array of String

The privileges that the user should have on the folder. Read Privileges for more information.

Example Request

curl -X PUT 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/catalog/ffbe8c1d-1db7-48d1-9c58-f452838fedc0' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json' \
-d '{
  "entityType": "folder",
  "id": "ffbe8c1d-1db7-48d1-9c58-f452838fedc0",
  "path": [
    "reporting",
    "new-folder"
  ],
  "tag": "b79b70f4-d4a7-4fb5-bfbb-dc00b1b29801",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "ALL"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  }
}'

Example Response

{
  "entityType": "folder",
  "id": "ffbe8c1d-1db7-48d1-9c58-f452838fedc0",
  "path": [
    "reporting",
    "new-folder"
  ],
  "tag": "5a34c3d1-ac24-b27a-bb5e-af5dc1b230e1",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "ALL"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  },
  "permissions": [],
  "owner": {
    "ownerId": "a430ed7f-7142-4e1f-ba7d-94173afdc9a3",
    "ownerType": "USER"
  }
}

Responses

200   OK

400   Bad Request

401   Unauthorized

Deleting a Folder

Delete a folder.

Deleting a Folder

DELETE /v0/projects/{project-id}/catalog/{id}

Parameters

project-id Path String (UUID)

The UUID for the project that contains the folder.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6

id Path String

The identifier for the folder that you want to delete. For folders in non-Arctic sources, the id may be a UUID or a text path. If the id is a text path, use URL-encoded format to replace special characters with their UTF-8-equivalent characters: %3A for a colon; %2F for a forward slash, and %20 for a space. For example, if the id value is dremio:/Samples/samples.dremio.com/Dremio University, the encoded id is dremio%3A%2FSamples%2Fsamples.dremio.com%2FDremio%20University. For folders in Arctic sources and the primary Arctic catalog, the id is a JSON string like {"tableKey":["myArcticSource","myFolder"],"contentId":"65b24a53-c56e-4037-8ffc-f25297614c3c","versionContext":{"type":"BRANCH","value":"main"}}.

Example Request

curl -X DELETE 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/catalog/21a74cb1-3fcf-48c6-8f69-94c257ec3da3' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'

Example Response

No response

Responses

204   No Content

400   Bad Request

401   Unauthorized

404   Not Found

Folder

Folder Attributes​

Attributes of the children Object​

Attributes of the accessControlList Object​

Attributes of the owner Object​

Attributes of the roles Object​

Attributes of the users Object​

Adding a Folder​

Parameters​

Responses​

Retrieving a Folder by ID​

Parameters​

Responses​

Retrieving a Folder by Path​

Parameters​

Responses​

Updating a Folder​

Parameters​

Parameters of the accessControlList Object​

Parameters of the roles Object​

Parameters of the users Object​

Responses​

Deleting a Folder​

Parameters​

Responses​

Folder Attributes

Attributes of the `children` Object

Attributes of the `accessControlList` Object

Attributes of the `owner` Object

Attributes of the `roles` Object

Attributes of the `users` Object

Adding a Folder

Parameters

Responses

Retrieving a Folder by ID

Parameters

Responses

Retrieving a Folder by Path

Parameters

Responses

Updating a Folder

Parameters

Parameters of the `accessControlList` Object

Parameters of the `roles` Object

Parameters of the `users` Object

Responses

Deleting a Folder

Parameters

Responses