> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge graph

> Build a graph, then search and walk it

A graph is built when you ask for one. Ingesting files never commits you to
a build. `knowledge_graph.auto_build` on the workspace chains a build after
every ingestion.

<Tabs>
  <Tab title="Python">
    ```python theme={"dark"}
    from ndi_sdk import NdiClient

    with NdiClient() as client:
        workspace_id = "550e8400-e29b-41d4-a716-446655440001"
        client.jobs.wait(
            client.ingestion.build_knowledge_graph(workspace_id).job_id,
            timeout=1800,
        )
        info = client.tools.kg_info(workspace_id)
        print(info)
        nodes = client.tools.kg_search(workspace_id, query="Acme Holdings", k=5)
        print(nodes)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```ts theme={"dark"}
    import { NdiClient } from "ndi-sdk";

    const client = new NdiClient();
    const workspaceId = "550e8400-e29b-41d4-a716-446655440001";
    await client.jobs.wait((await client.ingestion.buildKnowledgeGraph(workspaceId)).job_id, {
      timeout: 1800,
    });
    const info = await client.tools.kgInfo(workspaceId);
    const nodes = await client.tools.kgSearch(workspaceId, { query: "Acme Holdings", k: 5 });
    console.log(info, nodes);
    ```
  </Tab>

  <Tab title="curl">
    ```bash theme={"dark"}
    curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/knowledge-graph/builds" \
      -H "X-API-Key: $NDI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'

    curl -s "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-info" \
      -H "X-API-Key: $NDI_API_KEY"

    curl -s -X POST "$NDI_BASE_URL/v1/workspaces/$WS/tools/kg-search" \
      -H "X-API-Key: $NDI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"query":"Acme Holdings","k":5}'
    ```
  </Tab>
</Tabs>

## Walk

`kg_walk` follows edges from a start node. Use `kg_search` first to get an id.

```python theme={"dark"}
from ndi_sdk import NdiClient

with NdiClient() as client:
    workspace_id = "550e8400-e29b-41d4-a716-446655440001"
    walk = client.tools.kg_walk(
        workspace_id,
        start_node_ids=["node-acme"],
        hops=2,
    )
    print(walk)
```

## PATCH `knowledge_graph`

`PATCH /v1/workspaces/{id}` replaces the `knowledge_graph` block whole.
Read the current block first and send exclusions back with `auto_build`
changed — sending `auto_build` alone resets `exclude_path_prefixes` and
`exclude_categories` to empty.

See [Workspaces](/concepts/workspaces).