Skip to main content
Version: current [25.x]

Home

Use the Catalog API to retrieve information about the home space and the child objects it contains.

Home Object
{
"entityType": "home",
"id": "87049e43-8564-4ee7-8bb6-5bdaf5bd0959",
"name": "@user@dremio.com",
"tag": "8S9cTZ5IsWo=",
"children": [
{
"id": "1e16c0e5-c890-4f87-b1a6-ac9325aafa2c",
"path": [
"@user@dremio.com",
"Business"
],
"tag": "KgFBPW3+Cyc=",
"type": "CONTAINER",
"containerType": "FOLDER"
},
{
"id": "a59815d0-3c21-41ad-b9bc-2ba105251fa6",
"path": [
"@user@dremio.com",
"meeting_rooms_lookup"
],
"tag": "OaQT64frevc=",
"type": "DATASET",
"datasetType": "PROMOTED",
"createdAt": "1970-01-01T00:00:00.000Z"
},
{
"id": "37401663-8666-4e00-bc03-668abb43ccd7",
"path": [
"@user@dremio.com",
"NYC-trips-quarterly"
],
"tag": "+H5TpLYoosY=",
"type": "DATASET",
"datasetType": "VIRTUAL",
"createdAt": "2023-02-07T21:26:14.385Z"
}
]
}

Home Attributes

entityType String

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

Example: home


id String (UUID)

Unique identifier of the home space.

Example: 87049e43-8564-4ee7-8bb6-5bdaf5bd0959


name String

Name of the home space. Automatically generated based on the username.

Example: @user@dremio.com


tag String

Unique identifier of the version of the home space. Dremio uses tags to ensure that PUT requests apply to the most recent version of the resource being updated. However, home spaces cannot be changed, so the tag is listed in the home space object but not used.

Example: 8S9cTZ5IsWo=


children Array of Object

Information about each catalog object in the home space.

Example: [{"id":"1e16c0e5-c890-4f87-b1a6-ac9325aafa2c","path": ["@dremio","Business"],"tag":"KgFBPW3+Cyc=","type":"CONTAINER","containerType":"FOLDER"},{"id":"a59815d0-3c21-41ad-b9bc-2ba105251fa6","path": ["@dremio","meeting_rooms_lookup"],"tag":"OaQT64frevc=","type":"DATASET","datasetType":"PROMOTED","createdAt":"1970-01-01T00:00:00.000Z"},{"id":"37401663-8666-4e00-bc03-668abb43ccd7","path": ["@dremio","NYC-trips-quarterly"],"tag":"+H5TpLYoosY=","type":"DATASET","datasetType":"VIRTUAL","createdAt":"2023-02-07T21:26:14.385Z"}]

Attributes of Objects in the children Array

id String (UUID)

Unique identifier of the catalog object.

Example: 1e16c0e5-c890-4f87-b1a6-ac9325aafa2c


path Array of String

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

Example: ["@user@dremio.com","Business"]


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: KgFBPW3+Cyc=


type String

Type of the catalog object.

Enum: CONTAINER, DATASET

Example: CONTAINER


containerType String

For catalog entities with the type CONTAINER, the type of container.

Enum: FOLDER, FUNCTION

Example: FOLDER


datasetType String

For catalog entities with the type DATASET, the type of dataset. For tables, the datasetType is PROMOTED. For views, the datasetType is VIRTUAL.

Enum: PROMOTED, VIRTUAL

Example: PROMOTED


createdAt String

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

Example: 2023-02-07T21:26:14.385Z

Retrieving the Home Space by ID

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

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

Parameters

id Body   String (UUID)

Unique identifier of the home space that you want to retrieve.

Example: 87049e43-8564-4ee7-8bb6-5bdaf5bd0959


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.

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 home space 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.

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

Example Request
curl -X GET 'https://{hostname}/api/v3/catalog/63505c60-bc86-42aa-a622-24e5f22ce50b' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response
{
"entityType": "home",
"id": "87049e43-8564-4ee7-8bb6-5bdaf5bd0959",
"name": "@user@dremio.com",
"tag": "8S9cTZ5IsWo=",
"children": [
{
"id": "1e16c0e5-c890-4f87-b1a6-ac9325aafa2c",
"path": [
"@user@dremio.com",
"Business"
],
"tag": "KgFBPW3+Cyc=",
"type": "CONTAINER",
"containerType": "FOLDER"
},
{
"id": "a59815d0-3c21-41ad-b9bc-2ba105251fa6",
"path": [
"@user@dremio.com",
"meeting_rooms_lookup"
],
"tag": "OaQT64frevc=",
"type": "DATASET",
"datasetType": "PROMOTED",
"createdAt": "1970-01-01T00:00:00.000Z"
},
{
"id": "37401663-8666-4e00-bc03-668abb43ccd7",
"path": [
"@user@dremio.com",
"NYC-trips-quarterly"
],
"tag": "+H5TpLYoosY=",
"type": "DATASET",
"datasetType": "VIRTUAL",
"createdAt": "2023-02-07T21:26:14.385Z"
}
]
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found

Retrieving the Home Space by Path

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

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

Parameters

path Path   String

Path of the home space whose information you want to retrieve. The home space path is the username, preceded with the @ symbol.

Example: @user@dremio.com


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.

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 home space 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.

Example: ?pageToken=cHAAFLceQCKsTVpwaEVisqgjDntZJUCuTqVNghPdkyBDUNoJvwrEXAMPLE

Example Request
curl -X GET 'https://{hostname}/api/v3/catalog/by-path/@user@dremio.com' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
Example Response
{
"entityType": "home",
"id": "87049e43-8564-4ee7-8bb6-5bdaf5bd0959",
"name": "@user@dremio.com",
"tag": "8S9cTZ5IsWo=",
"children": [
{
"id": "1e16c0e5-c890-4f87-b1a6-ac9325aafa2c",
"path": [
"@user@dremio.com",
"Business"
],
"tag": "KgFBPW3+Cyc=",
"type": "CONTAINER",
"containerType": "FOLDER"
},
{
"id": "a59815d0-3c21-41ad-b9bc-2ba105251fa6",
"path": [
"@user@dremio.com",
"meeting_rooms_lookup"
],
"tag": "OaQT64frevc=",
"type": "DATASET",
"datasetType": "PROMOTED",
"createdAt": "1970-01-01T00:00:00.000Z"
},
{
"id": "37401663-8666-4e00-bc03-668abb43ccd7",
"path": [
"@user@dremio.com",
"NYC-trips-quarterly"
],
"tag": "+H5TpLYoosY=",
"type": "DATASET",
"datasetType": "VIRTUAL",
"createdAt": "2023-02-07T21:26:14.385Z"
}
]
}

Response Status Codes

200   OK

400   Bad Request

401   Unauthorized

403   Forbidden

404   Not Found