Add folder name filtering capabilities to documentation

concepts/user-folder-scoping.mdx

@@ -1,13 +1,13 @@
 ---
 title: 'User and Folder Scoping'
 description: 'Organizing data with user and folder scoping in Morphik'
 ---
 
 Morphik provides powerful mechanisms to organize and isolate your data through **user scoping** and **folder scoping**. These features allow you to create logical boundaries for different projects or user groups while maintaining a unified database.
 
 ## Folder Scoping
 
 Folders in Morphik allow you to organize documents into logical groups, similar to directories in a file system, but for your unstructured data. Operations performed within a folder scope only affect documents within that folder.
 
 ### When to Use Folder Scoping
 
@@ -97,12 +97,55 @@
 
 ## Important Considerations
 
 - All methods available on the main Morphik client are also available on folder and user scopes
 - Operations performed within a scope are isolated to that scope
 - Documents created within a scope are only accessible within that scope, unless explicitly queried with appropriate filters
 - Scopes can be used for both reading and writing operations
 - User and folder information is stored as metadata with the documents, so you can still filter across scopes with explicit filter parameters if needed
 
+## Filtering by Folder Name in Metadata
+
+When you ingest documents in a folder with the `folder_name` parameter, that value is automatically available in the document's metadata for filtering. This enables powerful cross-folder queries using Morphik's metadata filter operators:
+
+```python
+from morphik import Morphik
+
+db = Morphik()
+
+# Filter documents from multiple folders
+filters = {
+    "folder_name": {"$in": ["legal", "hr", "finance"]}
+}
+docs = db.list_documents(filters=filters)
+
+# Combine folder filtering with other metadata
+filters = {
+    "$and": [
+        {"folder_name": {"$regex": {"pattern": "^project_", "flags": "i"}}},
+        {"status": "active"},
+        {"priority": {"$gte": 70}}
+    ]
+}
+response = db.query("What are the high-priority project updates?", filters=filters)
+
+# Exclude specific folders
+filters = {
+    "$and": [
+        {"folder_name": {"$nin": ["archived", "drafts"]}},
+        {"created_date": {"$gte": "2024-01-01"}}
+    ]
+}
+chunks = db.retrieve_chunks("quarterly report", filters=filters, k=10)
+```
+
+This approach is useful when you need to:
+- Query across multiple folders simultaneously
+- Use pattern matching on folder names
+- Combine folder filters with complex metadata conditions
+- Build dynamic queries where folder selection isn't known at scope creation time
+
+For more filtering examples, see the [Complex Metadata Filtering](/cookbooks/complex-metadata-filtering) cookbook and [Metadata Filtering](/concepts/metadata-filtering) reference.
+
 ## Use Cases
 
 ### Multi-Project Research Team

cookbooks/complex-metadata-filtering.mdx

@@ -3,16 +3,16 @@
 description: "Advanced document filtering using dates, arrays, decimals, and multiple operators for precise retrieval."
 ---
 
 This cookbook demonstrates Morphik's advanced metadata filtering capabilities with rich typed metadata fields including dates, decimals, booleans, arrays, and nested objects.
 
 > **Prerequisites**
 > - Install the Morphik SDK: `pip install morphik`
 > - Provide credentials via Morphik URI
 > - Basic understanding of document ingestion
 
 ## 1. Ingest Documents with Rich Typed Metadata
 
 Morphik supports various metadata types for sophisticated filtering:
 
 ```python
 from datetime import date, datetime, timezone
@@ -99,6 +99,40 @@
 }
 ```
 
+### Filtering by Folder Name
+
+Documents ingested with a `folder_name` parameter can be filtered using that value in metadata. This enables cross-folder queries and pattern matching:
+
+```python
+# Filter specific folder
+filters = {"folder_name": "reports"}
+
+# Query multiple folders
+filters = {
+    "folder_name": {"$in": ["reports", "invoices", "contracts"]}
+}
+
+# Exclude archived folders
+filters = {
+    "folder_name": {"$nin": ["archived", "drafts", "test"]}
+}
+
+# Pattern matching on folder names
+filters = {
+    "folder_name": {"$regex": {"pattern": "^project_", "flags": "i"}}
+}
+
+# Combine folder with other metadata
+filters = {
+    "$and": [
+        {"folder_name": {"$in": ["legal", "compliance"]}},
+        {"priority": {"$gte": 70}},
+        {"status": "active"},
+        {"year": 2024}
+    ]
+}
+```
+
 ## 3. List Documents with Filters
 
 Find documents matching your criteria:
@@ -222,4 +256,4 @@
 ## Related Cookbooks
 
 - [Generating Completions with Retrieved Chunks](./generating-completions-with-retrieved-chunks) - Send filtered chunks to OpenAI
 - [Python SDK Basic Operations](./python-basic-operations) - Core Morphik operations

python-sdk/query.mdx

