Org Chart from JSON Exports

Turn two flat JSON exports of companies and people into a connected org-chart graph, with deterministic node IDs doing the deduplication

You have your org data as plain exports — one JSON file listing companies and their departments, another listing people and where they work — and you want it in memory as a connected graph of companies, departments, and employees, without an LLM re-deriving structure you already know.

What You’ll Build

Two JSON files — companies.json and people.json — are loaded and mapped onto typed DataPoint classes, then written straight into the graph and vector stores by a two-task custom pipeline: no chunking, no extraction, no cognify pass. What comes out is an org chart you can open in a browser: Company nodes linked to their Department nodes, each department linked to the Person nodes that work in it, with every name embedded for semantic search. Node IDs are derived from the data itself, so the same department name reaching the pipeline twice lands on one node rather than two.

The script closes by asking the graph a question, so the same run that builds the org chart also shows it is retrievable.

The complete runnable script is in examples/demos/custom_pipelines/organizational_hierarchy — this page walks through its key moments rather than reproducing it.

Features in Play

• DataPoints — Person, Department, Company, and CompanyType are the node types; index_fields decides what gets embedded and identity_fields derives the deterministic ID that collapses repeats
• Custom Data Models — add_data_points persists the typed objects and their nesting as nodes and edges, with no LLM in the path
• Custom Tasks and Pipelines — two Task objects run by run_tasks against a dataset: one maps JSON to DataPoints, one stores them
• Graph Visualization — the script renders the org chart to an HTML file you can open
• Search — the script finishes with a GRAPH_COMPLETION query run with only_context=True, proving the hand-declared nodes are retrievable like any other memory without pulling an LLM into the demo

How It Looks

This is the graph the script writes, loaded from a real run of it. Drag a node to pull it out of the tangle, scroll to zoom, and hover one to fade out everything it does not touch — hovering a department is the quickest way to see exactly who works in it.

The org chart from a real run: one CompanyType node at the centre, five companies around it, each linked to the departments it declares, and each department to the people in it. Hover a node to list its edges with the text the run stored on each.

Every node and edge here comes from the run’s visualize_graph export, so the shape is exactly what lands in your graph store: Research & Development sits on GreenFuture with no one attached to it, because the company declares the department but no one in people.json works there.

What to Expect

The lines below come from one real run of the script, trimmed. Nothing in this demo calls an LLM, so the node and edge counts are identical on every run — only the UUIDs, timestamps, and paths change. A first run also prints a long block of relational migrations as cognee builds its tables; that block is setup, not part of the demo.

The pipeline starts with both JSON files already in hand. build_lightweight_data_object has wrapped the two files into a single LightweightData DataPoint, so the payload printed at the start of the run is the whole input — five companies and ten people — before any task has touched it.

