> ## Documentation Index > Fetch the complete documentation index at: https://morphik.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Folder Management > Organize and isolate data into logical folder groups in Morphik ## Overview Folders in Morphik provide a way to organize documents into logical groups. This is particularly useful for multi-project environments where you want to maintain separation between different contexts. Documents within a folder are isolated from those in other folders, allowing for clean organization and data separation. > ℹ️ All folder APIs accept **folder UUIDs, names, or canonical paths** (e.g., `"/projects/alpha/specs"`). Folder objects expose `full_path`, `parent_id`, `depth`, and `child_count`; documents expose `folder_path` to mirror server responses. ## Creating and Accessing Folders ```python theme={null} from morphik import Morphik db = Morphik() # Create a new folder folder = db.create_folder("marketing_docs") # Create a nested folder (parents created automatically) nested = db.create_folder(full_path="/projects/alpha/specs") # Access an existing folder by name/path or UUID folder = db.get_folder("/projects/alpha") folder_by_id = db.get_folder(folder.id) ``` ```python theme={null} from morphik import AsyncMorphik async with AsyncMorphik() as db: # Create a new folder folder = await db.create_folder("marketing_docs") nested = await db.create_folder(full_path="/projects/alpha/specs") # Access an existing folder by name/path or UUID folder = await db.get_folder("/projects/alpha") folder_by_id = await db.get_folder(folder.id) ``` ## Operations Within a Folder Once you have a folder object, all operations performed on it are scoped to that folder. Documents created, retrieved, or manipulated will be contained within this folder's scope. ```python theme={null} # Get a folder folder = db.get_folder("marketing_docs") # Ingest a document into this folder doc = folder.ingest_text("New marketing strategy for Q3", filename="strategy_q3.txt", metadata={"department": "marketing", "quarter": "Q3"}) # Retrieve documents only from this folder marketing_docs = folder.list_documents() # Search documents only within this folder results = folder.retrieve_chunks("marketing strategy") # Query within the folder context response = folder.query("What is our Q3 marketing strategy?") ``` ```python theme={null} # Get a folder folder = db.get_folder("marketing_docs") # Ingest a document into this folder doc = await folder.ingest_text("New marketing strategy for Q3", filename="strategy_q3.txt", metadata={"department": "marketing", "quarter": "Q3"}) # Retrieve documents only from this folder marketing_docs = await folder.list_documents() # Search documents only within this folder results = await folder.retrieve_chunks("marketing strategy") # Query within the folder context response = await folder.query("What is our Q3 marketing strategy?") ``` ## Nested Folders and Scope Depth Folders can be nested arbitrarily. Use canonical paths (leading slash optional) to address them, and include descendant folders in retrieval/listing by setting `folder_depth`: ```python theme={null} folder = db.create_folder(full_path="/projects/alpha/specs") # Query across /projects/alpha and all children chunks = db.retrieve_chunks( query="design notes", folder_name="/projects/alpha", folder_depth=-1, # -1: all descendants, 0/None: exact only, n>0: include up to n levels ) ``` Folder-scoped helpers inherit the path automatically, so `folder.retrieve_chunks(..., folder_depth=-1)` will include its children. ## Expanding Scope with Additional Folders Folder-scoped retrieval/list/query helpers accept `additional_folders` to include extra folders in the same request: ```python theme={null} folder = db.get_folder("/projects/alpha") # Search across /projects/alpha plus shared archives results = folder.retrieve_chunks( "design notes", additional_folders=["/shared", "/archive"], ) ``` ## Folder Methods All the core document operations available on the main Morphik client are also available on folder objects, but they are automatically scoped to the specific folder: * `ingest_text` - Ingest text content into this folder * `ingest_file` - Ingest a file into this folder * `ingest_files` - Ingest multiple files into this folder * `ingest_directory` - Ingest all files from a directory into this folder * `retrieve_chunks` - Retrieve chunks matching a query from this folder (supports [reverse image search](/python-sdk/retrieve_chunks#reverse-image-search)) * `retrieve_docs` - Retrieve documents matching a query from this folder * `query` - Generate a completion using context from this folder (supports `llm_config` parameter for custom LLM configuration) * `list_documents` - List all documents in this folder * `batch_get_documents` - Get multiple documents by their IDs from this folder * `batch_get_chunks` - Get specific chunks by source from this folder * `get_info` - Fetch the latest folder metadata from the API * `get_summary` - Fetch the latest folder summary * `upsert_summary` - Create or update the folder summary * `delete_document_by_filename` - Delete a document by filename from this folder ## Managing Existing Documents and Folders You can move previously ingested documents into a folder, remove them, or delete the entire folder. The SDK methods accept a folder UUID, name, or canonical path. ```python theme={null} from morphik import Morphik db = Morphik() folder = db.get_folder("marketing_docs") document_id = "doc_123" # Add an existing document to the folder (name/path or UUID works) db.add_document_to_folder(folder.id, document_id) db.add_document_to_folder("/projects/alpha/specs", document_id) # Remove the document from the folder db.remove_document_from_folder("marketing_docs", document_id) # Delete the folder (also removes its documents) db.delete_folder(folder.id) ``` ```python theme={null} from morphik import AsyncMorphik async with AsyncMorphik() as db: folder = await db.get_folder("marketing_docs") document_id = "doc_123" await db.add_document_to_folder(folder.id, document_id) await db.add_document_to_folder("/projects/alpha/specs", document_id) await db.remove_document_from_folder("marketing_docs", document_id) await db.delete_folder(folder.id) ``` ## Using Custom LLM Configuration with Folders You can pass a custom LLM configuration when querying within a folder: ```python theme={null} from morphik import Morphik db = Morphik() folder = db.get_folder("research") # Use a specific model for this query response = folder.query( "Summarize the latest findings", llm_config={ "model": "claude-3-opus-20240229", "temperature": 0.5 } ) print(response.completion) ``` ```python theme={null} from morphik import AsyncMorphik async with AsyncMorphik() as db: folder = db.get_folder("research") # Use a specific model for this query response = await folder.query( "Summarize the latest findings", llm_config={ "model": "claude-3-opus-20240229", "temperature": 0.5 } ) print(response.completion) ``` ## Example: Project Document Management A common use case for folders is separating different projects. Here's an example of how to organize project documentation: ```python theme={null} from morphik import Morphik from pathlib import Path db = Morphik() # Create folders for different projects project_a = db.create_folder("project_a") project_b = db.create_folder("project_b") # Ingest project documentation into respective folders project_a.ingest_directory(Path("/path/to/project_a_docs"), recursive=True, metadata={"project": "Project A"}) project_b.ingest_directory(Path("/path/to/project_b_docs"), recursive=True, metadata={"project": "Project B"}) # Query is scoped to just Project A documents project_a_response = project_a.query("What are the key milestones for this project?") # Query is scoped to just Project B documents project_b_response = project_b.query("What are the technical requirements?") ``` ```python theme={null} from morphik import AsyncMorphik from pathlib import Path async with AsyncMorphik() as db: # Create folders for different projects project_a = db.create_folder("project_a") project_b = db.create_folder("project_b") # Ingest project documentation into respective folders await project_a.ingest_directory(Path("/path/to/project_a_docs"), recursive=True, metadata={"project": "Project A"}) await project_b.ingest_directory(Path("/path/to/project_b_docs"), recursive=True, metadata={"project": "Project B"}) # Query is scoped to just Project A documents project_a_response = await project_a.query("What are the key milestones for this project?") # Query is scoped to just Project B documents project_b_response = await project_b.query("What are the technical requirements?") ``` ## Accessing a Folder's User Scope You can further scope operations within a folder to a specific user by using the `signin` method on the folder object: ```python theme={null} # Get a folder project_folder = db.get_folder("project_x") # Create a user scope within this folder user_in_project = project_folder.signin("user_123") # This document is accessible only to user_123 within project_x doc = user_in_project.ingest_text("User-specific project notes") ``` ```python theme={null} # Get a folder project_folder = db.get_folder("project_x") # Create a user scope within this folder user_in_project = project_folder.signin("user_123") # This document is accessible only to user_123 within project_x doc = await user_in_project.ingest_text("User-specific project notes") ``` See [User Management](/python-sdk/users) for more details on working with user scopes.