Skip to content

graphistry/graphistry-js

Repository files navigation


Latest docs npm npm GitHub

CI main Security audit CI docs

Twitter Follow


GraphistryJS

Web libraries for uploading and embedding graph visualizations

Dev guide for contributors: DEVELOP.md



Graphistry - Visual Graph Intelligence

GPU and AI acceleration for interactive visualization of large graphs. Used accross multiple industries for security, fraud, supply chain, social media analysis and more. Graphistry supports live explorations of large datasets by running server side GPUs to stream into a custom WebGL rendering engine. This enables graph metrics and dynamic layout of up to 8MM nodes and edges at a time, most older client GPUs smoothly support somewhere between 100K and 1MM elements.

You can



JavaScript clients: Vanilla JS, React, & Node

@graphistry/client-api

Pure JavaScript API for manipulating Graphistry visualizations in the browser with async-friendly APIs

npm install '@graphistry/client-api'
import { graphistryJS } from "@graphistry/client-api"; // + variants for different bundling formats
const g = graphistryJS(elt);

See @graphistry/client-api project and interactive storybook docs



@graphistry/client-api-react

React component for manipulating Graphistry visualizations in the browser

npm install '@graphistry/client-api-react'
import { Graphistry } from '@graphistry/client-api-react';` // + variants for different bundling formats
<Graphistry dataset="myDatasetID" />

See @graphistry/client-api-react project, interactive storybook docs, and Create React App project sample



@graphistry/node-api

@graphistry/node-api: Node.js bindings, including optional Typescript support, for creating visualizations and generating URLs

npm install '@graphistry/node-api'
import { Client, Dataset, EdgeFile, NodeFile } from "@graphistry/node-api";
const client = new Client(user, pass);
const ds = new Dataset(bindings, new EdgeFile(edges));
await ds.upload(client);

See @graphistry/node-api project and API docs & examples



Graphistry's Architecture

You can think of Graphistry as a live data version of Google Maps.

Clientside (client-api & client-api-react):

  • Graphistry runs as an embedded iframe that streams live with your Graphistry server
  • GraphistryJS runs as a lightweight JavaScript library in your application. It simplifies creating the iframe, uploading data for visualization as needed, and sending the iframe messages to control style and interactions
  • GraphistryJS can be used to upload and view new visualizations, or run sessions for existing uploads, including those from other clients
  • User and GraphistryJS interactions will transparently leverage the Graphistry server as needed, such as for loading a graph, running analytics, drilling into data, and saving settings

Serverside (node-api):

  • GraphistryJS can be used to upload new files and stitch them into graph datasets
  • The resulting server item IDs can be sent to browsers for embedding either as iframe URLs or GraphistryJS IDs, or additional server-side manipulations

Decoupling uploads from downloads

To support server-acceleration and fast interactions, Graphistry decouples uploads from downloads

Uploads:

  • Multiple upload formats are possible, but we recommend parquet & arrow for the best performance and high reliability
  • Uploads are possible from browser clients (CSP/CORS support), but we generally recommend server<>server communications for better speed
  • Different datasets may reuse the same file. Datasets are generally just a small amount of metadata, so for best performance, try to upload new datasets for existing files, instead of reuploading the files as well.

Downloads:

  • Client sessions connect to previously uploaded datasets and their files
  • Client session configurations can override settings initially defined during the upload phase

Security

  • You can configure your Graphistry server to run as http, https, or both
  • Uploads require authentication
    • The node-api client already uses the new JWT-based protocol ("API 3")
    • Deprecated: The clientside JavaScript convenience APIs still use the deprecrated "API 1" protocol (key-based), which lacks JWT-based authentication and authorization
      • We recommend clients instead use fetch or other HTTP callers to directly invoke the REST API: See how the node-api performs it
      • The client JavaScript APIs will updated to the new JWT method alongside recent CORS and SSO updates; contact staff if you desire assistance
  • Sessions are based on unguessable web keys: sharing a secret ID means sharing read access
  • Datasets are immutable and thus their integrity is safe for sharing, while session state (e.g., filters) are writable: share a copy when in doubt