status='PipelineRunStarted' pipeline_run_id=UUID('40da9a6f-3948-43be-a90f-e551570c40dd') dataset_id=UUID('94add405-52f0-5e30-871b-b2e8eeda31c7') dataset_name='test_dataset' payload=[LightweightData(id=UUID('c22f2fa6-5eee-5a20-a8d5-f3a1d10dbbbd'), ...

The two tasks finish in about three seconds. ingest_files maps the payload and add_data_points writes the result. There is no extraction step between them, which is why the whole pipeline costs less than a single LLM call would.

2026-09-11T15:24:05.784975 [info     ] Function task started: `ingest_files` [run_tasks_base]
2026-09-11T15:24:05.792215 [info     ] Coroutine task started: `add_data_points` [run_tasks_base]
...
2026-09-11T15:24:08.755657 [info     ] Coroutine task completed: `add_data_points` [run_tasks_base]
2026-09-11T15:24:08.762174 [info     ] Function task completed: `ingest_files` [run_tasks_base]
2026-09-11T15:24:08.768537 [info     ] Pipeline run completed: `07f15429-bcc9-56e7-8058-6ff9d3fd6372` [run_tasks_with_telemetry()]

The graph that lands is 27 nodes and 26 edges, and the arithmetic is what tells you the mapping was right. Five Company nodes, eleven Department nodes, ten Person nodes, and the one CompanyType all five companies point at make 27. Eleven company-to-department edges, ten department-to-employee edges, and five is_type edges make 26. Had a department name landed as two nodes, both numbers would be higher.

2026-09-11T15:24:08.791366 [info     ] Retrieved 27 nodes and 26 edges in 0.00 seconds [cognee.shared.logging_utils]
2026-09-11T15:24:08.797151 [info     ] Neighborhood retrieval (2-hop): 27 nodes and 26 edges in 0.01s [cognee.shared.logging_utils]

One warning is expected and does not mean the run failed. add_data_points did embed every index_fields value — the Person_name, Department_name, and Company_name collections are written and searchable. The warning comes from the renderer’s semantic-map layer, which only recognizes cognee’s built-in node types and so has nothing to plot for custom DataPoints. The graph view itself is complete.

2026-09-11T15:24:08.798832 [info     ] fetch_node_embeddings: resolved 0/27 node embeddings across 0 collection(s) [embedding_join]
2026-09-11T15:24:08.798890 [warning  ] fetch_node_embeddings: no embeddings resolved — the semantic map will be empty. Missing collections: none. Unmapped node types: ['Department', 'Company', 'Person', 'CompanyType']. [embedding_join]

The closing search returns the LLM input, not a sentence. It asks “Who works for GreenFuture Solutions?” with only_context=True, so what comes back is the prompt built around the graph neighbourhood the query matched — the company, its departments, and the people connected to them, rendered as text — rather than an LLM’s answer. That is the point: GreenFuture’s departments and employees coming back proves the hand-declared DataPoints are retrievable, and it costs an embedding call instead of a completion. The run above predates the query, so no output from it is shown here.

Before You Start

• Complete Quickstart to understand basic operations
• Ensure you have LLM Providers configured — an embedding provider is all this demo needs. add_data_points embeds every index_fields value, and the closing search embeds the query; nothing in the script calls a completion model
• Run the script from a checkout of the cognee repo: it reads companies.json and people.json from the data/ folder next to it, and writes its HTML render into a sibling .artifacts/ folder
• The script starts with prune.prune_data() and prune.prune_system(metadata=True), which wipes the configured instance — point it at a scratch instance rather than memory you want to keep

How It Works

Stage 1: Model the Org Chart as Deduplicating DataPoints

Source: examples/demos/custom_pipelines/organizational_hierarchy/organizational_hierarchy_pipeline_example.py

class Person(DataPoint):
    name: str
    # "index_fields": fields to embed for vector search
    # "identity_fields": fields used to generate deterministic IDs (deduplication)
    metadata: dict = {"index_fields": ["name"], "identity_fields": ["name"]}


class Department(DataPoint):
    name: str
    employees: list[Person]
    metadata: dict = {"index_fields": ["name"], "identity_fields": ["name"]}

These classes are the entire schema of the resulting graph — Company and CompanyType follow the same pattern below them. Two things happen per class: index_fields names the field that gets embedded, so the graph is searchable by name; identity_fields makes the node’s UUID a deterministic function of that name, so building Person(name="John Doe") twice lands on one node instead of two. The employees field is what makes this a graph rather than two tables — a list of Person objects on a Department becomes edges from that department to those people.

Stage 2: Map the JSON Rows onto Nested DataPoints

Source: examples/demos/custom_pipelines/organizational_hierarchy/organizational_hierarchy_pipeline_example.py

def ingest_files(data: list[Any]) -> list[Company]:
    # With identity_fields, DataPoints with the same name automatically get the same UUID.
    # No manual dict-based deduplication needed — just create instances freely.
    all_companies: list[Company] = []

    # Single CompanyType node shared across all data items (deterministic ID via identity_fields)
    company_type = CompanyType()

    for data_item in data:
        people = data_item.people
        companies = data_item.companies

        # Build departments with their employees
        dept_employees: dict[str, list[Person]] = {}
        for person in people:
            dept_name = person["department"]
            if dept_name not in dept_employees:
                dept_employees[dept_name] = []
            dept_employees[dept_name].append(Person(name=person["name"]))

        departments = {
            name: Department(name=name, employees=employees)
            for name, employees in dept_employees.items()
        }

        for company in companies:
            company_departments = [
                departments.get(dept_name, Department(name=dept_name, employees=[]))
                for dept_name in company["departments"]
            ]
            all_companies.append(
                Company(name=company["name"], departments=company_departments, is_type=company_type)
            )

    return all_companies

This is the first pipeline task, and it is ordinary Python: group people by their department field, build one Department per group, then hang the departments each company declares off a Company. Nothing here checks whether a node already exists. A company that declares a department nobody works in still gets a Department node — created on the spot with no employees — and if another company declares the same one, identity_fields gives both objects the same UUID, so the two collapse into a single shared node when they are stored. The function returns only the companies; the departments and people reach the graph because they hang off them.

Stage 3: Run the Two-Task Pipeline

Source: examples/demos/custom_pipelines/organizational_hierarchy/organizational_hierarchy_pipeline_example.py

    # Run tasks expects a list of data even if it is just one document
    data = [{"companies": companies, "people": people}]

    pipeline = run_tasks(
        [Task(ingest_files), Task(add_data_points)],
        dataset_id=datasets[0].id,
        data=build_lightweight_data_object(data),
        incremental_loading=False,
    )

main() prunes, calls setup() to create the relational tables, resolves the default user, and creates a test_dataset with load_or_create_datasets before this point — the dataset is what the pipeline run is tracked against. run_tasks then chains the two tasks: ingest_files returns Company objects and add_data_points writes them, their nested departments and people, and the edges between them into the graph and vector stores. build_lightweight_data_object wraps the raw dict in a LightweightData DataPoint with a uuid5 ID, because the pipeline expects DataPoints rather than plain dicts. Once the pipeline drains, visualize_graph writes the org chart to .artifacts/organizational_hierarchy_pipeline_example.html.

Stage 4: Query the Graph You Just Built

Source: examples/demos/custom_pipelines/organizational_hierarchy/organizational_hierarchy_pipeline_example.py

    # Ask a question against the graph that was just built. only_context=True
    # returns the prompt the LLM would receive (retrieval context included)
    # instead of an answer, so this example needs only an embedding provider
    # configured - no LLM.
    results = await search(
        query_text="Who works for GreenFuture Solutions?",
        query_type=SearchType.GRAPH_COMPLETION,
        dataset_ids=datasets[0].id,
        user=user,
        only_context=True,
    )

This is what turns the demo from an import into a round trip. Nothing about the query knows the graph was hand-declared rather than extracted by cognify — GRAPH_COMPLETION embeds the question, finds the matching nodes, and walks company → department → employee edges out from them exactly as it would over an LLM-built graph. only_context=True stops there and hands back the prompt instead of sending it to a completion model, which is what keeps the whole script free of completion calls. Passing dataset_ids and user scopes the search to the test_dataset this run created.

search returns a list with one entry per dataset searched. In the default multi-user mode each entry is a dict whose search_result key holds the context; with ENABLE_BACKEND_ACCESS_CONTROL=false each entry is the context string itself. The script’s closing loop reads result.search_result as an attribute, which neither shape has, so as of cognee#5049 the final print raises AttributeError after the graph and render are already written. Until that is fixed upstream, read the entry with result["search_result"] in multi-user mode, or print results directly.

Run It

uv run python examples/demos/custom_pipelines/organizational_hierarchy/organizational_hierarchy_pipeline_example.py

It prints the pipeline statuses walked through above, logs the path of the render it wrote to .artifacts/organizational_hierarchy_pipeline_example.html, next to the script — open that file to see companies linked to departments linked to people — and closes with the “Who works for GreenFuture Solutions?” query. The graph and the render are complete before that query runs, so they are there to inspect even though the script’s final print currently fails as described in Stage 4.

DataPoints

How index_fields, identity_fields, and nested models shape the graph a DataPoint becomes.

Custom Data Models

More on modeling your own node types and storing them with add_data_points.

Custom Tasks and Pipelines

Writing your own tasks and running them as a pipeline, step by step.

Reading the Visualization

What each tab of the rendered org chart shows, and which one to reach for.