Data Strcutures

This section introduces the core data structures provided by the driver. These objects represent the entities you work with when retrieving results from Ultipa.

Node

Node includes the following fields:

If a query returns nodes, you can use asNodes() to convert the results into a list of Node objects:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("MATCH (n) RETURN n LIMIT 2", requestConfig);
const nodes = response.alias("n").asNodes();

for (const node of nodes) {
  console.log(node)
};

Node {
  uuid: '72059793061183494',
  id: 'ULTIPA800000000000003B',
  schema: 'account',
  values: {
    industry: 'Publishing',
    name: 'Velox',
    gender: 'female',
    year: 1976
  }
}
Node {
  uuid: '504405357288751106',
  id: 'ULTIPA8000000000000060',
  schema: 'account',
  values: {
    industry: 'Real Estate',
    name: 'Kox3',
    gender: 'male',
    year: 1980
  }
}

Edge

Edge includes the following fields:

If a query returns edges, you can use asEdges() to convert the results into a list of Edge objects:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("MATCH ()-[e]->() RETURN e LIMIT 3",requestConfig);
const edges = response.alias("e").asEdges();

for (const edge of edges) {
  console.log(edge)
};

Edge {
  uuid: '385',
  fromUuid: '6196955286285058053',
  toUuid: '7998395137233256458',
  from: 'ULTIPA8000000000000007',
  to: 'ULTIPA800000000000000D',
  schema: 'follow',
  values: {}
}
Edge {
  uuid: '553',
  fromUuid: '6196955286285058053',
  toUuid: '9223377534412914779',
  from: 'ULTIPA8000000000000007',
  to: 'ULTIPA8000000000000408',
  schema: 'wishlist',
  values: { timestamp: 1537331913, datetime: '2018-09-19 12:38:33' }
}
Edge {
  uuid: '559',
  fromUuid: '6196955286285058053',
  toUuid: '4611691515985526871',
  from: 'ULTIPA8000000000000007',
  to: 'ULTIPA80000000000003ED',
  schema: 'wishlist',
  values: { timestamp: 1544118960, datetime: '2018-12-07 01:56:00' }
}

Path

Path includes the following fields:

Methods on Path:

If a query returns paths, you can first use asGraph() to convert the results into a Graph object; the Graph object provides access to the returned paths:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("MATCH p = ()-[]-() RETURN p LIMIT 2", requestConfig);
const graph = response.alias("p").asGraph();
const paths = graph.getPaths();

for (const path of paths) {
  console.log("Node _uuids:", path.nodeUuids, "Length:", path.length())
};

Node _uuids: [ '6196955286285058053', '7998395137233256458' ] Length: 1
Node _uuids: [ '6196955286285058053', '9223377534412914779' ] Length: 1

Graph

Graph includes the following fields:

Methods on Graph:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("MATCH p = ()-[]-() RETURN p LIMIT 2", requestConfig);
const graph = response.alias("p").asGraph();

console.log("Unique nodes in the graph:");
console.log(graph.nodes);

console.log("\n_uuid of nodes in each path:");
const paths = graph.getPaths();
for (const path of paths) {
  console.log("Node _uuids:", path.nodeUuids)
};

Unique nodes in the graph:
Map(3) {
  '6196955286285058053' => Node {
    uuid: '6196955286285058053',
    id: 'ULTIPA8000000000000007',
    schema: 'account',
    values: {
      industry: 'Government',
      name: 'Yuki',
      gender: 'female',
      year: 1986
    }
  },
  '7998395137233256458' => Node {
    uuid: '7998395137233256458',
    id: 'ULTIPA800000000000000D',
    schema: 'account',
    values: {
      industry: 'Health',
      name: 'CR.',
      gender: 'female',
      year: 1987
    }
  },
  '9223377534412914779' => Node {
    uuid: '9223377534412914779',
    id: 'ULTIPA8000000000000408',
    schema: 'movie',
    values: {
      genre: 'Fiction Action Thriller',
      name: 'Inception',
      rating: 9,
      year: 2010
    }
  }
}

_uuid of nodes in each path:
Node _uuids: [ '6196955286285058053', '7998395137233256458' ]
Node _uuids: [ '6196955286285058053', '9223377534412914779' ]

const response1 = await conn.gql("MATCH p = ()-[]-() RETURN p LIMIT 2", requestConfig);
const graph = response1.alias("p").asGraph();
console.log("Original nodes in the graph:")
for (const [_uuid, node] of graph.nodes) {
  console.log(_uuid)
};

// Adds 3 account nodes to the returned graph
const response2 = await conn.gql("MATCH (n:account) RETURN n LIMIT 3", requestConfig);
const nodes = response2.alias("n").asNodes();
for (const node of nodes) {
  graph.addNode(node);
};
console.log("New collection of nodes in the graph:")
for (const [_uuid, node] of graph.nodes) {
  console.log(_uuid)
};

