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.