@graphistry/node-api

Version:

Graphistry API client for use with node.js

github.com/graphistry/graphistry-js

graphistry/graphistry-js

109 lines (94 loc) • 41.3 kB

HTML

<!DOCTYPE html><html class="default"><head><meta charSet="utf-8"/><meta http-equiv="x-ua-compatible" content="IE=edge"/><title>@graphistry/node-api - v5.0.2</title><meta name="description" content="Documentation for @graphistry/node-api - v5.0.2"/><meta name="viewport" content="width=device-width, initial-scale=1"/><link rel="stylesheet" href="assets/style.css"/><link rel="stylesheet" href="assets/highlight.css"/><script async src="assets/search.js" id="search-script"></script></head><body><script>document.body.classList.add(localStorage.getItem("tsd-theme") || "os")</script><header><div class="tsd-page-toolbar"><div class="container"><div class="table-wrap"><div class="table-cell" id="tsd-search" data-base="."><div class="field"><label for="tsd-search-field" class="tsd-widget search no-caption">Search</label><input type="text" id="tsd-search-field"/></div><ul class="results"><li class="state loading">Preparing search index...</li><li class="state failure">The search index is not available</li></ul><a href="index.html" class="title">@graphistry/node-api - v5.0.2</a></div><div class="table-cell" id="tsd-widgets"><div id="tsd-filter"><a href="#" class="tsd-widget options no-caption" data-toggle="options">Options</a><div class="tsd-filter-group"><div class="tsd-select" id="tsd-filter-visibility">All<ul class="tsd-select-list"><li data-value="public">Public</li><li data-value="protected">Public/Protected</li><li data-value="private" class="selected">All</li></ul></div> <input type="checkbox" id="tsd-filter-inherited" checked/><label class="tsd-widget" for="tsd-filter-inherited">Inherited</label><input type="checkbox" id="tsd-filter-externals" checked/><label class="tsd-widget" for="tsd-filter-externals">Externals</label></div></div><a href="#" class="tsd-widget menu no-caption" data-toggle="menu">Menu</a></div></div></div></div><div class="tsd-page-title"><div class="container"><h1>@graphistry/node-api - v5.0.2 </h1></div></div></header><div class="container container-main"><div class="row"><div class="col-8 col-content"><div class="tsd-panel tsd-typography"> <a href="#graphistrynode-api-graphistry39s-nodejs-client-api" id="graphistrynode-api-graphistry39s-nodejs-client-api" style="color: inherit; text-decoration: none;"> <h1><code>@graphistry/node-api</code>: Graphistry's Node.js client API</h1> </a> <a href="#automatically-upload-and-visualize-datasets-using-node-powered-by-graphistry39s-gpu-graph-visualization-infrastructure" id="automatically-upload-and-visualize-datasets-using-node-powered-by-graphistry39s-gpu-graph-visualization-infrastructure" style="color: inherit; text-decoration: none;"> <h2>Automatically upload and visualize datasets using node, powered by Graphistry's GPU graph visualization infrastructure</h2> </a> <a href="#install" id="install" style="color: inherit; text-decoration: none;"> <h3>Install</h3> </a> <code>npm install @graphistry/node-api</code> <a href="#standard-native-esm-imports" id="standard-native-esm-imports" style="color: inherit; text-decoration: none;"> <h3>Standard native <code>esm</code> imports</h3> </a> <pre><code class="language-javascript">import { EdgeFile, NodeFile, Dataset, Client } from '@graphistry/node-api'; </code></pre> Still transitioning to <code>esm</code>? <ul> <li>You may need <code>"type": "module"</code> in your <code>package.json</code></li> <li>Transpiling should preserve esm import syntax. Ex: <code>"babel": { "presets": [ ["@babel/preset-env", {"modules": false}] ] }</code></li> </ul> The <a href="https://github.com/graphistry/graphistry-js/tree/master/projects/node-api">node-api-test sample project</a> shares an example of a native node project. Please contact the team for additional format support. <a href="#usage" id="usage" style="color: inherit; text-decoration: none;"> <h3>Usage</h3> </a> <a href="#the-many-options" id="the-many-options" style="color: inherit; text-decoration: none;"> <h4>The many options</h4> </a> The API is split between the client wrapper and the JSON configuration payloads: <ul> <li><a href="https://graphistry.github.io/graphistry-js/node-tsdocs/"><code>@graphistry/node-api</code> API docs</a>: Overall Node.js client llibrary</li> <li><a href="https://hub.graphistry.com/docs/api/">Graphistry REST API docs</a>: JSON payload options around configuring file formats and visualization settings</li> </ul> <a href="#ex-javascript-with-asyncawait" id="ex-javascript-with-asyncawait" style="color: inherit; text-decoration: none;"> <h4>Ex: JavaScript with async/await</h4> </a> <pre><code class="language-javascript">import { EdgeFile, NodeFile, Dataset, Client } from '@graphistry/node-api'; //defaults: 'https', 'hub.graphistry.com', 'https://hub.graphistry.com' const client = new Client('my_username', 'my_password'); //columnar data is fastest; column per attribute; reuse across datasets const edgesFile = new EdgeFile({'s': ['a1', 'b2'], 'd': ['b2', 'c3']}); const nodesFile = new NodeFile({'n': ['a1', 'b2', 'c3'], 'a1': ['x', 'y', 'z']}); const dataset = new Dataset({ node_encodings: { bindings: { node: 'n' } }, edge_encodings: { bindings: { source: 's', destination: 'd' } }, metadata: {}, name: 'testdata', }, edgesFile, nodesFile); await dataset.upload(client); console.info(`View at ${dataset.datasetID} at ${dataset.datasetURL}`); </code></pre> <a href="#ex-typescript-with-asyncawait" id="ex-typescript-with-asyncawait" style="color: inherit; text-decoration: none;"> <h3>Ex: TypeScript with async/await</h3> </a> Exactly the same! <a href="#ex-using-promises" id="ex-using-promises" style="color: inherit; text-decoration: none;"> <h3>Ex: Using promises</h3> </a> <pre><code class="language-javascript">import { EdgeFile, NodeFile, Dataset, Client } from '@graphistry/node-api'; //defaults: 'https', 'hub.graphistry.com', 'https://hub.graphistry.com' const client = new Client(user, password); //columnar data is fastest; column per attribute; reuse across datasets const edgesFile = new EdgeFile({'s': ['a1', 'b2'], 'd': ['b2', 'c3']}); const nodesFile = new NodeFile({'n': ['a1', 'b2', 'c3'], 'a1': ['x', 'y', 'z']}); (new Dataset({ node_encodings: { bindings: { node: 'n' } }, edge_encodings: { bindings: { source: 's', destination: 'd' } }, metadata: {}, name: 'testdata', }, edgesFile, nodesFile)) .upload(client) .then(dataset => { console.info(`View at ${dataset.datasetID} at ${dataset.datasetURL}`); }) .catch(err => { console.error('Oops', err); }) </code></pre> <a href="#ex-apache-arrow-uploads" id="ex-apache-arrow-uploads" style="color: inherit; text-decoration: none;"> <h3>Ex: Apache Arrow uploads</h3> </a> We recommend uploading <a href="https://arrow.apache.org/docs/dev/index.html">Apache Arrow</a> format data in most scenarios due to the speed and reliability guarantees: <pre><code class="language-javascript">import { tableFromArrays, tableToIPC, Table } from 'apache-arrow'; import { EdgeFile } from '@graphistry/node-api'; //columnar data is fastest; column per attribute; reuse across datasets const edgesJSON = {'s': ['a1', 'b2'], 'd': ['b2', 'c3']}; const edgesTable: Table = tableFromArrays(edgesJSON); const edgesUint8: Uint8Array = tableToIPC(edgesArr, 'file'); const edgesFile = new EdgeFile(edgesUint8, 'arrow'); </code></pre> <a href="#ex-using-an-organization" id="ex-using-an-organization" style="color: inherit; text-decoration: none;"> <h3>Ex: Using an organization</h3> </a> You can log into an organization instead of a personal account <pre><code class="language-javascript">import { Client } from '@graphistry/node-api'; const c = new Client('my_user', 'my_pass', 'my_org'); </code></pre> <a href="#ex-custom-token" id="ex-custom-token" style="color: inherit; text-decoration: none;"> <h3>Ex: Custom token</h3> </a> If you already have a JWT token, you can pass it in <pre><code class="language-javascript">import { Client } from '@graphistry/node-api'; const c = new Client(); c.setToken('Bearer 123abc'); </code></pre> <a href="#ex-custom-server" id="ex-custom-server" style="color: inherit; text-decoration: none;"> <h3>Ex: Custom server</h3> </a> You can switch which server to use for uploads and for downloads, which is useful for self-hosted servers and advanced enterprise network configurations <pre><code class="language-javascript">import { Client } from '@graphistry/node-api'; const c = new Client( 'my_user', 'my_pass', 'optional_my_org', 'https', //upload protcol 'hub.graphistry.com', //upload server 'https://hub.graphistry.com' //url to use in browsers ) </code></pre> <a href="#using-api-options" id="using-api-options" style="color: inherit; text-decoration: none;"> <h3>Using API Options</h3> </a> <ul> <li>Set parsing options for different <code>File</code> formats and shapes </li> <li>Configure <code>Dataset</code> nodes & edges to use data-driven colors, sizes, icons, and badges using simple and complex encodings, including both continuous and categorical mappings </li> <li>Theme with custom branding around background & foreground colors, images, logos, titles, and more </li> </ul> <pre><code class="language-javascript">const client = new Client(user, password, org, protocol, host); // Row-oriented data slower to upload but often convenient const edgesRows = [ { 's': 'a', 'd': 'b', 'v': 'e1' }, { 's': 'b', 'd': 'c', 'v': 'e2' }, { 's': 'c', 'd': 'a', 'v': 'e3' } ]; const nodesRows = [ { 'n': 'a', 'vv': 10, 't': 'person' }, { 'n': 'b', 'vv': 20, 't': 'person' }, { 'n': 'c', 'vv': 30 , 't': 'car' } ]; const edgesFile = new EdgeFile( edgesRows, 'json', 'my_edges', // Also: file_compression, sql_transforms, ... // https://hub.graphistry.com/docs/api/2/rest/files/ { // JSON parsing options: // - https://hub.graphistry.com/docs/api/2/rest/upload/data/#uploadjson2 // - https://pandas.pydata.org/docs/reference/api/pandas.read_json.html parser_options: { orient: 'records' // Row-oriented: Array of objects } // Default: to columnar json - Object of arrays } ); // Node files are optional, mainly for properties const nodesFile = new NodeFile(nodesRows); const dataset = new Dataset( { // Also: color, size, title, icon, badge, axis // - https://hub.graphistry.com/docs/api/2/rest/upload/colors // - https://hub.graphistry.com/docs/api/2/rest/upload/complex/ node_encodings: { bindings: { node: 'n', // id (required) node_title: 'vv' }, complex: { default: { pointColorEncoding: { graphType: "point", encodingType: "color", attribute: "vv", variation: "continuous", colors: ["blue", "yellow", "red"] }, pointIconEncoding: { graphType: "point", encodingType: "icon", attribute: "t", variation: "categorical", mapping: { categorical: { fixed: { "person": "user", "car": "car" }, other: "question" } } } } } }, //Also: color, weight, icon, badge, title // - https://hub.graphistry.com/docs/api/2/rest/upload/colors // - https://hub.graphistry.com/docs/api/2/rest/upload/complex/ edge_encodings: { bindings: { source: 's', destination: 'd' }, complex: { } }, // Brand & theme: Background, foreground, logo, page metadata // https://hub.graphistry.com/docs/api/2/rest/upload/metadata/ metadata: { bg: { color: 'silver' }, logo: { "url": "http://a.com/logo.png", } }, name: 'testdata', }, edgesFile, nodesFile, // Visual and layout settings // https://hub.graphistry.com/docs/api/1/rest/url/#urloptions { strongGravity: true, edgeCurvature: 0.5 } ); await dataset.upload(client); console.info(`View dataset ${dataset.datasetID} at ${dataset.datasetURL}`); console.info(`Dataset using node file ${nodesFile.fileID}, edge file ${edgesFile.fileID}`); </code></pre> <a href="#underlying-rest-api" id="underlying-rest-api" style="color: inherit; text-decoration: none;"> <h3>Underlying REST API</h3> </a> For further information about authentication, files, and datasets, see the <a href="https://hub.graphistry.com/docs/api/">Graphistry REST API docs</a>. <a href="#typescript" id="typescript" style="color: inherit; text-decoration: none;"> <h3>TypeScript</h3> </a> Types are already automatically bundled with this module For source maps, you may want to add <code>NODE_OPTIONS=--enable-source-maps</code> to your environment or run node as <code>node --enable-source-maps</code>. </div></div><div class="col-4 col-menu menu-sticky-wrap menu-highlight"><nav class="tsd-navigation primary"><ul><li class="current"><a href="modules.html">Exports</a></li></ul></nav><nav class="tsd-navigation secondary menu-sticky"><ul><li class="tsd-kind-class"><a href="classes/Client.html" class="tsd-kind-icon">Client</a></li><li class="tsd-kind-class"><a href="classes/ClientPKey.html" class="tsd-kind-icon">ClientPKey</a></li><li class="tsd-kind-class"><a href="classes/Dataset.html" class="tsd-kind-icon">Dataset</a></li><li class="tsd-kind-class"><a href="classes/EdgeFile.html" class="tsd-kind-icon">EdgeFile</a></li><li class="tsd-kind-class"><a href="classes/File.html" class="tsd-kind-icon">File</a></li><li class="tsd-kind-enum"><a href="enums/FileType.html" class="tsd-kind-icon">FileType</a></li><li class="tsd-kind-type-alias"><a href="modules.html#Mode" class="tsd-kind-icon">Mode</a></li><li class="tsd-kind-type-alias"><a href="modules.html#ModeAction" class="tsd-kind-icon">ModeAction</a></li><li class="tsd-kind-type-alias"><a href="modules.html#ModeActionRaw" class="tsd-kind-icon">ModeActionRaw</a></li><li class="tsd-kind-class"><a href="classes/NodeFile.html" class="tsd-kind-icon">NodeFile</a></li><li class="tsd-kind-class"><a href="classes/Privacy.html" class="tsd-kind-icon">Privacy</a></li></ul></nav></div></div></div><footer class=""><div class="container"><h2>Legend</h2><div class="tsd-legend-group"><ul class="tsd-legend"><li class="tsd-kind-constructor tsd-parent-kind-class">Constructor</li><li class="tsd-kind-property tsd-parent-kind-class">Property</li><li class="tsd-kind-method tsd-parent-kind-class">Method</li></ul><ul class="tsd-legend"><li class="tsd-kind-property tsd-parent-kind-class tsd-is-inherited">Inherited property</li><li class="tsd-kind-method tsd-parent-kind-class tsd-is-inherited">Inherited method</li></ul><ul class="tsd-legend"><li class="tsd-kind-property tsd-parent-kind-class tsd-is-private">Private property</li></ul></div><h2>Settings</h2>Theme <select id="theme"><option value="os">OS</option><option value="light">Light</option><option value="dark">Dark</option></select></div></footer><div class="overlay"></div><script src="assets/main.js"></script></body></html>