create_graph

Create a graph from documents

Sync

def create_graph(
    name: str,
    filters: Optional[Dict[str, Any]] = None,
    documents: Optional[List[str]] = None,
    prompt_overrides: Optional[Union[GraphPromptOverrides, Dict[str, Any]]] = None,
    folder_name: Optional[Union[str, List[str]]] = None,
    end_user_id: Optional[str] = None,
) -> Graph

Async

async def create_graph(
    name: str,
    filters: Optional[Dict[str, Any]] = None,
    documents: Optional[List[str]] = None,
    prompt_overrides: Optional[Union[GraphPromptOverrides, Dict[str, Any]]] = None,
    folder_name: Optional[Union[str, List[str]]] = None,
    end_user_id: Optional[str] = None,
) -> Graph

Parameters

• name (str): Name of the graph to create
• filters (Dict[str, Any], optional): Optional metadata filters to determine which documents to include
• documents (List[str], optional): Optional list of specific document IDs to include
• prompt_overrides (GraphPromptOverrides | Dict[str, Any], optional): Optional customizations for entity extraction and resolution prompts
• folder_name (str | List[str], optional): Optional folder scope (canonical path or list of paths/names)
• end_user_id (str, optional): Optional end-user scope

Returns

Calling create_graph now returns a placeholder Graph immediately.

• graph (Graph): Graph stub with system_metadata["status"] = "processing". Entities and relationships will be empty until processing completes.

Use db.wait_for_graph_completion("<name>") (sync) or await db.wait_for_graph_completion("<name>") (async) to block until the graph is done, or poll graph.is_processing / graph.is_completed.

Examples

Sync

from morphik import Morphik

db = Morphik()

# Start graph creation – returns immediately with status "processing"
graph = db.create_graph(
    name="research_graph",
    filters={"category": "research"},
    folder_name="/projects/alpha",
)

# Option 1: Block until finished
graph = db.wait_for_graph_completion("research_graph")

# Option 2: Poll periodically
while graph.is_processing:
    time.sleep(10)
    graph = db.get_graph("research_graph")
print("Entities:", len(graph.entities))

# Create a graph from specific documents
graph = db.create_graph(
    name="custom_graph",
    documents=["doc1", "doc2", "doc3"]
)

# With custom entity extraction examples
from morphik.models import EntityExtractionPromptOverride, EntityExtractionExample, GraphPromptOverrides

# Example with only entity extraction examples
graph = db.create_graph(
    name="medical_graph", 
    filters={"category": "medical"},
    prompt_overrides=GraphPromptOverrides(
        entity_extraction=EntityExtractionPromptOverride(
            examples=[
                EntityExtractionExample(label="Insulin", type="MEDICATION"),
                EntityExtractionExample(label="Diabetes", type="CONDITION")
            ]
        )
    )
)

# Example with custom entity extraction prompt template and examples
graph = db.create_graph(
    name="financial_graph",
    documents=["doc1", "doc2"],
    prompt_overrides=GraphPromptOverrides(
        entity_extraction=EntityExtractionPromptOverride(
            prompt_template="Extract financial entities from the following text:\n\n{content}\n\nFocus on these types of entities:\n{examples}\n\nReturn in JSON format.",
            examples=[
                EntityExtractionExample(label="Apple Inc.", type="COMPANY", properties={"sector": "Technology"}),
                EntityExtractionExample(label="Q3 2024", type="TIME_PERIOD"),
                EntityExtractionExample(label="Revenue Growth", type="METRIC")
            ]
        ),
        entity_resolution=EntityResolutionPromptOverride(
            examples=[
                EntityResolutionExample(
                    canonical="Apple Inc.", 
                    variants=["Apple", "AAPL", "Apple Computer"]
                )
            ]
        )
    )
)

print(f"Created graph with {len(graph.entities)} entities and {len(graph.relationships)} relationships")

Async

from morphik import AsyncMorphik

async with AsyncMorphik() as db:
    # Start graph creation (returns quickly)
    graph = await db.create_graph(
        name="research_graph",
        filters={"category": "research"},
        folder_name="/projects/alpha",
    )

    # Wait for completion
    graph = await db.wait_for_graph_completion("research_graph")

    print("Entities:", len(graph.entities))

    # Create a graph from documents with category="research"
    graph = await db.create_graph(
        name="research_graph",
        filters={"category": "research"}
    )
    
    # Create a graph from specific documents
    graph = await db.create_graph(
        name="custom_graph",
        documents=["doc1", "doc2", "doc3"]
    )
    
    # With custom entity extraction examples
    from morphik.models import EntityExtractionPromptOverride, EntityExtractionExample, GraphPromptOverrides
    
    # Example with only entity extraction examples
    graph = await db.create_graph(
        name="medical_graph", 
        filters={"category": "medical"},
        prompt_overrides=GraphPromptOverrides(
            entity_extraction=EntityExtractionPromptOverride(
                examples=[
                    EntityExtractionExample(label="Insulin", type="MEDICATION"),
                    EntityExtractionExample(label="Diabetes", type="CONDITION")
                ]
            )
        )
    )
    
    # Example with custom entity extraction prompt template and examples
    graph = await db.create_graph(
        name="financial_graph",
        documents=["doc1", "doc2"],
        prompt_overrides=GraphPromptOverrides(
            entity_extraction=EntityExtractionPromptOverride(
                prompt_template="Extract financial entities from the following text:\n\n{content}\n\nFocus on these types of entities:\n{examples}\n\nReturn in JSON format.",
                examples=[
                    EntityExtractionExample(label="Apple Inc.", type="COMPANY", properties={"sector": "Technology"}),
                    EntityExtractionExample(label="Q3 2024", type="TIME_PERIOD"),
                    EntityExtractionExample(label="Revenue Growth", type="METRIC")
                ]
            ),
            entity_resolution=EntityResolutionPromptOverride(
                examples=[
                    EntityResolutionExample(
                        canonical="Apple Inc.", 
                        variants=["Apple", "AAPL", "Apple Computer"]
                    )
                ]
            )
        )
    )
    
    print(f"Created graph with {len(graph.entities)} entities and {len(graph.relationships)} relationships")

Graph Properties

The returned Graph object has the following properties:

• id (str): Unique graph identifier
• name (str): Graph name
• entities (List[Entity]): List of entities in the graph
• relationships (List[Relationship]): List of relationships in the graph
• metadata (Dict[str, Any]): Graph metadata
• document_ids (List[str]): Source document IDs
• filters (Dict[str, Any], optional): Document filters used to create the graph
• created_at (datetime): Creation timestamp
• updated_at (datetime): Last update timestamp
• owner (Dict[str, str]): Graph owner information
• folder_path (Optional[str]): Canonical folder path for the graph (if scoped)