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

Example: ?maxChildren=25

pageToken Query String Optional

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

Home Attributes​

Attributes of Objects in the children Array​

Retrieving the Home Space by ID​

Parameters​

Response Status Codes​

Retrieving the Home Space by Path​

Parameters​

Response Status Codes​

Home Attributes

Attributes of Objects in the `children` Array

Retrieving the Home Space by ID

Parameters

Response Status Codes

Retrieving the Home Space by Path

Parameters

Response Status Codes