Dremio Cloud
Dremio Software
 
On this page

    Endpoints

    Introduced in Dremio 2.0.0.

    See Models for details on object representations.

    List all top level catalog containers

    GET /api/v3/catalog

    Output

    {
  "data": [
     CatalogEntitySummary,
     ...
  ]
}

    Retrieve a specific catalog entity

    GET /api/v3/catalog/{id}

    Id for a source, space, folder, file or dataset.

    Output

    CatalogEntity

    Response Codes

    403 - user does not have permission to view the catalog entity.

    404 - a catalog entity with the specified id could not be found.

    Retrieve a catalog entity by path

    Note:
    Introduced in Dremio 2.1.0

    GET /api/v3/catalog/by-path/{path}

    Path is the Dremio path for the entity, using / as a separator. Each path component should be url escaped.

    For example, given a source called MySource which has a folder called MyFolder that contains a dataset called MyDataset, the URL will look like this:

    GET /api/v3/catalog/by-path/MySource/MyFolder/MyDataset

    If the dataset was called My?Dataset, then the URL will be:

    GET /api/v3/catalog/by-path/MySource/MyFolder/My%3FDataset

    This is because ? is a special character in URLs and we have to url escape it.

    Output

    CatalogEntity

    Response Codes

    403 - user does not have permission to view the catalog entity.

    404 - a catalog entity with the specified path could not be found.

    Create a new catalog entity

    POST /api/v3/catalog

    Input

    CatalogEntity

    The catalog entity supplied must not contain any Dremio generated fields such id or tag.

    The following entities can be created:

    • Dataset - Only Virtual Datasets can be created here and the supplied path determines where the dataset is stored.

    • Folder - Folders can only be created in the user’s Home Space or any Spaces that the user has write access to.

    • Space

    • Source

    Output

    CatalogEntity

    Response Codes

    400 - the supplied CatalogEntity object is invalid.

    403 - user does not have permission to create the catalog entity.

    409 - a catalog entity with the specified path already exists.

    Update an existing catalog entity

    PUT /api/v3/catalog/{id}

    Input

    CatalogEntity

    Only datasets and sources can be edited.

    Output

    CatalogEntity

    Response Codes

    400 - the supplied CatalogEntity object is invalid.

    403 - user does not have permission to create the catalog entity.

    404 - a catalog entity with the specified id could not be found.

    409 - a catalog entity with the specified path already exists.

    Delete an existing catalog entity

    DELETE /api/v3/catalog/{id}?tag={tag}

    Response Codes

    403 - user does not have permission to delete the catalog entity.

    404 - a catalog entity with the specified id could not be found.

    Promote a folder or file to a dataset

    POST /api/v3/catalog/{id}

    Folders and files inside a source can be promoted to physical datasets. This will convert the folder/file to a dataset, which will then have a new id as it is a new entity.

    The supplied path is used to determine what entity is promoted.

    To unpromote a dataset you delete the dataset, which will revert it back to its original form (a folder or file).

    Input

    Dataset

    Output

    Dataset

    400 - the supplied CatalogEntity object is invalid.

    403 - user does not have permission to create the catalog entity.

    Refreshing a catalog entity

    Currently only works on datasets. Will refresh all dependant reflections of the specified dataset.

    POST /api/v3/catalog/{id}/refresh

    403 - user does not have permission to access the catalog entity.

    404 - a catalog entity with the specified id could not be found.