Skip to main content
Version: current

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": "d4c2a8ba-a972-4db4-8deb-67e1ade684d1",
  "path": [
    "Samples",
    "samples.dremio.com"
  ],
  "tag": "pRmJ0BQ9SFw=",
  "children": [
    {
      "id": "dremio:/Samples/samples.dremio.com/zip_lookup.csv",
      "path": [
        "Samples",
        "samples.dremio.com",
        "zip_lookup.csv"
      ],
      "type": "FILE"
    },
    {
      "id": "dremio:/Samples/samples.dremio.com/NYC-taxi-trips-iceberg",
      "path": [
        "Samples",
        "samples.dremio.com",
        "NYC-taxi-trips-iceberg"
      ],
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "1acab7b3-ee82-44c1-abcc-e86d56078d4d",
      "path": [
        "Samples",
        "samples.dremio.com",
        "NYC-taxi-trips"
      ],
      "type": "DATASET",
      "datasetType": "PROMOTED"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  },
  "permissions": [
    "READ",
    "WRITE",
    "ALTER_REFLECTION",
    "SELECT",
    "ALTER",
    "VIEW_REFLECTION",
    "MODIFY",
    "MANAGE_GRANTS",
    "CREATE_TABLE",
    "DROP",
    "EXTERNAL_QUERY",
    "INSERT",
    "TRUNCATE",
    "DELETE",
    "UPDATE",
    "EXECUTE",
    "CREATE_SOURCE",
    "ALL"
  ],
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Folder Attributes​

{{< api-section file="data/software-api/folder.json" data="folderAttributes" >}}

children​

{{< api-section file="data/software-api/folder.json" data="childrenAttributes" >}}

accessControlList​

{{< api-section file="data/software-api/folder.json" data="accessControlListAttributes" >}}

owner​

{{< api-section file="data/software-api/folder.json" data="ownerAttributes" >}}

users and roles​

{{< api-section file="data/software-api/folder.json" data="usersRolesAccessControlAttributes" >}}

Creating a Folder​

Create a new folder within a space.

note:

The Catalog API cannot create new folders within sources.

Method and URL
POST /api/v3/catalog

Parameters​

{{< api-section file="data/software-api/folder.json" data="createFolderParameters" >}}

accessControlList​

{{< api-section file="data/software-api/folder.json" data="createAccessControlListParameters" >}}

users and roles​

{{< api-section file="data/software-api/folder.json" data="createUsersRolesParameters" >}}


Example Request
curl -X POST 'https://{hostname}/api/v3/catalog' \
--header 'Authorization: _dremio{tokenstring}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entityType": "folder",
  "path": [
    "Example-Space",
    "First-Folder",
    "New-Folder"
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  }
}'
Example Response
{
  "entityType": "folder",
  "id": "598697c2-8be0-4050-9731-53563977a17d",
  "path": [
    "Example-Space",
    "First-Folder",
    "New-Folder"
  ],
  "tag": "R7COubQq8KE=",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  },
  "permissions": [],
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes​

{{< api-responses file="data/software-api/folder.json" data="createFolderResponseCodes" >}}

Retrieving a Folder by ID​

Retrieve a folder and information about its contents by specifying the folder's ID.

Method and URL
GET /api/v3/catalog/{id}

Parameters​

{{< api-section file="data/software-api/folder.json" data="retrieveFolderIdParameters" >}}