Original nodes in the graph:
6196955286285058053
7998395137233256458
9223377534412914779
New collection of nodes in the graph:
6196955286285058053
7998395137233256458
9223377534412914779
72059793061183494
504405357288751106
576462951326679064

GraphSet

GraphSet includes the following fields:

const response = await conn.gql("SHOW GRAPH");
const graphs = response.alias("_graph").asGraphSets();

for (const graph of graphs) {
  console.log(graph.name)
}

DFS_EG
cyber
netflow

Schema

Schema includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("SHOW NODE SCHEMA", requestConfig);
const schemas = response.alias("_nodeSchema").asSchemas();

for (const schema of schemas) {
  console.log(schema.name)
}

default
account
celebrity
country
movie

Property

Property includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("SHOW NODE account PROPERTY", requestConfig);
const properties = response.alias("_nodeProperty").asProperties();

for (const property of properties) {
  console.log(property.name)
}

title
profile
age
name
logo

Attr

Attr includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("MATCH (n:account) RETURN n.name LIMIT 3");
const attr = response.alias("n.name").asAttr();
console.log("name:", attr.name);
console.log("values:", attr.values);
console.log("type:", attr.propertyType);

name: n.name
values: ['Velox', 'K03', 'Lunatique']
type: 7

Table

Table includes the following fields:

Methods on a Table object:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql(
  "MATCH (n:account) RETURN table(n._id, n.name) LIMIT 3",
  requestConfig
);
const table = response.get(0).asTable();

console.log("Header:");
for (const header of table.getHeaders()) {
  console.log(header.propertyName, " - ", header.propertyType);
}

console.log("First Row:");
const rows = table.toKV();
if (rows.length != 0) {
  console.log(rows[0]);
}

Header:
n._id - 7
n.name - 7
First Row:
{'n._id': 'ULTIPA800000000000003B', 'n.name': 'Velox'}

HDCGraph

HDCGraph includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.uql("hdc.graph.show()", requestConfig);
const hdcGraphs = response.alias("_hdcGraphList").asHDCGraphs();

for (const hdcGraph of hdcGraphs) {
  console.log(hdcGraph.name, "on", hdcGraph.hdcServerName);
}

miniCircle_hdc_graph on hdc-server-1
miniCircle_hdc_graph2 on hdc-server-2

Algo

Algo includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.uql("show().hdc('hdc-server-1')");
const algos = response.alias("_algoList").asAlgos();

for (const algo of algos) {
  if (algo.type == "algo") {
    console.log(
      `${algo.name} supports writeback types: ${algo.writeSupportType}`
    );
  }
}

fastRP supports writeback types: DB,FILE
struc2vec supports writeback types: DB,FILE

Projection

Projection includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.uql("show().projection()", requestConfig);
const projections = response.alias("_projectionList").asProjections();

for (const projection of projections) {
  console.log(projection.name)
}

miniCircle_projection_1

Index

Index includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};
const response = await conn.gql("SHOW NODE INDEX", requestConfig);
const indexList = response.alias("_nodeIndex").asIndexes();

for (const index of indexList) {
  console.log(index.schema, "-", index.properties)
}

account - gender(6)
account - year

Privilege

Privilege includes the following fields:

const response = await conn.uql("show().privilege()");
const privileges = response.alias("_privilege").asPrivileges();

const graphPrivilegeNames = privileges
  .filter((p) => p.level === PrivilegeLevel.GraphLevel)
  .map((p) => p.name)
  .join(", ");
console.log("Graph privileges: " + graphPrivilegeNames);

const systemPrivilegeNames = privileges
  .filter((p) => p.level === PrivilegeLevel.SystemLevel)
  .map((p) => p.name)
  .join(", ");
console.log("System privileges: " + systemPrivilegeNames);

Graph privileges: READ, INSERT, UPSERT, UPDATE, DELETE, CREATE_SCHEMA, DROP_SCHEMA, ALTER_SCHEMA, SHOW_SCHEMA, RELOAD_SCHEMA, CREATE_PROPERTY, DROP_PROPERTY, ALTER_PROPERTY, SHOW_PROPERTY, CREATE_FULLTEXT, DROP_FULLTEXT, SHOW_FULLTEXT, CREATE_INDEX, DROP_INDEX, SHOW_INDEX, LTE, UFE, CLEAR_JOB, STOP_JOB, SHOW_JOB, ALGO, CREATE_PROJECT, SHOW_PROJECT, DROP_PROJECT, CREATE_HDC_GRAPH, SHOW_HDC_GRAPH, DROP_HDC_GRAPH, COMPACT_HDC_GRAPH, SHOW_VECTOR_INDEX, CREATE_VECTOR_INDEX, DROP_VECTOR_INDEX, SHOW_CONSTRAINT, CREATE_CONSTRAINT, DROP_CONSTRAINT
System privileges: TRUNCATE, COMPACT, CREATE_GRAPH, SHOW_GRAPH, DROP_GRAPH, ALTER_GRAPH, TOP, KILL, STAT, SHOW_POLICY, CREATE_POLICY, DROP_POLICY, ALTER_POLICY, SHOW_USER, CREATE_USER, DROP_USER, ALTER_USER, SHOW_PRIVILEGE, SHOW_META, SHOW_SHARD, ADD_SHARD, DELETE_SHARD, REPLACE_SHARD, SHOW_HDC_SERVER, ADD_HDC_SERVER, DELETE_HDC_SERVER, LICENSE_UPDATE, LICENSE_DUMP, GRANT, REVOKE, SHOW_BACKUP, CREATE_BACKUP, SHOW_VECTOR_SERVER, ADD_VECTOR_SERVER, DELETE_VECTOR_SERVER