@@ -14,16 +14,16 @@
         query: str,
         filters: Optional[Dict[str, Any]] = None,
         k: int = 4,
         min_score: float = 0.0,
         max_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
         use_colpali: bool = True,
         graph_name: Optional[str] = None,
         hop_depth: int = 1,
         include_paths: bool = False,
         prompt_overrides: Optional[Union[QueryPromptOverrides, Dict[str, Any]]] = None,
         schema: Optional[Union[Type[BaseModel], Dict[str, Any]]] = None,
         llm_config: Optional[Dict[str, Any]] = None,
     ) -> CompletionResponse
     ```
   </Tab>
@@ -33,16 +33,16 @@
         query: str,
         filters: Optional[Dict[str, Any]] = None,
         k: int = 4,
         min_score: float = 0.0,
         max_tokens: Optional[int] = None,
         temperature: Optional[float] = None,
         use_colpali: bool = True,
         graph_name: Optional[str] = None,
         hop_depth: int = 1,
         include_paths: bool = False,
         prompt_overrides: Optional[Union[QueryPromptOverrides, Dict[str, Any]]] = None,
         schema: Optional[Union[Type[BaseModel], Dict[str, Any]]] = None,
         llm_config: Optional[Dict[str, Any]] = None,
     ) -> CompletionResponse
     ```
   </Tab>
@@ -61,7 +61,7 @@
 - `hop_depth` (int, optional): Number of relationship hops to traverse in the graph (1-3). Defaults to 1.
 - `include_paths` (bool, optional): Whether to include relationship paths in the response. Defaults to False.
 - `prompt_overrides` (QueryPromptOverrides | Dict[str, Any], optional): Optional customizations for entity extraction, resolution, and query prompts
 - `schema` (Type[BaseModel] | Dict[str, Any], optional): Optional schema for structured output, can be a Pydantic model or a JSON schema dict
 - `llm_config` (Dict[str, Any], optional): Optional LiteLLM-compatible model configuration (e.g., model name, API key, base URL). Allows overriding the default LLM configuration on a per-query basis. Defaults to None.
 
 ## Metadata Filters
@@ -85,6 +85,23 @@
 )
 ```
 
+You can also filter by folder name and use expressive operators like `$in`, `$regex`, and `$nin`:
+
+```python
+# Query across multiple folders
+filters = {
+    "$and": [
+        {"folder_name": {"$in": ["reports", "invoices"]}},
+        {"year": 2024},
+        {"priority": {"$gte": 50}}
+    ]
+}
+
+response = db.query("What are the key financial highlights?", filters=filters)
+```
+
+For more advanced filtering patterns, see the [Complex Metadata Filtering cookbook](/cookbooks/complex-metadata-filtering).
+
 ## Returns
 
 - `CompletionResponse`: Response containing the completion, source information, and potentially structured output.
@@ -96,7 +113,7 @@
 <Tabs>
   <Tab title="Sync">
     ```python
     from morphik import Morphik
 
     db = Morphik()
 
@@ -115,7 +132,7 @@
   </Tab>
   <Tab title="Async">
     ```python
     from morphik import AsyncMorphik
 
     async with AsyncMorphik() as db:
         response = await db.query(
@@ -138,7 +155,7 @@
 <Tabs>
   <Tab title="Sync">
     ```python
     from morphik import Morphik
 
     db = Morphik()
 
@@ -160,7 +177,7 @@
   </Tab>
   <Tab title="Async">
     ```python
     from morphik import AsyncMorphik
 
     async with AsyncMorphik() as db:
         # Knowledge graph enhanced query
@@ -186,7 +203,7 @@
 <Tabs>
   <Tab title="Sync">
     ```python
     from morphik import Morphik
     from morphik.models import QueryPromptOverride, QueryPromptOverrides
 
     db = Morphik()
@@ -218,7 +235,7 @@
   </Tab>
   <Tab title="Async">
     ```python
     from morphik import AsyncMorphik
     from morphik.models import QueryPromptOverride, EntityExtractionPromptOverride, QueryPromptOverrides
 
     async with AsyncMorphik() as db:
@@ -275,7 +292,7 @@
 <Tabs>
   <Tab title="Sync">
     ```python
     from morphik import Morphik
 
     db = Morphik()
 
@@ -307,7 +324,7 @@
   </Tab>
   <Tab title="Async">
     ```python
     from morphik import AsyncMorphik
 
     async with AsyncMorphik() as db:
         # Use GPT-4 for a specific query
@@ -340,13 +357,13 @@
 
 ### Using Structured Output
 
 Use the `schema` parameter to get the completion response in a structured format according to a Pydantic model or a JSON schema dictionary.
 
 <Tabs>
   <Tab title="Sync">
     ```python
     from morphik import Morphik
     from pydantic import BaseModel
     from typing import List
 
     # Define the desired output structure
@@ -386,8 +403,8 @@
   </Tab>
   <Tab title="Async">
     ```python
     from morphik import AsyncMorphik
     from pydantic import BaseModel
     from typing import List
 
     # Define the desired output structure