Space

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

Space Object

{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "Example-Space",
  "tag": "zzOQfjY9lU0=",
  "createdAt": "2023-01-12T18:44:43.237Z",
  "children": [
    {
      "id": "8da037a1-8e50-422b-9a2b-cafb03f57c71",
      "path": [
        "Example-Space",
        "testfolder"
      ],
      "tag": "0McuCL4MzBU=",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "f32dfe85-32e2-4c31-b2b4-bfd62ab3f473",
      "path": [
        "Example-Space",
        "travel_testing"
      ],
      "tag": "i4mnlSmHqVM=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-01-30T17:54:25.547Z"
    },
    {
      "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
      "path": [
        "Example-Space",
        "zips"
      ],
      "tag": "ITlp8+qyIMQ=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-02-08T16:24:25.084Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "MODIFY"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  },
  "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"
  }
}

Space Attributes

entityType String

Type of the catalog object. For spaces, the entityType is space.

Example: space

---

id String (UUID)

Unique identifier of the space.

Example: 5442c00a-ada1-48c6-82fc-bb804b2e04e0

---

name String

Name of the space.

Example: Example-Space

---

tag String

Unique identifier of the version of the space. Dremio changes the tag whenever the space changes and uses the tag to ensure that PUT requests apply to the most recent version of the space.

Example: zzOQfjY9lU0=

---

createdAt String

Date and time that the space was created, in UTC format.

Example: 2023-01-12T18:44:43.237Z

---

children Array of Object

Information about each catalog object in the space.

Example: [{"id": "8da037a1-8e50-422b-9a2b-cafb03f57c71","path": ["Example-Space","testfolder"],"tag": "0McuCL4MzBU=","type": "CONTAINER","containerType": "FOLDER"},{"id": "f32dfe85-32e2-4c31-b2b4-bfd62ab3f473","path": ["Example-Space","travel_testing"],"tag": "i4mnlSmHqVM=","type": "DATASET","datasetType": "VIRTUAL","createdAt": "2023-01-30T17:54:25.547Z"},{"id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda","path": ["Example-Space","zips"],"tag": "ITlp8+qyIMQ=","type": "DATASET","datasetType": "VIRTUAL","createdAt": "2023-02-08T16:24:25.084Z"}]

---

accessControlList Object

Enterprise only. Information about users and roles with access to the space and the specific privileges each user or role has. May include an array of users, an array of roles, or both, depending on the configured access and privileges. The accessControlList array is empty if space-specific access control privileges are not set.

Example: {"users": [{"id": "737a038f-c6cd-4fd3-a77a-59f692727ba5","permissions": ["MODIFY"]}],"roles": [{"id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889","permissions": ["MODIFY"]}]}

---

permissions Array of String

Enterprise-only. List of the privileges that you have on the space. Only appears in the response if the request URL includes the permissions query parameter. For more information, read Privileges.

Example: ["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 Object

Information about the space's owner.

Example: {"ownerId": "d01585a2-b267-4d56-9154-31762ab65a43","ownerType": "USER"}

Attributes of the children Object

id String (UUID)

Unique identifier of the catalog object.

Example: 8da037a1-8e50-422b-9a2b-cafb03f57c71

---

path Array of String

Path of the catalog object within Dremio, expressed as an array. The path consists of the space, followed by any folder and subfolders, followed by the catalog object itself as the last item in the array.

Example: ["Example-Space","testfolder"]

---

tag String

Unique identifier of the version of the catalog object. Dremio changes the tag whenever the catalog object changes and uses the tag to ensure that PUT requests apply to the most recent version of the object.

Example: 0McuCL4MzBU=

---

type String

Type of the catalog object.

Enum: CONTAINER, DATASET, FILE

Example: CONTAINER

---

containerType String

For catalog objects in a space with the type CONTAINER, the containerType is FOLDER.

Example: FOLDER

---

datasetType String

For catalog objects in a space with the type DATASET, the datasetType is VIRTUAL (spaces cannot contain tables, only views).

Example: VIRTUAL

---

createdAt String

For catalog objects in a space with the type DATASET, date and time that the catalog object was created, in UTC format.

Example: 2023-01-30T17:54:25.547Z

Attributes of the accessControlList Object

users Array of Object

Enterprise only. List of users with access to the space and the specific privileges each user has.

Example: [{"id": "737a038f-c6cd-4fd3-a77a-59f692727ba5", "permissions": ["MODIFY"]}]

---

roles Array of Object

Enterprise only. List of roles whose members have access to the space and the specific privileges each role has.

Example: [{"id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889", "permissions": ["MODIFY"]}]

Attributes of the owner Object

id String

Enterprise only. Unique identifier of the user or role with access to the space.

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

---

permissions Array of String

Enterprise only. List of privileges the user or role has on the space. For more information, read Privileges.

Enum: ALL, VIEW_REFLECTION, TRUNCATE, UPDATE, DELETE, DROP, MANAGE_GRANTS, EXTERNAL_QUERY, EXECUTE, ALTER, INSERT, MODIFY, SELECT, CREATE_SOURCE, WRITE, CREATE_TABLE, ALTER_REFLECTION, READ

Example: ["MODIFY"]

Attributes of the users and roles Objects

ownerId String (UUID)

Unique identifier of the space's owner.

Example: d01585a2-b267-4d56-9154-31762ab65a43

---

ownerType String

Type of owner of the space.

Enum: USER, ROLE

Example: USER

Creating a Space

Create a new space.

Method and URL

POST /api/v3/catalog

Parameters

entityType Body   String

Type of the catalog object. For spaces, the entityType is space.

Example: space

---

name Body   String

Name of the space.

Example: Example-Space

---

accessControlList Body   Object   Optional

Enterprise only. Object used to specify which users and roles should have access to the space and the specific privileges each user or role should have. May include an array of users, an array of roles, or both. Omit if you do not want to configure space-specific access control privileges.

Example: {"users": [{"id": "737a038f-c6cd-4fd3-a77a-59f692727ba5","permissions": ["MODIFY"]}],"roles": [{"id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889","permissions": ["MODIFY"]}]}

Parameters of the accessControlList Object

users Body   Array of Object   Optional

Enterprise only. List of users who should have access to the space and the specific privileges each user should have.

Example: [{"id": "737a038f-c6cd-4fd3-a77a-59f692727ba5","permissions": ["MODIFY"]}]

---

roles Body   Array of Object   Optional

Enterprise only. List of roles whose members should have access to the space and the specific privileges each role should have.

Example: [{"id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889","permissions": ["MODIFY"]}]

Parameters of the users and roles Objects

id Body   String   Optional

Enterprise only. Unique identifier of the user or role who should have access to the space.

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

---

permissions Body   Array of String   Optional

Enterprise only. List of privileges the user or role should have on the space. For more information, read Privileges.

Enum: ALL, VIEW_REFLECTION, TRUNCATE, UPDATE, DELETE, DROP, MANAGE_GRANTS, EXTERNAL_QUERY, EXECUTE, ALTER, INSERT, MODIFY, SELECT, CREATE_SOURCE, WRITE, CREATE_TABLE, ALTER_REFLECTION, READ

Example: ["MODIFY"]

Example Request

curl -X POST 'https://{hostname}/api/v3/catalog' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entityType": "space",
  "name": "Example-Space",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "MODIFY"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  }
}'

