On this page

    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

    [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" } ]

    children

    id

    String (UUID)

    Unique identifier of the catalog object.

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


    path

    [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 containerType is FOLDER.

    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

    path

    String (UUID)

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

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


    Example Request
    curl -X GET 'https://{hostname}/api/v3/catalog/63505c60-bc86-42aa-a622-24e5f22ce50b' \
    --header 'Authorization: _dremio{tokenstring}' \
    --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

    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


    Example Request
    curl -X GET 'https://{hostname}/api/v3/catalog/by-path/@user@dremio.com' \
    --header 'Authorization: _dremio{tokenstring}' \
    --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

    404

    Not Found