Folders
Access folders through client.folders in the Datature Vi SDK.
Datature Vi datasets are flat by default. Folders add a virtual tree on top: useful for browsing large collections in the UI and for filtering assets by parent folder. Folders do not move files on disk. They purely add navigable structure, so creating and deleting them never touches your media or annotations.
- Vi SDK installed with authentication configured
- An existing dataset with assets uploaded
Use "/" as the folder name to address the dataset root.
Methods
list()
List folders defined in a dataset.
folders = client.folders.list("dataset_abc123")
for folder in folders.items:
print(folder.get("name"))page = client.folders.list(
dataset_id="dataset_abc123",
sort_by="name",
sort_order="asc",
)
for folder in page.all_items():
print(folder["name"])# Folders require a dataset_id, so use the call syntax to iterate
for folder in client.folders(dataset_id="dataset_abc123"):
print(folder.get("name"))Returns: PaginatedResponse[dict]. A page of folder documents.
Raises: ViValidationError if dataset_id is invalid. ViOperationError on an unexpected response shape.
get()
Fetch a single folder by name.
folder = client.folders.get("dataset_abc123", "raw/2025-05")
print(folder)root = client.folders.get("dataset_abc123", "/")
print(root)Returns: dict. The folder document.
Raises: ViValidationError if parameters are invalid. ViNotFoundError if the folder does not exist.
children()
List the children of a folder: subfolders and assets in one heterogeneous page.
Each entry carries a kind of "Folder" or "Asset" plus the corresponding resource payload, mirroring the platform response shape so you can render breadcrumb-style navigation.
page = client.folders.children("dataset_abc123", "raw/2025-05")
for entry in page.all_items():
if entry["kind"] == "Folder":
print("DIR ", entry["resource"]["name"])
else:
print("FILE", entry["resource"]["filename"])page = client.folders.children(
dataset_id="dataset_abc123",
folder_name="/",
child_type="Folder",
)
for entry in page.all_items():
print(entry["resource"]["name"])def walk(dataset_id, folder="/", depth=0):
page = client.folders.children(dataset_id, folder, child_type="All")
for entry in page.all_items():
name = entry["resource"].get("name") or entry["resource"].get("filename")
print(" " * depth + name)
if entry["kind"] == "Folder":
walk(dataset_id, entry["resource"]["name"], depth + 1)
walk("dataset_abc123")Returns: PaginatedResponse[dict]. Heterogeneous page of {kind, resource} children.
put()
Create or overwrite a folder by name.
folder = client.folders.put(
dataset_id="dataset_abc123",
folder_name="raw/2025-05",
)
print(folder)client.folders.put(
dataset_id="dataset_abc123",
folder_name="review/pending",
owner="user_abc123",
)Returns: dict. The created or updated folder document.
delete()
Delete a folder by name.
client.folders.delete("dataset_abc123", "raw/2025-05/morning")Returns: DeletedResource. Confirmation of deletion.
delete_all()
Delete every folder in a dataset.
This removes all folder definitions in the dataset. The underlying assets and annotations are left intact, but the folder organization is not recoverable.
client.folders.delete_all("dataset_abc123")Returns: bool. True when the API confirms the bulk delete.
Response format
Folders are returned as plain dictionaries mirroring the platform's folder documents.
For children(), each entry is a {kind, resource} pair where kind is "Folder" or "Asset".
Related resources
Updated 1 day ago