Example Response

{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "Example-Space",
  "tag": "zzOQfjY9lU0=",
  "createdAt": "2023-01-12T18:44:43.237Z",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "MODIFY"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  },
  "permissions": [],
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict

Retrieving a Space by ID

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

Method and URL

GET /api/v3/catalog/{id}

Parameters

id Path   String (UUID)

Unique identifier of the space that you want to retrieve.

Example: 5442c00a-ada1-48c6-82fc-bb804b2e04e0

---

include Query   String   Optional

Include a non-default attribute in the response. The available value for the include query parameter is permissions. For more information, read include and exclude Query Parameters.

Example: ?include=permissions

---

exclude Query   String   Optional

Exclude a default attribute from the response. The available value for the exclude query parameter is children. For more information, read include and exclude Query Parameters.

Example: ?exclude=children

Example Request

curl -X GET 'https://{hostname}/api/v3/catalog/5442c00a-ada1-48c6-82fc-bb804b2e04e0' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Example Response

{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "Example-Space",
  "tag": "zzOQfjY9lU0=",
  "createdAt": "2023-01-12T18:44:43.237Z",
  "children": [
    {
      "id": "8da037a1-8e50-422b-9a2b-cafb03f57c71",
      "path": [
        "Example-Space",
        "testfolder"
      ],
      "tag": "0McuCL4MzBU=",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "f32dfe85-32e2-4c31-b2b4-bfd62ab3f473",
      "path": [
        "Example-Space",
        "travel_testing"
      ],
      "tag": "i4mnlSmHqVM=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-01-30T17:54:25.547Z"
    },
    {
      "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
      "path": [
        "Example-Space",
        "zips"
      ],
      "tag": "ITlp8+qyIMQ=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-02-08T16:24:25.084Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "MODIFY"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes

200   OK

204   No Content

401   Unauthorized

403   Forbidden

404   Not Found

Retrieving a Space by Path

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

Method and URL

GET /api/v3/catalog/by-path/{path}

Parameters

path Path   String (UUID)

Path of the space that you want to retrieve. The path is the name of the space.

Example: Example-Space

---

include Query   String   Optional

Include a non-default attribute in the response. The available value for the include query parameter is permissions. For more information, read include and exclude Query Parameters.

Example: ?include=permissions

---

exclude Query   String   Optional

Exclude a default attribute from the response. The available value for the exclude query parameter is children. For more information, read include and exclude Query Parameters.

Example: ?exclude=children

Example Request

curl -X GET 'https://{hostname}/api/v3/catalog/by-path/Example-Space' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'

Example Response

{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "Example-Space",
  "tag": "zzOQfjY9lU0=",
  "createdAt": "2023-01-12T18:44:43.237Z",
  "children": [
    {
      "id": "8da037a1-8e50-422b-9a2b-cafb03f57c71",
      "path": [
        "Example-Space",
        "testfolder"
      ],
      "tag": "0McuCL4MzBU=",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "f32dfe85-32e2-4c31-b2b4-bfd62ab3f473",
      "path": [
        "Example-Space",
        "travel_testing"
      ],
      "tag": "i4mnlSmHqVM=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-01-30T17:54:25.547Z"
    },
    {
      "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
      "path": [
        "Example-Space",
        "zips"
      ],
      "tag": "ITlp8+qyIMQ=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-02-08T16:24:25.084Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "MODIFY"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes

200   OK

204   No Content

401   Unauthorized

403   Forbidden

404   Not Found

Updating a Space

Update the specified space.

Method and URL

PUT /api/v3/catalog/{id}

Parameters

id Path   String (UUID)

Unique identifier of the space that you want to update.

Example: 5442c00a-ada1-48c6-82fc-bb804b2e04e0

---

entityType Body   String

Type of the catalog object. For spaces, the entityType is space.

Example: space

---

id Body   String (UUID)

Unique identifier of the space to update.

Example: 5442c00a-ada1-48c6-82fc-bb804b2e04e0

---

name Body   String

Name of the space to update.

Example: Example-Space

---

tag Body   String (UUID)

Unique identifier of the version of the space that you want to update. Dremio uses the tag to ensure that you are requesting to update the most recent version of the space.

Example: zzOQfjY9lU0=

---

accessControlList Body   String   Optional

Enterprise only. Object used to specify which users and roles should have access to the space and the specific privileges each user or role should have. If you omit the accessControlList object in a PUT request, Dremio removes all existing user and role access settings from the space. To keep existing user and role access settings while making other updates, duplicate the existing accessControlList array in the PUT request.

Example: {"users": [{"id": "737a038f-c6cd-4fd3-a77a-59f692727ba5","permissions": ["ALL"]}],"roles": [{"id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889","permissions": ["MODIFY"]}]}

Parameters of the accessControlList Object

users Body   Array of Object   Optional

Enterprise only. List of users who should have access to the space and the specific privileges each user should have. If you omit the users object in a PUT request, Dremio removes all existing user access settings from the space. To keep existing user access settings while making other updates, duplicate the existing users array in the PUT request.

Example: [{"id": "737a038f-c6cd-4fd3-a77a-59f692727ba5", "permissions": ["ALL"]}]

---

roles Body   Array of Object   Optional

Enterprise only. List of roles whose members should have access to the space and the specific privileges each role should have. If you omit the roles object in a PUT request, Dremio removes all existing role access settings from the space. To keep existing role access settings while making other updates, duplicate the existing roles array in the PUT request.

Example: [{"id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889", "permissions": ["MODIFY"]}]

Parameters of the users and roles Objects

id Body   String   Optional

Enterprise only. Unique identifier of the user or role who should have access to the space.

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

---

permissions Body   Array of String   Optional

Enterprise only. List of privileges the user or role should have on the space. For more information, read Privileges.

Enum: ALL, VIEW_REFLECTION, TRUNCATE, UPDATE, DELETE, DROP, MANAGE_GRANTS, EXTERNAL_QUERY, EXECUTE, ALTER, INSERT, MODIFY, SELECT, CREATE_SOURCE, WRITE, CREATE_TABLE, ALTER_REFLECTION, READ

Example: ["ALL"]

Example Request

curl -X PUT 'https://{hostname}/api/v3/catalog/5442c00a-ada1-48c6-82fc-bb804b2e04e0' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "Example-Space",
  "tag": "zzOQfjY9lU0=",
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "ALL"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  }
}'

Example Response

{
  "entityType": "space",
  "id": "5442c00a-ada1-48c6-82fc-bb804b2e04e0",
  "name": "Example-Space",
  "tag": "PwZ6e/axHUY=",
  "createdAt": "2023-01-12T18:44:43.237Z",
  "children": [
    {
      "id": "8da037a1-8e50-422b-9a2b-cafb03f57c71",
      "path": [
        "Example-Space",
        "testfolder"
      ],
      "tag": "0McuCL4MzBU=",
      "type": "CONTAINER",
      "containerType": "FOLDER"
    },
    {
      "id": "f32dfe85-32e2-4c31-b2b4-bfd62ab3f473",
      "path": [
        "Example-Space",
        "travel_testing"
      ],
      "tag": "i4mnlSmHqVM=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-01-30T17:54:25.547Z"
    },
    {
      "id": "7f1c4660-cd7b-40d0-97d1-b8a6f431cbda",
      "path": [
        "Example-Space",
        "zips"
      ],
      "tag": "ITlp8+qyIMQ=",
      "type": "DATASET",
      "datasetType": "VIRTUAL",
      "createdAt": "2023-02-08T16:24:25.084Z"
    }
  ],
  "accessControlList": {
    "users": [
      {
        "id": "737a038f-c6cd-4fd3-a77a-59f692727ba5",
        "permissions": [
          "ALTER_REFLECTION",
          "MODIFY",
          "ALTER",
          "MANAGE_GRANTS",
          "VIEW_REFLECTION",
          "SELECT"
        ]
      }
    ],
    "roles": [
      {
        "id": "0f2d94e0-bb5e-4c03-8c6f-62d379d10889",
        "permissions": [
          "MODIFY"
        ]
      }
    ]
  },
  "owner": {
    "ownerId": "d01585a2-b267-4d56-9154-31762ab65a43",
    "ownerType": "USER"
  }
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

409   Conflict

Deleting a Space

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

Method and URL

DELETE /api/v3/catalog/{id}

Parameters

id Path   String (UUID)

Unique identifier of the space that you want to delete.

Example: 5442c00a-ada1-48c6-82fc-bb804b2e04e0

Example Request

curl -X DELETE 'https://{hostname}/api/v3/catalog/5442c00a-ada1-48c6-82fc-bb804b2e04e0' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json' 

Example Response

No response

Response Status Codes

204   No Content

401   Unauthorized

403   Forbidden

404   Not Found