search_documents

Search for documents by name or filename

Sync

def search_documents(
    query: str,
    limit: int = 10,
    filters: Optional[Dict[str, Any]] = None,
    folder_name: Optional[Union[str, List[str]]] = None,
    folder_depth: Optional[int] = None,
    end_user_id: Optional[str] = None,
) -> List[Document]

Async

async def search_documents(
    query: str,
    limit: int = 10,
    filters: Optional[Dict[str, Any]] = None,
    folder_name: Optional[Union[str, List[str]]] = None,
    folder_depth: Optional[int] = None,
    end_user_id: Optional[str] = None,
) -> List[Document]

Parameters

• query (str): Search query for document names/filenames
• limit (int, optional): Maximum number of documents to return. Defaults to 10.
• filters (Dict[str, Any], optional): Optional metadata filters
• folder_name (str | List[str], optional): Optional folder scope (canonical path or list of paths/names)
• folder_depth (int, optional): Folder scope depth. None/0 = exact match, -1 = include all descendants, n > 0 = include descendants up to n levels deep.
• end_user_id (str, optional): Optional end-user scope

Returns

• List[Document]: List of matching documents

Metadata Filters

Filters follow the same JSON syntax across the API. See the Metadata Filtering guide for supported operators and typed comparisons. Example:

filters = {
    "$and": [
        {"department": {"$eq": "research"}},
        {"priority": {"$gte": 40}},
    ]
}

docs = db.search_documents("report", filters=filters)

Examples

Sync

from morphik import Morphik

db = Morphik()

# Basic document name search
docs = db.search_documents("quarterly report")
for doc in docs:
    print(f"{doc.external_id}: {doc.filename}")

# Search with limit and filters
docs = db.search_documents(
    query="invoice",
    limit=20,
    filters={"department": "finance"},
)

# Search within specific folders
docs = db.search_documents(
    query="contract",
    folder_name="/projects/legal",
    folder_depth=-1,
)

# Search scoped to an end user
docs = db.search_documents(
    query="notes",
    end_user_id="user_456",
)

Async

from morphik import AsyncMorphik

async with AsyncMorphik() as db:
    # Basic document name search
    docs = await db.search_documents("quarterly report")
    for doc in docs:
        print(f"{doc.external_id}: {doc.filename}")

    # Search with limit and filters
    docs = await db.search_documents(
        query="invoice",
        limit=20,
        filters={"department": "finance"},
    )

    # Search within specific folders
    docs = await db.search_documents(
        query="contract",
        folder_name="/projects/legal",
        folder_depth=-1,
    )

    # Search scoped to an end user
    docs = await db.search_documents(
        query="notes",
        end_user_id="user_456",
    )

Notes

• This method searches document names and filenames, not document content. For content-based search, use retrieve_chunks or retrieve_docs.
• The folder_name parameter accepts a canonical path (leading slash optional) or a list of paths/names; combine with folder_depth to include descendants.
• Results are returned sorted by relevance to the search query.