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

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

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

The path for a folder.

Example "reporting", "test-folder"

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

List of items inside a folder.

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.

Note: For folders in Arctic sources and the primary Arctic catalog, the folder object does not include the accessControlList 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.

children

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

Identifies the path to the object.

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

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

Enum CONTAINER, DATASET

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

Enum VIRTUAL, PROMOTED

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

The date and time that the object was created.

accessControlList

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

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

owner

Unique identifier for the folder's owner.

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

Type of owner.

Enum USER, ROLE

Example USER

roles

The ID of the role.

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

The privileges that the role has on the folder.

For more information, read Privileges.

users

The ID of the user.

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

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

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

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

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

The UUID for the project that contains the folder.

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

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

The UUID for the project that contains the folder.

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

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

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

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.

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

Unique identifier of the folder.

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.

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.

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.

accessControlList

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

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

roles

The ID of the role.

Example 9ab42853-bdef-465f-b9bb-381a13a9bf78

The privileges that the role should have on the folder.

For more information, read Privileges.

users

The ID of the user.

The privileges that the user should have on the folder.

For more information, read Privileges.

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

Deleting a Folder

Delete a folder.

Deleting a Folder

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

Parameters

The UUID for the project that contains the folder.

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

Folder

Folder Attributes​

children​

accessControlList​

owner​

roles​

users​

Adding a Folder​

Parameters​

Responses​

Retrieving a Folder by ID​

Parameters​

Responses​

Retrieving a Folder by Path​

Parameters​

Responses​

Updating a Folder​

Parameters​

accessControlList​

roles​

users​

Responses​

Deleting a Folder​

Parameters​

Responses​

Folder Attributes

children

accessControlList

owner

roles

users

Adding a Folder

Parameters

Responses

Retrieving a Folder by ID

Parameters

Responses

Retrieving a Folder by Path

Parameters

Responses

Updating a Folder

Parameters

accessControlList

roles

users

Responses

Deleting a Folder

Parameters

Responses