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


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.