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 URLGET /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 Requestcurl -X GET 'https://{hostname}/api/v3/catalog/63505c60-bc86-42aa-a622-24e5f22ce50b' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
{
"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 URLGET /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 Requestcurl -X GET 'https://{hostname}/api/v3/catalog/by-path/@user@dremio.com' \
--header 'Authorization: Bearer <PersonalAccessToken>' \
--header 'Content-Type: application/json'
{
"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