Policy

Policy includes the following fields:

PropertyPrivilegeElement includes the following fields:

const response = await conn.uql("show().policy('Tester')");
const policy = response.alias("_policy").asPolicies();
console.log("Graph privileges: ", policy[0].graphPrivileges);
console.log("System privileges: ", policy[0].systemPrivileges);
console.log("Property privileges:");
console.log("- Node (Read): ", policy[0].propertyPrivileges.node.read);
console.log("- Node (Write): ", policy[0].propertyPrivileges.node.write);
console.log("- Node (Deny): ", policy[0].propertyPrivileges.node.deny);
console.log("- Edge (Read): ", policy[0].propertyPrivileges.edge.read);
console.log("- Edge (Write): ", policy[0].propertyPrivileges.edge.write);
console.log("- Edge (Deny): ", policy[0].propertyPrivileges.edge.deny);
console.log("Policies: ", policy[0].policies)

Graph Privileges: Map(3) {'amz' => ['ALGO', 'INSERT', 'DELETE', 'UPSERT'], 'StoryGraph' => ['UPDATE', 'READ']}
System Privileges: ['TRUNCATE', 'KILL', 'TOP']
Property Privileges:
- Node (Read): [['*', '*', '*']]
- Node (Write): []
- Node (Deny): []
- Edge (Read): []
- Edge (Write): [['amz', '*', '*'], ['alimama', '*', '*']]
- Edge (Deny): [['miniCircle', 'review', 'value, timestamp']]
Policies: ['sales', 'manager']

User

User includes the following fields:

PropertyPrivilegeElement includes the following fields:

const response = await conn.uql("show().user('johndoe')");
const user = response.alias("_user").asUsers();
console.log("Created Time: ", user[0].createdTime);
console.log("Graph privileges: ", user[0].graphPrivileges);
console.log("System privileges: ", user[0].systemPrivileges);
console.log("Property privileges:");
console.log("- Node (Read): ", user[0].propertyPrivileges.node.read);
console.log("- Node (Write): ", user[0].propertyPrivileges.node.write);
console.log("- Node (Deny): ", user[0].propertyPrivileges.node.deny);
console.log("- Edge (Read): ", user[0].propertyPrivileges.edge.read);
console.log("- Edge (Write): ", user[0].propertyPrivileges.edge.write);
console.log("- Edge (Deny): ", user[0].propertyPrivileges.edge.deny);
console.log("Policies: ", user[0].policies);

Created Time: 2025-04-02 11:08:38
Graph Privileges: Map(2){'amz'=> ['ALGO', 'INSERT', 'DELETE', 'UPSERT'], 'StoryGraph'=> ['UPDATE', 'READ']}
System Privileges: ['TRUNCATE', 'KILL', 'TOP']
Property Privileges:
- Node (Read): [['*', '*', '*']]
- Node (Write): []
- Node (Deny): []
- Edge (Read): []
- Edge (Write): [['amz', '*', '*'], ['alimama', '*', '*']]
- Edge (Deny): [['miniCircle', 'review', 'value, timestamp']]
Policies: ['sales', 'manager']

Process

Process includes the following fields:

const response = await conn.uql("top()");
const processes = response.alias("_top").asProcesses();

for (const process of processes) {
  console.log(process.processId);
}

1049435

Job

Job includes the following fields:

const requestConfig: RequestConfig = {
  graph: "miniCircle",
};

const response = await conn.gql("SHOW JOB", requestConfig);
const jobs = response.alias("_job").asJobs();
const falid_jobs = jobs.filter((job) => job.status === "FAILED");

if (falid_jobs.length > 0) {
  for (const job of falid_jobs) {
    console.log(job.id, "_", job.errMsg, "-", job.type);
  }
}

51 - Fulltext name already exists. - CREATE_FULLTEXT
42 - Fulltext name already exists. - CREATE_FULLTEXT
26 - [engine] uuids should be unsigned integer - HDC_ALGO
26_1 -  - HDC_ALGO
17 - [engine] all failed, because some nodes do not exist in db - HDC_ALGO
17_1 -  - HDC_ALGO