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 Array of 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 Objects in the `children` Array

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

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

roles Array of 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 Objects in the `roles` Array

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 Objects in the `users` Array

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.

Method and URL

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. The name of the new folder cannot include the following special characters: /, :, [, or ].

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"
  }
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

Retrieving a Folder by ID

Get the folder metadata by providing the folder ID.

Method and URL

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"}}.

maxChildren Query Integer Optional

Specify the maximum number of child objects to include in each page of results. Use in concert with the pageToken query parameter to split large sets of results into multiple pages. For more information, read maxChildren Query Parameter.

NOTE: The maxChildren query parameter is not supported for folders in filesystem sources.

Example: ?maxChildren=25

pageToken Query String Optional

Specify the token for retrieving the next page of results. Must be used in concert with the maxChildren query parameter: the first request URL includes maxChildren set to the maximum number of child objects to include in each page of results. If the folder has more child objects than the specified maxChildren value, the response includes a nextPageToken attribute. Add the pageToken query parameter with the nextPageToken value to the request URL to retrieve the next page of results. Do not remove or change the maxChildren query parameter when you add pageToken to the request URL. Read pageToken Query Parameter: User-Specified Maximum for more information.

NOTE: Dremio ignores the pageToken query parameter for folders in filesystem sources.

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

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"
  }
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Retrieving a Folder by Path

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

Method and URL

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.

maxChildren Query Integer Optional

NOTE: The maxChildren query parameter is not supported for folders in filesystem sources.

Example: ?maxChildren=25

pageToken Query String Optional

NOTE: Dremio ignores the pageToken query parameter for folders in filesystem sources.

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

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"
  }
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

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.

Method and URL

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 Objects in the `roles` Array

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 Objects in the `users` Array

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"
  }
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

403 Forbidden

Deleting a Folder

Delete a folder.

Method and URL

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

Response Status Codes

204 No Content

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

Folder Attributes​

Attributes of Objects in the children Array​

Attributes of the accessControlList Object​

Attributes of the owner Object​

Attributes of Objects in the roles Array​

Attributes of Objects in the users Array​

Adding a Folder​

Parameters​

Response Status Codes​

Retrieving a Folder by ID​

Parameters​

Response Status Codes​

Retrieving a Folder by Path​

Parameters​

Response Status Codes​

Updating a Folder​

Parameters​

Parameters of the accessControlList Object​

Parameters of Objects in the roles Array​

Parameters of Objects in the users Array​

Response Status Codes​

Deleting a Folder​

Parameters​

Response Status Codes​

Folder Attributes

Attributes of Objects in the `children` Array

Attributes of the `accessControlList` Object

Attributes of the `owner` Object

Attributes of Objects in the `roles` Array

Attributes of Objects in the `users` Array

Adding a Folder

Parameters

Response Status Codes

Retrieving a Folder by ID

Parameters

Response Status Codes

Retrieving a Folder by Path

Parameters

Response Status Codes

Updating a Folder

Parameters

Parameters of the `accessControlList` Object

Parameters of Objects in the `roles` Array

Parameters of Objects in the `users` Array

Response Status Codes

Deleting a Folder

Parameters

Response Status Codes