Quick Start

The Ultipa Node.js driver is the official library to interact with an Ultipa instance through a Node.js application. It requires Node.js v12.22.12 or later.

Install the Driver

You can install the latest Ultipa package from the npm registry:

npm install @ultipa-graph/ultipa-driver

Connect to the Database

You need a running Ultipa database to use the driver. The easiest way to get an instance is via Ultipa Cloud (free trial available), or you can use an on-premises deployment if you already have one.

Creates a connection using and tests the connection:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    // URI example: hosts: ["xxxx.us-east-1.cloud.ultipa.com:60010"]
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Tests the connection
  const isSuccess = await driver.test();
  console.log(`Connection succeeds: ${isSuccess}`);
};

sdkUsage().catch(console.error);

Connection succeeds: true

More info on database connection →

Work with the Database

GQL is the international standardized query language for graph databases. You can use the driver's gql() method to send GQL queries and fully interact with the database. If you're new to GQL, check out the GQL Quick Start or the GQL documentation for a detailed orientation.

Some of you may be familiar with UQL, Ultipa's proprietary query language, which can also fully interact with the database. Use the driver's uql() method for UQL queries. To lean UQL, see the UQL documentation.

Create a Graph

An Ultipa database instance can host multiple graphs (or graphsets), each representing a dataset of nodes and edges.

Creates a new graph:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Creates a new open graph 'g1'
  let response = await driver.gql("CREATE GRAPH g1 ANY")
  console.log(response.status?.message)
};

sdkUsage().catch(console.error);

SUCCESS

Insert Nodes and Edges

Since the database may contain multiple graphs, you must specify the graph when inserting data. You can either set the default graph using UltipaConfig.defaultGraph when establishing the connection, or specify the graph for a particular request with RequestConfig.graph.

Method 1: Uses UltipaConfig.defaultGraph to set the default graph

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>",
    defaultGraph: "g1" // Sets the default graph to 'g1'
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Inserts nodes and edges into the graph 'g1'
  let response = await driver.gql(`INSERT 
    (u1:User {_id: 'U1', name: 'rowlock'}),
    (u2:User {_id: 'U2', name: 'Brainy'}),
    (u3:User {_id: 'U3', name: 'purplechalk'}),
    (u4:User {_id: 'U4', name: 'mochaeach'}),
    (u5:User {_id: 'U5', name: 'lionbower'}),
    (u1)-[:Follows {createdOn: DATE('2024-01-05')}]->(u2),
    (u4)-[:Follows {createdOn: DATE('2024-02-10')}]->(u2),
    (u2)-[:Follows {createdOn: DATE('2024-02-01')}]->(u3),
    (u3)-[:Follows {createdOn: DATE('2024-05-03')}]->(u5)`)
  console.log(response.status?.message)
};

sdkUsage().catch(console.error);

SUCCESS

Method 2: Uses RequestConfig.graph to set the graph for a request (this overwrites any default graph set in UltipaConfig.defaultGraph)

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";
import { RequestConfig } from "@ultipa-graph/ultipa-driver/dist/types/types.js";

async function sdkUsage() {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>",
    defaultGraph: "miniCircle" // Sets the default graph to 'miniCircle'
  };

  const driver = new UltipaDriver(ultipaConfig);

  // Inserts nodes and edges into graph the 'g1'
  const requestConfig: RequestConfig = {
    graph: "g1" // Sets the graph for the request
  }; 

  let response = await driver.gql(`INSERT 
    (u1:User {_id: 'U1', name: 'rowlock'}),
    (u2:User {_id: 'U2', name: 'Brainy'}),
    (u3:User {_id: 'U3', name: 'purplechalk'}),
    (u4:User {_id: 'U4', name: 'mochaeach'}),
    (u5:User {_id: 'U5', name: 'lionbower'}),
    (u1)-[:Follows {createdOn: DATE('2024-01-05')}]->(u2),
    (u4)-[:Follows {createdOn: DATE('2024-02-10')}]->(u2),
    (u2)-[:Follows {createdOn: DATE('2024-02-01')}]->(u3),
    (u3)-[:Follows {createdOn: DATE('2024-05-03')}]->(u5)`, requestConfig);
  console.log(response.status?.message);
}

sdkUsage().catch(console.error);

SUCCESS

Retrieve Nodes

As with data insertion, you must specify the graph from which to retrieve nodes.

To retrieve 3 User nodes from graph g1, use Response.alias().asNodes() to convert the returned nodes into a list of Node objects:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";
import { RequestConfig } from "@ultipa-graph/ultipa-driver/dist/types/types.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Retrieves 3 User nodes from the graph 'g1'
  const requestConfig: RequestConfig = {
    graph: "g1"
  }; 
  let response = await driver.gql("MATCH (u:User) RETURN u LIMIT 3", requestConfig);
  const nodes = response.alias("u").asNodes();
  for (const node of nodes) {
    console.log(node)
  };
};

