@graphty/graphty-element / session / SessionDataApi
Interface: SessionDataApi ​
Defined in: graphty-element/src/session/types.ts:717
Reading the graph.
Every verb here is synchronous, because every verb here is either an O(1) lookup or a walk whose answer is cached against the snapshot it was computed from, except nodes and edges, which list every record and walk the graph to do it, and neighbors, which walks one node's adjacency. Reads stay synchronous up to the element's load limits; a read that may need more later gets an ...Async twin. Finding by text is session.find, synchronous too: it reads an index built once per revision.
Properties ​
store ​
readonlystore:SessionGraphStore
Defined in: graphty-element/src/session/types.ts:719
The store this session reads, read-only: its snapshot is the one snapshot returns.
Methods ​
addEdges() ​
addEdges(
records):Promise<void>
Defined in: graphty-element/src/session/types.ts:925
Add edge records, as one undoable step. Endpoints are read through the configured edge id paths, the repeated-edge policy applies, and each edge is given an id.
Parameters ​
records ​
readonly Readonly<Record<string, unknown>>[]
The records.
Returns ​
Promise<void>
Settles once the edges are in the graph and drawn.
addNodes() ​
addNodes(
records):Promise<void>
Defined in: graphty-element/src/session/types.ts:918
Add node records, as one undoable step. A record's id is read through data.knownFields.nodeIdPath; a record whose id the graph already holds is skipped.
Parameters ​
records ​
readonly Readonly<Record<string, unknown>>[]
The records.
Returns ​
Promise<void>
Settles once the nodes are in the graph and drawn.
attributes() ​
attributes(): readonly
AttributeDescriptor[]
Defined in: graphty-element/src/session/types.ts:861
Every attribute the graph's records carry, with its type, what it measures, how complete it is and a few sample values. Walked once per revision and cached.
Returns ​
readonly AttributeDescriptor[]
the descriptors, node attributes first, each kind in first-seen order
clear() ​
clear():
Promise<void>
Defined in: graphty-element/src/session/types.ts:956
Remove every node, edge, record and graph-level value, as one undoable step.
Returns ​
Promise<void>
Settles once the graph and the picture are empty.
declare() ​
declare(
column,declaration):Promise<void>
Defined in: graphty-element/src/session/types.ts:881
Say what a column measures, as one undoable step in the "attributes" project slice.
The element infers strings and booleans as categorical and numbers as quantitative, so a column of number codes (department 1 to 14) is drawn as a ramp until it is declared categorical. A declaration affects layers created afterwards: a layer that already exists keeps the binding it stored.
const department = session.data.attributes().find((a) => a.kind === "node" && a.name === "department")!;
await session.data.declare(department, { measurement: "categorical" });
await session.data.declare({ kind: "node", name: "risk" }, { measurement: "ordinal", order: ["low", "high"] });Parameters ​
column ​
the column; an attribute descriptor can be passed as it is
declaration ​
what it measures; an ordinal column lists its values, lowest first
Returns ​
Promise<void>
settles once the step is recorded
Throws ​
A GraphtyError with E_UNKNOWN_ATTRIBUTE (with details.candidates) for a column no record carries, and E_BAD_COMMAND for a declaration that is not one.
edge() ​
edge(
id):EdgeRecord|undefined
Defined in: graphty-element/src/session/types.ts:758
One edge, by the element-assigned edge id.
Parameters ​
id ​
string
the edge id
Returns ​
EdgeRecord | undefined
the record, or undefined when the graph has no such edge
edgePage() ​
Call Signature ​
edgePage(
options):RecordPage<EdgeRecord> &object
Defined in: graphty-element/src/session/types.ts:796
One page of edge records, without reading the rest: nodePage, for edges, and optionally only the edges at one node.
Parameters ​
options ​
EdgePageOptions & object
the window, the scope, the order and the node; every field optional
Returns ​
RecordPage<EdgeRecord> & object
the page, with the total and the revision it was read at
Throws ​
A GraphtyError with E_OPTION_RANGE when offset or limit is not a whole number of zero or more; E_UNKNOWN_RUN for a column or sort naming a run this session does not hold; E_UNKNOWN_ATTRIBUTE for a field the run does not publish; E_BAD_COMMAND for a field that has no value per record of this kind.
Call Signature ​
edgePage(
options?):RecordPage<EdgeRecord>
Defined in: graphty-element/src/session/types.ts:799
Parameters ​
options? ​
Returns ​
edges() ​
edges(): readonly
EdgeRecord[]
Defined in: graphty-element/src/session/types.ts:770
Every edge, in the graph's order: the records edge reads one at a time. Walks the whole graph on every call, so read it when the graph changes, not every frame.
Returns ​
readonly EdgeRecord[]
the records, deep-frozen
fingerprint() ​
fingerprint():
string
Defined in: graphty-element/src/session/types.ts:911
A stable identity for the graph's topology: equal fingerprints mean the same node ids in the same order with the same arcs between them. Attributes and coordinates are not in it.
Returns ​
string
the fingerprint
histogram() ​
histogram(
column,options?):ColumnHistogram
Defined in: graphty-element/src/session/types.ts:900
How a data column's values are distributed, for a chart of one attribute. A quantitative column comes back binned (kind: "numeric", the Histogram shape a run's field has), any other column counted by value, commonest first (kind: "categorical"). Elements with no value in the column are not counted. Walks the column on every call.
const age = session.data.histogram({ kind: "node", name: "age" });
if (age.kind === "numeric") drawBars(age.bins);
else drawBars(age.values, age.otherCount);Parameters ​
column ​
the column; an attribute descriptor can be passed as it is
options? ​
bins: how many bars, or how many values a categorical column lists (20 by default, 1 to 100); scale: a numeric column's axis, as RunResult.histogram takes it
Returns ​
the distribution
Throws ​
A GraphtyError with E_UNKNOWN_ATTRIBUTE (with details.candidates) for a column no record carries, and E_OPTION_RANGE for a bin count outside 1 to 100.
import() ​
import(
source,options?):Promise<void>
Defined in: graphty-element/src/session/types.ts:974
Load a file, a URL or inline text through a registered data source, as one undoable step. It waits its turn behind loads and layouts already asked for. What was loaded, and from where, is kept: lastImport() and source() report it, and undo and redo never read the source again.
Without a type, the format is detected the way loadFromUrl and loadFromFile detect it: from the file name or the URL's extension, then from the first bytes, fetching the URL once when its name says nothing. A format nothing recognises rejects with E_UNKNOWN_FORMAT, naming the formats this element reads.
Parameters ​
source ​
The data source's name, or none to detect it, and its options: inline data, a url or a file.
options? ​
Whether to replace the graph (the default) or add to it, and the column roles and other choices LoadDraft.load takes. Equal to prepare, load, dispose.
Returns ​
Promise<void>
Settles once the last chunk is in the graph; rejects, recording nothing, when the load fails.
lastImport() ​
lastImport():
LoadReport|null
Defined in: graphty-element/src/session/types.ts:833
What the last load did: which endpoint spelling the element resolved, how many repeated edges it saw and what the policy did with them, and how many edges the graph actually holds.
A door as well as the two load events, because those are fire-and-forget: a consumer that subscribed after the load has no other way to ask.
Returns ​
LoadReport | null
the report, or null when nothing has been loaded into this graph
name() ​
name(
id):string|undefined
Defined in: graphty-element/src/session/types.ts:752
What a node is called: the value of its label column (data.knownFields.nodeLabelPath) as text, else its id as text. The same name neighbors gives each neighbor and a result summary gives each element, so a header and a list never disagree. Untrusted text from the data: render it as text, never as markup.
const title = session.data.name(nodeId) ?? String(nodeId); // "Javert"Parameters ​
id ​
NodeId
the node id, compared without coercion
Returns ​
string | undefined
the name, or undefined when the graph has no such node
neighbors() ​
neighbors(
id,options?):NeighborPage
Defined in: graphty-element/src/session/types.ts:824
Each distinct neighbor of a node once, with the combined weight of the edges between them.
A neighbor is exactly a node selection.apply({ neighborsOf: [id], direction }) selects, other than id itself: a self-loop never makes a node its own neighbor, and A->B with B->A under "all" is one neighbor with edgeCount 2. total counts neighbors, not edges. One walk of the node's adjacency, the order cached per revision.
Parameters ​
id ​
NodeId
the node
options? ​
the direction, the weight, the scope, the order and the window
Returns ​
the page, with what it measured and the revision it was read at
Throws ​
A GraphtyError with E_UNKNOWN_ELEMENT (details: { kind: "node", id }) for an id the graph does not hold, E_UNKNOWN_ATTRIBUTE for a weight column no edge carries, and E_OPTION_RANGE for a bad offset or limit.
node() ​
node(
id):NodeRecord|undefined
Defined in: graphty-element/src/session/types.ts:739
One node, by id.
Parameters ​
id ​
NodeId
the node id, compared without coercion: 1 and "1" are two different nodes
Returns ​
NodeRecord | undefined
the record, or undefined when the graph has no such node
nodePage() ​
Call Signature ​
nodePage(
options):RecordPage<NodeRecord> &object
Defined in: graphty-element/src/session/types.ts:782
One page of node records, without reading the rest: what a table showing a few rows of a large graph reads. The order is computed once per revision, scope and sort and then reused, so scrolling through the pages of one order costs only the records on each page.
Parameters ​
options ​
RecordPageOptions & object
the window, the scope and the order; every field optional
Returns ​
RecordPage<NodeRecord> & object
the page, with the total and the revision it was read at
Throws ​
A GraphtyError with E_OPTION_RANGE when offset or limit is not a whole number of zero or more; E_UNKNOWN_RUN for a column or sort naming a run this session does not hold; E_UNKNOWN_ATTRIBUTE for a field the run does not publish; E_BAD_COMMAND for a field that has no value per record of this kind.
Call Signature ​
nodePage(
options?):RecordPage<NodeRecord>
Defined in: graphty-element/src/session/types.ts:785
Parameters ​
options? ​
Returns ​
nodes() ​
nodes(): readonly
NodeRecord[]
Defined in: graphty-element/src/session/types.ts:764
Every node, in the graph's order: the records node reads one at a time. Walks the whole graph on every call, so read it when the graph changes, not every frame.
Returns ​
readonly NodeRecord[]
the records, deep-frozen
prepare() ​
prepare(
source,options?):Promise<LoadDraft>
Defined in: graphty-element/src/session/types.ts:986
Read a source once and hold its rows, so its tables, columns and the counts a load would produce can be read, and the column roles changed, before anything is added to the graph. Nothing is loaded and history is untouched until draft.load(). A source import would refuse to read is refused here with the same code (E_UNKNOWN_FORMAT, E_PARSE_FAILED, E_FETCH_FAILED). A new prepare, and any load, disposes the draft before it.
Parameters ​
source ​
What import takes.
options? ​
How to read it.
signal? ​
AbortSignal
Abandons the read.
Returns ​
Promise<LoadDraft>
The draft.
removeEdges() ​
removeEdges(
ids):Promise<void>
Defined in: graphty-element/src/session/types.ts:951
Remove edges, as one undoable step.
Parameters ​
ids ​
readonly string[]
The element-assigned edge ids; one the graph does not hold is skipped.
Returns ​
Promise<void>
Settles once they are gone from the graph and the picture.
removeNodes() ​
removeNodes(
ids):Promise<void>
Defined in: graphty-element/src/session/types.ts:945
Remove nodes, and every edge attached to one, as one undoable step. Undo puts them back at the rows they held, with their records, weights and edge ids.
Parameters ​
ids ​
readonly NodeId[]
The node ids; one the graph does not hold is skipped.
Returns ​
Promise<void>
Settles once they are gone from the graph and the picture.
renameSource() ​
renameSource(
name):Promise<void>
Defined in: graphty-element/src/session/types.ts:855
Give the source the graph was loaded from a new name, as one undoable step: what source reports as name from then on. The name is saved with the project, and undo restores the old one.
await session.data.renameSource("Les Miserables characters");
session.data.source()?.name; // "Les Miserables characters"Parameters ​
name ​
string
the new name; not empty
Returns ​
Promise<void>
settles once the step is recorded
Throws ​
A GraphtyError with E_BAD_COMMAND (details.reason "no-source") when no source is loaded, and ("empty-name") for an empty name.
resultColumns() ​
resultColumns(
kind): readonlyResultColumnDescriptor[]
Defined in: graphty-element/src/session/types.ts:809
The runs whose result a node or an edge page can show as a column with no field named: every run, in the session's order, whose primary field holds one value per record of that kind. Exactly the runs nodePage({ columns: [run] }) or edgePage(...) accepts, so a table offers its result columns without trying each run. A run still computing is listed; its column comes back pending.
Parameters ​
kind ​
"node" | "edge"
"node" for nodePage, "edge" for edgePage
Returns ​
readonly ResultColumnDescriptor[]
one entry per run, in the order session.runs.list() returns them
snapshot() ​
snapshot():
GraphSnapshot
Defined in: graphty-element/src/session/types.ts:727
The current snapshot. Its structure, id map and attribute columns are the graph's own, shared rather than copied; its position and graphty.pinned columns are copies taken now, because the graph's own are written by the layout every frame and a write into them would place nodes without a step. Place and pin through session.positions.
Returns ​
the sealed graph-format snapshot
source() ​
source():
DataSourceDescriptor|null
Defined in: graphty-element/src/session/types.ts:840
Where the graph was loaded from: the format, the name the reader knows the data by, the URL, and the file's size. It follows undo and redo like the graph does, so a top bar that names the dataset reads it again after either.
Returns ​
DataSourceDescriptor | null
the source, or null when the graph was not loaded by an import, or was cleared
statistics() ​
statistics():
GraphStatistics
Defined in: graphty-element/src/session/types.ts:905
The graph's shape. Walked once per snapshot and cached.
Returns ​
the statistics
undirected() ​
undirected(
snapshot?):DerivedGraph
Defined in: graphty-element/src/session/types.ts:733
The undirected view of the current snapshot, or of one handed in.
Parameters ​
snapshot? ​
the snapshot to derive from; the current one by default
Returns ​
the derived graph, including the edge remap an edge result needs
updateEdges() ​
updateEdges(
rows):Promise<void>
Defined in: graphty-element/src/session/types.ts:938
Change some attributes of existing edges, as one undoable step.
Parameters ​
rows ​
readonly RowUpdate<string>[]
The new values, per edge id.
Returns ​
Promise<void>
Settles once the change is drawn.
updateNodes() ​
updateNodes(
rows):Promise<void>
Defined in: graphty-element/src/session/types.ts:932
Change some attributes of existing nodes, as one undoable step. Keys not named are kept; an id the graph does not hold is skipped.
Parameters ​
rows ​
readonly RowUpdate<NodeId>[]
The new values, per node.
Returns ​
Promise<void>
Settles once the change is drawn.