Example Request
curl -X GET 'https://{hostname}/api/v3/catalog/d4c2a8ba-a972-4db4-8deb-67e1ade684d1' \
--header 'Authorization: _dremio{tokenstring}' \
--header 'Content-Type: application/json'
Example Response
{
  "entityType": "folder",
  "id": "d4c2a8ba-a972-4db4-8deb-67e1ade684d1",
  "path": [
    "Samples",
    "samples.dremio.com"
  ],
  "tag": "pRmJ0BQ9SFw=",
  "children": [
    {
      "id": "dremio:/Samples/samples.dremio.com/zip_lookup.csv",
      "path": [
        "Samples",
        "samples.dremio.com",
        "zip_lookup.csv"
      ],
      "type": "FILE"
    },
    {
      "id": "dremio:/Samples/samples.dremio.com/NYC-taxi-trips-iceberg",
      "path": [
        "Samples",
        "samples.dremio.com",
        "NYC-taxi-trips-iceberg"
      ],
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "1acab7b3-ee82-44c1-abcc-e86d56078d4d",
      "path": [
        "Samples",
        "samples.dremio.com",
        "NYC-taxi-trips"
      ],
      "type": "DATASET",
      "datasetType": "PROMOTED"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes​

{{< api-responses file="data/software-api/folder.json" data="retrieveFolderIdResponseCodes" >}}

Retrieving a Folder by Path​

Retrieve a folder and information about its contents by specifying the folder's path.

Method and URL
GET /api/v3/catalog/by-path/{path}

Parameters​

{{< api-section file="data/software-api/folder.json" data="retrieveFolderPathParameters" >}}


Example Request
curl -X GET 'https://{hostname}/api/v3/catalog/by-path/Samples/samples.dremio.com' \
--header 'Authorization: _dremio{tokenstring}' \
--header 'Content-Type: application/json'
Example Response
{
  "entityType": "folder",
  "id": "d4c2a8ba-a972-4db4-8deb-67e1ade684d1",
  "path": [
    "Samples",
    "samples.dremio.com"
  ],
  "tag": "pRmJ0BQ9SFw=",
  "children": [
    {
      "id": "dremio:/Samples/samples.dremio.com/zip_lookup.csv",
      "path": [
        "Samples",
        "samples.dremio.com",
        "zip_lookup.csv"
      ],
      "type": "FILE"
    },
    {
      "id": "dremio:/Samples/samples.dremio.com/NYC-taxi-trips-iceberg",
      "path": [
        "Samples",
        "samples.dremio.com",
        "NYC-taxi-trips-iceberg"
      ],
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "1acab7b3-ee82-44c1-abcc-e86d56078d4d",
      "path": [
        "Samples",
        "samples.dremio.com",
        "NYC-taxi-trips"
      ],
      "type": "DATASET",
      "datasetType": "PROMOTED"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "SELECT",
          "ALTER"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes​

{{< api-responses file="data/software-api/folder.json" data="retrieveFolderPathResponseCodes" >}}

Updating a Folder​

Update the specified folder.

Method and URL
PUT /api/v3/catalog/{id}

Parameters​

{{< api-section file="data/software-api/folder.json" data="updateFolderParameters" >}}

accessControlList​

{{< api-section file="data/software-api/folder.json" data="updateAccessControlListParameters" >}}

users and roles​

{{< api-section file="data/software-api/folder.json" data="updateUsersRolesParameters" >}}


Example Request
curl -X PUT 'https://{hostname}/api/v3/catalog/5442c00a-ada1-48c6-82fc-bb804b2e04e0' \
--header 'Authorization: _dremio{tokenstring}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entityType": "folder",
  "id": "598697c2-8be0-4050-9731-53563977a17d",
  "path": [
    "Example-Space",
    "First-Folder",
    "New-Folder"
  ],
  "tag": "R7COubQq8KE=",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "ALL"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  }
}'
Example Response
{
  "entityType": "folder",
  "id": "598697c2-8be0-4050-9731-53563977a17d",
  "path": [
    "Example-Space",
    "First-Folder",
    "New-Folder"
  ],
  "tag": "vnRnYLLpCFU=",
  "children": [
    {
      "id": "d60f9258-e55a-4fc3-97b3-58c6720a70fc",
      "path": [
        "Example-Space",
        "First-Folder",
        "New-Folder",
        "NYC-trips-weather"
      ],
      "tag": "IHXU7Oxs80c=",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "acba8595-bfcf-4126-887c-d2a19b5afb1d",
      "path": [
        "Example-Space",
        "First-Folder",
        "New-Folder",
        "short-distance-trips"
      ],
      "tag": "KYs/Qyw1ok8=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-02-09T19:09:58.789Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "ALTER_REFLECTION",
          "ALTER",
          "MANAGE_GRANTS",
          "VIEW_REFLECTION",
          "SELECT"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "SELECT"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Deleting a Folder​

Delete the specified folder, including all of the folder's contents.

Method and URL
DELETE /api/v3/catalog/{id}

Parameters​

{{< api-section file="data/software-api/folder.json" data="deleteFolderParameters" >}}


Example Request
curl -X DELETE 'https://{hostname}/api/v3/catalog/598697c2-8be0-4050-9731-53563977a17d' \
--header 'Authorization: _dremio{tokenstring}' \
--header 'Content-Type: application/json'
Example Response
No response

Response Status Codes​

{{< api-responses file="data/software-api/folder.json" data="deleteFolderResponseCodes" >}}