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": "2024-01-13T19:52:01.894Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "63022041-783d-557e-8ead-271f5ea25812",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ]
  },
  "permissions": [],
  "owner": {
    "ownerId": "a430ed7f-7142-4e1f-ba7d-94173afdc9a3",
    "ownerType": "USER"
  },
  "storageUri": "s3://my.dremio.storage/catalog/test_folder/"
}

Folder Attributes

entityType String

For folders, the entityType is folder.

id String (UUID)

UUID of the folder.

path Array of String

The path for a folder.

Example:

[
  "reporting",
  "test-folder"
]

tag String (UUID)

UUID of the version of the folder. Dremio changes this tag whenever a change is made to the folder.

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.

permissions Array of String

The permissions that the user submitting the API call has on a folder. This will be an empty array unless the query parameter include=permissions is set. See Privileges for more information.

owner Object

Information about the folder's owner.

Example:

{
  "ownerId": "a430ed7f-7142-4e1f-ba7d-94173afdc9a3",
  "ownerType": "USER"
}

storageUri String

This field indicates the location of the Open Catalog folder in object storage.

Example: s3://my.dremio.storage/catalog/test_folder/

Attributes of Objects in the `children` Array

id String (UUID)

UUID of the object in the folder.

path Array of String

Identifies the path to the object.

Example:

[
  "dremio-project",
  "Application",
  "test7"
]

tag String (UUID)

UUID of the version of the object. Dremio changes this tag whenever a change is made to the object.

type String

The type of the object.

CONTAINER: A nested folder or user-defined function, differentiated by containerType.
DATASET: A table or view object, differentiated by datasetType.
FILE: A data file such as CSV or JSON that has not been promoted to a table.

datasetType String

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

VIRTUAL: A view
DIRECT: An Iceberg table in a direct catalog
PROMOTED: A promoted table

containerType String

For folders, the container type is FOLDER.

createdAt String

Timestamp when 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)

UUID of the owner.

ownerType String

Type of owner. Must be USER or ROLE.

Attributes of Objects in the `roles` Array

id String (UUID)

UUID of the role.

permissions Array of String

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

Attributes of Objects in the `users` Array

id String (UUID)

UUID of the user.

permissions Array of String

The privileges that the user has on the folder.

Example:

[
  "SELECT",
  "ALTER"
]

Add a Folder

Method and URL

POST /v0/projects/{project_id}/catalog

Parameters

project_id Path String (UUID)

entityType Body String

The type of catalog object. For folders, the entityType 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/$PROJECT_ID/catalog" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
      "entityType": "folder",
      "path": ["mySource", "newFolder"]
    }'

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"
  },
  "storageUri": "s3://my.dremio.storage/catalog/test_folder/"
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

Retrieve a Folder by ID

Method and URL

GET /v0/projects/{project_id}/catalog/{id}

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the folder.

maxChildren Query Integer Optional

Specify the maximum number of child objects to include in each page of results. Use in concert with the pageToken parameter to split large sets of results into multiple pages. For more information, see the 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 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. See pageToken query parameter for more information.

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

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

include Query String Optional

When using include, the name of a non-default response field is returned. You can retrieve a list of permissions. See the include query parameter for usage examples.

Example: ?include=permissions

exclude Query String Optional

When using exclude, the children field is excluded from the response. See the exclude query parameter for usage examples.

Example: ?exclude=children

Example

Request

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$FOLDER_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

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"
  },
  "storageUri": "s3://my.dremio.storage/catalog/test_folder/"
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

Retrieve a Folder by Path

Method and URL

GET /v0/projects/{project_id}/catalog/by-path/{path}

Parameters

project_id Path String (UUID)

path Path String

Folder's location within Dremio, using forward slashes as separators. 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

include Query String Optional

When using include, the name of a non-default response field is returned. You can retrieve a list of permissions. See the include query parameter for usage examples.

Example: ?include=permissions

exclude Query String Optional

When using exclude, the children field is excluded from the response. See the exclude query parameter for usage examples.

Example: ?exclude=children

Example

Request

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/by-path/reporting/test-folder" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

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"
  },
  "storageUri": "s3://my.dremio.storage/catalog/test_folder/"
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

Update a Folder

Method and URL

PUT /v0/projects/{project_id}/catalog/{id}

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the folder.

entityType Body String

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

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 folders and subfolders, followed by the target folder itself as the last item in the array.

Example:

[
  "reporting",
  "new-folder"
]

tag Body String (UUID) Optional

UUID of the version of the folder. 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.

accessControlList Body Object Optional

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.

Parameters of the `accessControlList` Object

roles Body Array of Object Optional

The roles with privileges on the folder, and their privileges.

users Body Array of Object Optional

The users with privileges on the folder, and their privileges.

Parameters of Objects in the `roles` Array

id Body String (UUID)

UUID of the role.

permissions Body Array of String

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

Parameters of Objects in the `users` Array

id Body String (UUID)

UUID of the user.

permissions Body Array of String

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

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$FOLDER_ID" \
-H "Authorization: Bearer $DREMIO_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"
        ]
      }
    ]
  }
}'

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

Delete a Folder

Method and URL

DELETE /v0/projects/{project_id}/catalog/{id}

Parameters

project_id Path String (UUID)

id Path String (UUID)

UUID of the folder.

Example

Request

curl -X DELETE "https://api.dremio.cloud/v0/projects/$PROJECT_ID/catalog/$FOLDER_ID" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

A successful request returns an empty response body with HTTP status 204 No Content.

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​

Add a Folder​

Parameters​

Example​

Response Status Codes​

Retrieve a Folder by ID​

Parameters​

Example​

Response Status Codes​

Retrieve a Folder by Path​

Parameters​

Example​

Response Status Codes​

Update a Folder​

Parameters​

Parameters of the accessControlList Object​

Parameters of Objects in the roles Array​

Parameters of Objects in the users Array​

Example​

Response Status Codes​

Delete a Folder​

Parameters​

Example​

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

Add a Folder

Parameters

Example

Response Status Codes

Retrieve a Folder by ID

Parameters

Example

Response Status Codes

Retrieve a Folder by Path

Parameters

Example

Response Status Codes

Update a Folder

Parameters

Parameters of the `accessControlList` Object

Parameters of Objects in the `roles` Array

Parameters of Objects in the `users` Array

Example

Response Status Codes

Delete a Folder

Parameters

Example

Response Status Codes