On this page

    Catalog API

    Use the Catalog API to retrieve and manage sources and spaces as well as the folders, files, tables, and views they contain. The Catalog API also includes endpoints for retrieving lineage information for datasets and for creating and managing tags, wikis, privileges, and grants on catalog objects.

    Use the Catalog API endpoint described on this page to retrieve a list of the spaces and sources in your Dremio organization. The response contains the IDs required to make requests to other Catalog API endpoints to create, retrieve, update, and delete objects in your catalog.

    Catalog Object
    {
      "data": [
        {
          "id": "a7b1bc39-bffa-4c30-a5eb-5bdaf5bd0959",
          "path": [
            "@dremio"
          ],
          "tag": "0QVA7wGyiY0=",
          "type": "CONTAINER",
          "containerType": "HOME",
          "stats": {
            "datasetCount": 18,
            "datasetCountBounded": false
          },
          "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"
          ]
        },
        {
          "id": "ed1013cb-4fea-6552-8d43-015215a38bcc",
          "path": [
            "Testing"
          ],
          "tag": "PR1M7B1Rhjs=",
          "type": "CONTAINER",
          "containerType": "SPACE",
          "stats": {
            "datasetCount": 3,
            "datasetCountBounded": false
          },
          "createdAt": "2023-02-14T19:28:40.840Z",
          "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"
          ]
        },
        {
          "id": "6b714877-760e-115b-aefd-799430b3ceab",
          "path": [
            "Samples"
          ],
          "tag": "nEjWZGnrAO0=",
          "type": "CONTAINER",
          "containerType": "SOURCE",
          "stats": {
            "datasetCount": 10,
            "datasetCountBounded": false
          },
          "createdAt": "2023-01-04T22:13:02.536Z",
          "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"
          ]
        }
      ]
    }
    

    Catalog Attributes

    data

    [Object]

    List of catalog objects in the Dremio organization.

    data

    id

    String (UUID)

    Unique identifier of the catalog object.

    Example ed1013cb-4fea-6552-8d43-015215a38bcc


    path

    [String]

    Path of the catalog object within Dremio, expressed as an array.

    Example [ "Testing" ]


    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 catalog object.

    Example PR1M7B1Rhjs=


    type

    String

    Type of the catalog object. For objects that can contain other catalog objects (the only objects this endpoint retrieves), the type is CONTAINER.

    Example CONTAINER


    containerType

    String

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

    Enum SPACE , SOURCE , FOLDER , HOME

    Example SPACE


    stats

    Object

    Optional

    Information about the number of datasets in the catalog object and whether the dataset count is bounded. Appears in the response only if the request URL includes the datasetCount query parameter.

    Example { "datasetCount": 18, "datasetCountBounded": false }


    createdAt

    String

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

    Example 2023-02-14T19:28:40.840Z


    permissions

    [String]

    Enterprise-only. List of the privileges that you have on the catalog object. 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" ]

    stats

    datasetCount

    Integer

    Number of datasets the catalog object contains.

    Example 18


    datasetCountBounded

    Boolean

    If the dataset count is bounded, the value is true. Otherwise, the value is false.

    Example false

    Retrieving a Catalog

    Retrieve the catalog for the current Dremio instance.

    Method and URL
    GET /api/v3/catalog
    

    Parameters

    include

    query

    String

    Optional

    Include a non-default attribute in the response. The available values for the include query parameter are permissions (Enterprise-only) and datasetCount. Specify permissions to include each catalog object's permissions array in the response. Specify datasetCount to include the stats object in the response. For more information, read include and exclude Query Parameters.

    Example ?include=permissions


    Example Request
    curl -X GET 'https://{hostname}/api/v3/catalog' \
    --header 'Authorization: _dremio{tokenstring}' \
    --header 'Content-Type: application/json'
    
    Example Response
    {
      "data": [
        {
          "id": "a7b1bc39-bffa-4c30-a5eb-5bdaf5bd0959",
          "path": [
            "@dremio"
          ],
          "tag": "0QVA7wGyiY0=",
          "type": "CONTAINER",
          "containerType": "HOME"
        },
        {
          "id": "ed1013cb-4fea-6552-8d43-015215a38bcc",
          "path": [
            "Testing"
          ],
          "tag": "PR1M7B1Rhjs=",
          "type": "CONTAINER",
          "containerType": "SPACE",
          "createdAt": "2023-02-14T19:28:40.840Z"
        },
        {
          "id": "6b714877-760e-115b-aefd-799430b3ceab",
          "path": [
            "Samples"
          ],
          "tag": "nEjWZGnrAO0=",
          "type": "CONTAINER",
          "containerType": "SOURCE",
          "createdAt": "2023-01-04T22:13:02.536Z"
        }
      ]
    }
    

    Response Status Codes

    200

    OK

    401

    Unauthorized

    404

    Not Found