@graphistry/js-upload-api
Version:
Graphistry upload client for reuse by node and browser clients
288 lines • 9.78 kB
TypeScript
import { ClientType } from './types.js';
import { File, EdgeFile, NodeFile } from './File.js';
import { Mode, ModeAction, Privacy } from './Privacy.js';
/**
* # Dataset examples
*
* Datasets are how to combine files into a single visualizable graph.
* Powerfully, you can also specify visualization settings and
* data-driven visual encodings as part of your dataset's bindings.
*
* For the many options, see the [JSON documentation](https://hub.graphistry.com/docs/api/).
*
* <br>
*
* ---
*
* <br>
*
* @example **Create a dataset from edges and upload using async/await**
* ```javascript
* import { Dataset } from '@graphistry/node-api';
* const dataset = new Dataset(
* {
* node_encodings: { bindings: { } },
* edge_encodings: { bindings: { source: 's', destination: 'd' } },
* metadata: {},
* name: 'testdata',
* },
* edgesFile
* );
* await dataset.upload(client);
* console.log(`Dataset ${dataset.datasetID} uploaded to ${dataset.datasetURL}`);
* ```
*
* <br>
*
* @example **Create a dataset from nodes + edges and upload using promises**
* ```javascript
* import { Dataset } from '@graphistry/node-api';
* const dataset = new Dataset(
* {
* node_encodings: { bindings: { 'node': 'n' } },
* edge_encodings: { bindings: { 'source': 's', 'destination': 'd' } },
* metadata: {},
* name: 'testdata',
* },
* edgesFile,
* nodesFile
* );
* dataset.upload(client).then(
* () => console.log(`Dataset ${dataset.datasetID} uploaded to ${dataset.datasetURL}`)
* ).catch(err => console.error('oops', err));
* ```
*
* <br>
*
* @example **Create a dataset using Arrow**
* ```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');
* ```
*
* <br>
*
* @example **Add files after the Dataset is instantiated but before it has been uploaded**
* ```javascript
* import { Dataset } from '@graphistry/node-api';
* const dataset = new Dataset(
* {
* node_encodings: { bindings: { 'node': 'n' } },
* edge_encodings: { bindings: { 'source': 's', 'destination': 'd' } },
* metadata: {},
* name: 'testdata',
* }
* );
* dataset.addFile(nodesFile);
* dataset.addFile(edgesFile);
* await dataset.upload(client);
* console.log(`Dataset ${dataset.datasetID} uploaded to ${dataset.datasetURL}`);
* ```
*
* <br>
*
* @example **Set privacy on uploaded dataset**
* ```javascript
* import { Dataset, Privacy } from '@graphistry/node-api';
* const dataset = new Dataset(
* {
* node_encodings: { bindings: { } },
* edge_encodings: { bindings: { 'source': 's', 'destination': 'd' } },
* metadata: {},
* name: 'testdata',
* }
* );
* dataset.addFile(edgesFile);
* await dataset.upload(client);
* await dataset.setPrivacy(client); // see additional options below
* ```
*
* <br>
*
* @example **Set simple data-driven bindings for titles, colors, icons, and labels**
* ```javascript
* import { Dataset } from '@graphistry/node-api';
* const dataset = new Dataset(
* {
*
* // See also simple title, color, ... and complex color, size, icon, badge, ...
* // 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
* 'node_title': 'some_title_column' //optional
* },
*
* complex: {
* default: {
* pointSizeEncoding: {
* graphType: 'point',
* encodingType: 'size',
* attribute: 'payment',
* variation: 'categorical',
* mapping: {
* fixed: {
* big: 500,
* normal: 200,
* tiny: 10
* },
* other: 100
* }
* }
* }
* }
* },
*
* // See also simple title, color, ... and complex color, size, icon, badge, ...
* // 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: {
* default: {
* edgeColorEncoding: {
* graphType: 'point',
* encodingType: 'color',
* attribute: 'time',
* variation: 'continuous',
* colors: ['blue', 'yellow', 'red']
* }
* }
* }
* },
*
* // Set 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',
* },
*
* nodesFile,
* edgesFile
*
* // Visual and layout settings
* // https://hub.graphistry.com/docs/api/1/rest/url/#urloptions
* {
* strongGravity: true,
* edgeCurvature: 0.5
* }
*
* );
* await dataset.upload();
* ```
*/
export declare class Dataset {
readonly edgeFiles: EdgeFile[];
readonly nodeFiles: NodeFile[];
readonly bindings: Record<string, unknown>;
readonly urlOpts: Record<string, unknown>;
private _datasetID?;
get datasetID(): string | undefined;
private _createDatasetResponse;
getCreateDatasetResponse(): any;
private _usedClientProtocolHostname?;
get datasetURL(): string;
/**
*
* See examples at top of file
*
* Dataset definitions including required node_encodings, edge_encodings, metadata and name.
* Optional definitions include edge_hypergraph_transform, and description, and various subfields.
* URL settings may also be specified for additional styling.
* This method autopopulates definitions edge_files, and if provided, node_files.
*
* Node files are optional: Nodes will be synthesized based on edges if not provided.
*
* If files have not been uploaded yet, this method will upload them for you.
*
* For more information about bindings, see https://hub.graphistry.com/docs/api/2/rest/upload/
*
* For more information about URL style settings, see https://hub.graphistry.com/docs/api/1/rest/url/#urloptions
*
* For more information about theming, see https://hub.graphistry.com/docs/api/2/rest/upload/metadata/
*
* For more information on simple encodings, see https://hub.graphistry.com/docs/api/2/rest/upload/colors
*
* For more information on complex encodings, see https://hub.graphistry.com/docs/api/2/rest/upload/complex/
*
* @param bindings JSON dictionary of bindings
* @param nodeFiles File object(s)
* @param edgeFiles File object(s)
* @param urlOpts JSON dictionary of URL options
*/
constructor(bindings?: Record<string, unknown>, edgeFiles?: EdgeFile[] | EdgeFile, nodeFiles?: NodeFile[] | NodeFile, urlOpts?: Record<string, unknown>);
/**
*
* See examples at top of file
*
* Upload the dataset to the Graphistry server.
*
* If files have not been uploaded yet, this method will upload them for you.
*
* Upon completion, attributes datasetID and datasetURL will be set, as well as
* createDatasetResponse and uploadResponse.
*
* @param client Client object
* @returns Promise that resolves when the dataset is uploaded
*/
upload(client: ClientType): Promise<Dataset>;
private createDataset;
/**
* Add one or more bindings to the existing ones. In case of conflicts, override the existing ones.
*
* For more information about each, see https://hub.graphistry.com/docs/api/2/rest/upload/
*
* @param bindings JSON dictionary of bindings to be added to the existing ones
*/
updateBindings(bindings: Record<string, unknown>): void;
/**
*
* See examples at top of file
*
* Add an additional node or edge file to the existing ones.
*
* @param file File object. Does not need to be uploaded yet.
*
**/
addFile(file: File): void;
private fillMetadata;
/**
*
* See examples at top of file
*
* Set the privacy mode of the dataset. All but the client are optional.
*
* @param client Client object
* @param mode Privacy mode. One of 'private', 'public', 'organization'
* @param modeAction Capability allowed when shared
* @param invitedUsers List of user IDs to share with
* @param notify Whether to notify users of the share
* @param message Message to include in the notification
*
*
* @returns Promise that resolves when the privacy is set
* @throws Error if the dataset has not been uploaded yet
* @throws Error if server call fails
*/
privacy(client: ClientType, mode?: Mode, modeAction?: ModeAction, invitedUsers?: string[], notify?: boolean, message?: string): Promise<Privacy>;
}
//# sourceMappingURL=Dataset.d.ts.map