Folders¶

Folders organize workspace items into a hierarchical structure, making it easier to manage large collections of items in a Fabric workspace.

Preview Feature

The Folders API is part of a Preview release and may change in future versions.

Getting a Folder¶

import fabias

ws = fabias.workspace("Analytics")

# By name (must be unique in workspace)
folder = ws.folder("Sales")

# By GUID
folder = ws.folder("a1b2c3d4-...")

# By path (slash-separated)
folder = ws.folder("Sales/Q1/January")

Path Resolution¶

When using slash-separated paths, the SDK walks the folder tree from the workspace root:

# Gets the "January" folder inside "Q1" inside root-level "Sales"
folder = ws.folder("Sales/Q1/January")

Listing Folders¶

ws = fabias.workspace("Analytics")

# List all folders recursively (default)
for folder in ws.folders():
    print(f"{folder.name} (parent: {folder.parent})")

# List only direct children of a specific folder
parent = ws.folder("Sales")
children = ws.folders(root_folder_id=parent.id, recursive=False)

# List only root-level folders (no nesting)
root_folders = ws.folders(root_folder_id=None, recursive=False)

Creating Folders¶

ws = fabias.workspace("Analytics")

# Create at workspace root
sales = ws.folders.add("Sales")

# Create nested folder
q1 = ws.folders.add("Q1", parent=sales.id)

# Create deeply nested folder
january = ws.folders.add("January", parent=q1.id)

Folder Properties¶

folder = ws.folder("Sales/Q1")

print(f"ID: {folder.id}")
print(f"Name: {folder.name}")
print(f"Workspace ID: {folder.workspace_id}")
print(f"Parent ID: {folder.parent}")  # None if at workspace root

Renaming Folders¶

folder = ws.folder("Sales")

# Rename (returns self for chaining)
folder.rename("Revenue")

print(f"New name: {folder.name}")

Moving Folders¶

ws = fabias.workspace("Analytics")

# Get folders
folder = ws.folder("Sales/Q1")
target = ws.folder("Archive")

# Move Q1 into Archive
folder.move(target_folder_id=target.id)

# Move Q1 to workspace root
folder.move()  # or folder.move(target_folder_id=None)

Circular Hierarchies

Moving a folder into one of its own descendants will fail with an error.

Deleting Folders¶

Folders must be empty (no items or nested folders) before deletion:

folder = ws.folder("Sales/Q1")

# Delete the folder
folder.delete()

# Or delete by name/ID via accessor
ws.folders.delete("Old Folder")

Building Folder Hierarchy¶

import fabias

ws = fabias.workspace("Analytics")

# Create a nested folder structure
sales = ws.folders.add("Sales")

for quarter in ["Q1", "Q2", "Q3", "Q4"]:
    q = ws.folders.add(quarter, parent=sales.id)

    # Add subfolders for each quarter
    ws.folders.add("Raw", parent=q.id)
    ws.folders.add("Processed", parent=q.id)
    ws.folders.add("Archived", parent=q.id)

Refreshing Folder Data¶

Folder properties are lazy-loaded and cached. To force a refresh:

folder = ws.folder("Sales")

# Make changes via web UI or another client...

# Refresh local data
folder.refresh()
print(f"Updated name: {folder.name}")

Example: Folder Tree Report¶

import fabias

def print_tree(folders, parent_id=None, indent=0):
    """Print folder tree recursively."""
    for folder in folders:
        if folder.parent == parent_id:
            print("  " * indent + f"?? {folder.name}")
            print_tree(folders, folder.id, indent + 1)

ws = fabias.workspace("Analytics")
all_folders = ws.folders()

print(f"\n{ws.name} Folder Structure:")
print_tree(all_folders)

Example: Organize Items by Type¶

import fabias

ws = fabias.workspace("Analytics")

# Create folders for each item type
folders = {
    "Pipelines": ws.folders.add("Pipelines"),
    "Lakehouses": ws.folders.add("Lakehouses"),
    "Notebooks": ws.folders.add("Notebooks"),
}

print("Folder structure created!")

Error Handling¶

Multiple Matches¶

When getting a folder by name (without path), the name must be unique:

# If there are two folders named "Sales" at different levels
try:
    folder = ws.folder("Sales")  # ? Ambiguous
except FabiasError as e:
    print(e)  # Suggests using full paths

# Use full path instead
folder = ws.folder("Archive/Sales")  # ? Unambiguous

Folder Not Found¶

from fabias import NotFoundError

try:
    folder = ws.folder("NonExistent")
except NotFoundError:
    print("Folder not found")