🔍 Code Extractor

Retrieves a complete document from Neo4j graph database along with all its related entities including versions, reviews, approvals, and authors.

Purpose

This function performs a comprehensive graph query to fetch a controlled document and all its relationships in a single operation. It's designed for document management systems that need to display complete document information including version history, review cycles, approval workflows, and authorship. The function handles optional relationships gracefully and returns an empty dictionary if the document is not found or an error occurs.

Source Code

def get_document_with_relationships(doc_uid: str) -> Dict[str, Any]:
    """
    Get a complete document with its versions, reviews, and approvals.
    
    Args:
        doc_uid: UID of document to retrieve
        
    Returns:
        Dictionary with document and related data
    """
    try:
        query = """
        MATCH (d:ControlledDocument {UID: $doc_uid})
        OPTIONAL MATCH (d)-[:HAS_VERSION]->(v:DocumentVersion)
        OPTIONAL MATCH (d)-[:CURRENT_VERSION]->(cv:DocumentVersion)
        OPTIONAL MATCH (v)-[:FOR_REVIEW]->(r:ReviewCycle)
        OPTIONAL MATCH (r)-[:FOR_APPROVAL]->(a:Approval)
        OPTIONAL MATCH (v)-[:AUTHORED_BY]->(author:User)
        RETURN d as document, 
               collect(distinct v) as versions,
               cv as current_version,
               collect(distinct r) as reviews,
               collect(distinct a) as approvals,
               collect(distinct author) as authors
        """
        
        driver = get_driver()
        with driver.session() as session:
            result = session.run(query, doc_uid=doc_uid)
            record = result.single()
            
            if not record:
                return {}
                
            # Convert record to dictionary
            document = dict(record["document"].items())
            
            # Process versions
            versions = []
            for v in record["versions"]:
                if v:  # Check if not None
                    versions.append(dict(v.items()))
            document["versions"] = versions
            
            # Add current version
            cv = record["current_version"]
            document["current_version"] = dict(cv.items()) if cv else None
            
            # Process reviews
            reviews = []
            for r in record["reviews"]:
                if r:  # Check if not None
                    reviews.append(dict(r.items()))
            document["reviews"] = reviews
            
            # Process approvals
            approvals = []
            for a in record["approvals"]:
                if a:  # Check if not None
                    approvals.append(dict(a.items()))
            document["approvals"] = approvals
            
            # Process authors
            authors = []
            for author in record["authors"]:
                if author:  # Check if not None
                    authors.append(dict(author.items()))
            document["authors"] = authors
            
            return document
            
    except Exception as e:
        logger.error(f"Error retrieving document with relationships: {e}")
        return {}

Parameters

Parameter Details

doc_uid: Unique identifier (UID) string for the controlled document to retrieve. This should match the UID property of a ControlledDocument node in the Neo4j database. Expected to be a string value, typically a UUID or similar unique identifier.

Return Value

Type: Dict[str, Any]

Returns a dictionary containing the document data and all related entities. The dictionary structure includes: 'document' properties as top-level keys, 'versions' (list of document version dictionaries), 'current_version' (dictionary or None), 'reviews' (list of review cycle dictionaries), 'approvals' (list of approval dictionaries), and 'authors' (list of user dictionaries). Returns an empty dictionary {} if the document is not found or if an error occurs during retrieval.

Dependencies

• neo4j
• logging
• typing
• datetime
• CDocs.db
• CDocs.db.schema_manager

Required Imports

from typing import Dict, Any
import logging
from CDocs.db import get_driver

Usage Example

from typing import Dict, Any
from CDocs.db import get_driver
import logging

# Ensure logger is configured
logger = logging.getLogger(__name__)

# Example usage
doc_uid = "doc-12345-abcde"
result = get_document_with_relationships(doc_uid)

if result:
    print(f"Document Title: {result.get('title')}")
    print(f"Number of versions: {len(result.get('versions', []))}")
    
    current_version = result.get('current_version')
    if current_version:
        print(f"Current version: {current_version.get('version_number')}")
    
    print(f"Number of reviews: {len(result.get('reviews', []))}")
    print(f"Number of approvals: {len(result.get('approvals', []))}")
    print(f"Authors: {[author.get('name') for author in result.get('authors', [])]}")
else:
    print("Document not found or error occurred")

Best Practices

• Always check if the returned dictionary is empty before accessing its contents to handle cases where the document doesn't exist
• The function returns an empty dictionary on errors, so implement proper error handling in calling code
• Ensure the Neo4j driver is properly initialized before calling this function
• Be aware that this function performs multiple OPTIONAL MATCH operations which can be resource-intensive for documents with many relationships
• The function uses collect(distinct ...) which may impact performance on large datasets; consider pagination for production use
• All None values in collections are filtered out during processing, so the returned lists only contain valid entities
• The function assumes a 'logger' variable exists in the module scope for error logging
• Consider implementing caching for frequently accessed documents to reduce database load
• The function closes the Neo4j session automatically using context manager, ensuring proper resource cleanup

Tags

Similar Components

AI-powered semantic similarity - components with related functionality:

• function get_document_v5 75.9% similar

  Retrieves all versions of a controlled document from a Neo4j graph database, including metadata about which version is current.

  From: /tf/active/vicechatdev/CDocs/db/db_operations.py

• function get_document 74.3% similar

  Retrieves comprehensive details of a controlled document by its UID, with optional inclusion of version history, review cycles, and approval cycles.

  From: /tf/active/vicechatdev/document_controller_backup.py

• function get_document_v1 73.5% similar

  Retrieves comprehensive details of a controlled document by its UID, including optional version history, review cycles, and approval workflows.

  From: /tf/active/vicechatdev/CDocs/controllers/document_controller.py

• function get_document_approvals 71.3% similar

  Retrieves all approval cycles associated with a specific document, with optional filtering for active cycles only.

  From: /tf/active/vicechatdev/CDocs/controllers/approval_controller_bis.py

• function get_document_history 71.2% similar

  Retrieves the complete audit history for a document by querying events across document, version, review, comment, and approval nodes in a Neo4j graph database.

  From: /tf/active/vicechatdev/CDocs/utils/audit_trail.py