sdkUsage().catch(console.error);

Node {
  uuid: '6557243256474697731',
  id: 'U4',
  schema: 'User',
  values: { name: 'mochaeach' }
}
Node {
  uuid: '7926337543195328514',
  id: 'U2',
  schema: 'User',
  values: { name: 'Brainy' }
}
Node {
  uuid: '14771808976798482436',
  id: 'U5',
  schema: 'User',
  values: { name: 'lionbower' }
}

Retrieve Edges

As with data insertion, you must specify the graph from which to retrieve edges.

To retrieve all incoming Follows edges of user U2 from graph g1, use Response.alias().asEdges() to convert the returned edges into a list of Edge objects:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";
import { RequestConfig } from "@ultipa-graph/ultipa-driver/dist/types/types.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Retrieves all incoming Follows edges of the user U2 from the graph 'g1'
  const requestConfig: RequestConfig = {
    graph: "g1"
  }; 
  let response = await driver.gql("MATCH (:User {_id: 'U2'})<-[e:Follows]-() RETURN e", requestConfig);
  const edges = response.alias("e").asEdges();
  for (const edge of edges) {
    console.log(edge)
  };
};

sdkUsage().catch(console.error);

Edge {
  uuid: '1',
  fromUuid: '15276212135063977986',
  toUuid: '7926337543195328514',
  from: 'U1',
  to: 'U2',
  schema: 'Follows',
  values: { createdOn: '2024-01-05' }
}
Edge {
  uuid: '2',
  fromUuid: '6557243256474697731',
  toUuid: '7926337543195328514',
  from: 'U4',
  to: 'U2',
  schema: 'Follows',
  values: { createdOn: '2024-02-10' }
}

Retrieve Paths

As with data insertion, you must specify the graph from which to retrieve paths.

To retrieve 1-step paths from user U1 in graph g1, use Response.alias().asGraph() to convert the results into a Graph object, which contains the returned paths:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";
import { RequestConfig } from "@ultipa-graph/ultipa-driver/dist/types/types.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Retrieves 1-step paths from user U1 in the graph 'g1'
  const requestConfig: RequestConfig = {
    graph: "g1"
  }; 
  let response = await driver.gql(`
    MATCH p = (u)-[]-()
    WHERE u._id = "U1"
    RETURN p`, requestConfig);
  const graph = response.alias("p").asGraph();
  for (const path of graph.paths ?? []) {
    console.log(path)
  };
};

sdkUsage().catch(console.error);

Path {
  nodeUuids: [ '15276212135063977986', '7926337543195328514' ],
  edgeUuids: [ '1' ],
  nodes: Map(2) {
    '15276212135063977986' => Node {
      uuid: '15276212135063977986',
      id: 'U1',
      schema: 'User',
      values: [Object]
    },
    '7926337543195328514' => Node {
      uuid: '7926337543195328514',
      id: 'U2',
      schema: 'User',
      values: [Object]
    }
  },
  edges: Map(1) {
    '1' => Edge {
      uuid: '1',
      fromUuid: '15276212135063977986',
      toUuid: '7926337543195328514',
      from: 'U1',
      to: 'U2',
      schema: 'Follows',
      values: [Object]
    }
  }
}

Convenience Methods

In addition to the gql() method, which lets you send GQL queries to fully interact with the database, the driver provides some convenience methods that allow you to perform common operations without writing GQL.

For example, the showGraph() returns all graphs in the database, it returns a list of Graphset objects:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Retrieves all graphs in the database
  const graphs = await driver.showGraph();
  for (const graph of graphs) {
    console.log(graph.name)
  }
};

sdkUsage().catch(console.error);

g1
miniCircle
social

For example, the insertNodes() method allows you to insert nodes into a graph:

import { UltipaDriver } from "@ultipa-graph/ultipa-driver";
import type { ULTIPA } from "@ultipa-graph/ultipa-driver/dist/types/index.js";
import { InsertRequestConfig } from "@ultipa-graph/ultipa-driver/dist/types/types.js";

let sdkUsage = async () => {
  const ultipaConfig: ULTIPA.UltipaConfig = {
    hosts: ["10.xx.xx.xx:60010"],
    username: "<username>",
    password: "<password>"
  };

  const driver = new UltipaDriver(ultipaConfig);
  
  // Inserts two User nodes into the graph 'g1'

  const insertRequestConfig: InsertRequestConfig = {
    graph: "g1"
  };

  const node1 = {
    id: "U6",
    values: {
      name: "Alice",
      age: 28
    },
  };
  const node2 = {
    id: "U7",
    values: {
      name: "Quars"
    },
  };
  const nodes = [node1, node2]

  let response = await driver.insertNodes("User", nodes, insertRequestConfig);
  console.log(response.status?.message);
};

sdkUsage().catch(console.error);

SUCCESS