Skip to content
Nodus

Parsing Graph Data

Nodus loads graphs as plain JSON — a RawGraph with a list of nodes and a list of edges. The parse namespace converts common external formats into exactly that shape, and when your data is bespoke you can build the same shape by hand. This guide covers both paths. For the structure itself, see the Graph Model.

The target shape: RawGraph

Everything you pass to setGraph (or addGraph) is a RawGraph:

type RawGraph = {
  nodes: { id?: string | number; attributes?: Record<string, any>; data?: ND }[];
  edges: {
    id?: string | number;
    source: string | number;
    target: string | number;
    attributes?: Record<string, any>;
    data?: ED;
  }[];
};
  • attributes holds visual attributes (x, y, color, radius, shape, text, …).
  • data holds your arbitrary payload, typed via the ND / ED generics.

Both parsing and hand-building aim to produce this shape.

Parsing an external format

Import the parse namespace and call the parser for your format. Parsers return a RawGraph, which you hand straight to setGraph:

import { Nodus, parse } from '@kortexya/nodus';


const nodus = new Nodus({ container: document.getElementById('graph') });


// Read your source text however you like (fetch, file input, bundler import).
const text = await fetch('/data/network.mtx').then((r) => r.text());


// Parse it into the RawGraph shape.
const graph = parse.mtx(text);


// Load, lay out, and frame.
await nodus.setGraph(graph);
await nodus.layouts.force({ duration: 0 });
await nodus.view.locateGraph();

The import → parse → load flow

import { parse } from '@kortexya/nodus';


// 1. Get the source text.
const source = await fetch('/data/graph.mtx').then((r) => r.text());


// 2. Parse → RawGraph.
const raw = parse.mtx(source);


// 3. Inspect or massage it before loading, if you like.
console.log(raw.nodes.length, 'nodes,', raw.edges.length, 'edges');


// 4. Load it.
await nodus.setGraph(raw);

Because the parser hands you an ordinary RawGraph, you can post-process it before loading — attach data, set default attributes, filter nodes — using plain JavaScript.

Building a RawGraph by hand

When your data comes from your own API or database, the most direct path is to map it into the RawGraph shape yourself. Put domain payload under data and anything visual under attributes:

// Your own records.
const people = [
  { uid: 'u1', name: 'Alice', team: 'red' },
  { uid: 'u2', name: 'Bob', team: 'blue' },
  { uid: 'u3', name: 'Carol', team: 'red' },
];
const links = [
  { from: 'u1', to: 'u2' },
  { from: 'u2', to: 'u3' },
];


// Map them into a RawGraph.
const graph = {
  nodes: people.map((p) => ({
    id: p.uid,
    data: { name: p.name, team: p.team },
    attributes: { text: { content: p.name } },
  })),
  edges: links.map((l) => ({
    source: l.from,
    target: l.to,
  })),
};


await nodus.setGraph(graph);
await nodus.layouts.force({ duration: 0 });
await nodus.view.locateGraph();

Read your payload back later with element.getData():

nodus.tools.tooltip.onNodeClick((node) => {
  const { name, team } = node.getData();
  console.log(name, 'is on team', team);
});

Try it live — a graph built from plain records, mapped into the RawGraph shape:

Build a graph from records Open in new tab ↗

Merging instead of replacing

setGraph replaces the whole graph; addGraph merges a RawGraph into the current one. The same parsed or hand-built shape works with either:

const more = parse.mtx(await fetch('/data/extra.mtx').then((r) => r.text()));
await nodus.addGraph(more);

Next

  • Graph Model — the RawGraph shape, attributes vs data, and the element wrappers.
  • Building a Graph — add, update and remove elements after loading.
  • Generating Graphs — synthetic graphs when you don’t have data yet.