处理查询结果

gql()和uql()等方法返回一个Response，其中包含来自数据库的原始查询结果和执行信息。为了在应用中使用查询结果，你需要将其提取出来并转换成可用的数据结构。

Response包含以下字段:

提取查询结果

为了提取查询结果，也就是Response.items里的DataItem，可使用get()或alias()方法。

get()

通过别名索引获取查询结果。

参数

• index: number：别名索引。

返回值

• DataItem：查询结果。

const response = await driver.gql("MATCH (n)-[e]->() RETURN n, e LIMIT 2");
console.log(response.get(0));

GQL语句返回n和e两个别名；get()方法获取与索引为0的别名n对应的DataItem。

DataItem {
  alias: 'n',
  type: 2,
  entities: [
    Node {
      uuid: '6557243256474697731',
      id: 'U4',
      schema: 'User',
      values: [Object]
    },
    Node {
      uuid: '7926337543195328514',
      id: 'U2',
      schema: 'User',
      values: [Object]
    }
  ]
}

alias()

通过别名名称获取查询结果。

参数

• alias: string：别名名称。

返回值

• DataItem：查询结果。

const response = await driver.gql("MATCH (n)-[e]->() RETURN n, e LIMIT 2");
console.log(response.alias("e"));

GQL语句返回n和e两个别名；alias()方法获取别名e对应的DataItem。

DataItem {
  alias: 'e',
  type: 3,
  entities: [
    Edge {
      uuid: '2',
      fromUuid: '6557243256474697731',
      toUuid: '7926337543195328514',
      from: 'U4',
      to: 'U2',
      schema: 'Follows',
      values: [Object]
    },
    Edge {
      uuid: '3',
      fromUuid: '7926337543195328514',
      toUuid: '17870285520429383683',
      from: 'U2',
      to: 'U3',
      schema: 'Follows',
      values: [Object]
    }
  ]
}

转换查询结果

使用一个as<DataStructure>()方法将DataItem.entities转换成对应的数据结构。

asNodes()

如果一个查询返回点，使用asNodes()将它们转换成一个Node对象列表。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH (n:User) RETURN n LIMIT 2", requestConfig);
const nodes = response.alias("n").asNodes();
for (const node of nodes) {
  console.log(node)
}

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

asFirstNode()

如果一个查询返回点，使用asFirstNode()将返回的第一个点转换成一个Node对象。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH (n:User) RETURN n", requestConfig);
const node = response.alias("n").asFirstNode();
console.log(node)

Node {
  uuid: '6557243256474697731',
  id: 'U4',
  schema: 'User',
  values: { name: 'mochaeach' }
}

asEdges()

如果一个查询返回边，使用asEdges()将它们转换成一个Edge对象列表。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH ()-[e]->() RETURN e LIMIT 2", requestConfig);
const edges = response.alias("e").asEdges();
for (const edge of edges) {
  console.log(edge)
}

Edge {
  uuid: '2',
  fromUuid: '6557243256474697731',
  toUuid: '7926337543195328514',
  from: 'U4',
  to: 'U2',
  schema: 'Follows',
  values: { createdOn: '2024-02-10' }
}
Edge {
  uuid: '3',
  fromUuid: '7926337543195328514',
  toUuid: '17870285520429383683',
  from: 'U2',
  to: 'U3',
  schema: 'Follows',
  values: { createdOn: '2024-02-01' }
}

asFirstEdge()

如果一个查询返回边，使用asFirstEdge()将返回的第一条边转换成一个Edge对象。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH ()-[e]->() RETURN e LIMIT 2", requestConfig);
const edge = response.alias("e").asFirstEdge();
console.log(edge)

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

asGraph()

如果一个查询返回路径，使用asGraph()将它们转换成一个Graph对象。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH p = ()-[]->() RETURN p LIMIT 2", requestConfig);
const graph = response.alias("p").asGraph();
console.log("Unique nodes:", graph.nodes)
console.log("Unique edges:", graph.edges)
console.log("All paths:", graph.paths)

Unique nodes: Map(3) {
  '6557243256474697731' => Node {
    uuid: '6557243256474697731',
    id: 'U4',
    schema: 'User',
    values: { name: 'mochaeach' }
  },
  '7926337543195328514' => Node {
    uuid: '7926337543195328514',
    id: 'U2',
    schema: 'User',
    values: { name: 'Brainy' }
  },
  '17870285520429383683' => Node {
    uuid: '17870285520429383683',
    id: 'U3',
    schema: 'User',
    values: { name: 'purplechalk' }
  }
}
Unique edges: Map(2) {
  '2' => Edge {
    uuid: '2',
    fromUuid: '6557243256474697731',
    toUuid: '7926337543195328514',
    from: 'U4',
    to: 'U2',
    schema: 'Follows',
    values: { createdOn: '2024-02-10' }
  },
  '3' => Edge {
    uuid: '3',
    fromUuid: '7926337543195328514',
    toUuid: '17870285520429383683',
    from: 'U2',
    to: 'U3',
    schema: 'Follows',
    values: { createdOn: '2024-02-01' }
  }
}
All paths: [
  Path {
    nodeUuids: [ '6557243256474697731', '7926337543195328514' ],
    edgeUuids: [ '2' ],
    nodes: Map(2) {
      '6557243256474697731' => [Node],
      '7926337543195328514' => [Node]
    },
    edges: Map(1) { '2' => [Edge] }
  },
  Path {
    nodeUuids: [ '7926337543195328514', '17870285520429383683' ],
    edgeUuids: [ '3' ],
    nodes: Map(2) {
      '7926337543195328514' => [Node],
      '17870285520429383683' => [Node]
    },
    edges: Map(1) { '3' => [Edge] }
  }
]

asGraphSets()

如果一个查询获取数据库中的图（图集），使用asGraphSets()将它们转换成一个GraphSet对象列表。

const response = await driver.gql("SHOW GRAPH");
const graphsets = response.get(0).asGraphSets();
for (const graphset of graphsets) {
  console.log(graphset.name)
}

g1
miniCircle
amz

asSchemas()

如果一个查询获取图中定义的点、边Schema，使用asSchemas()将它们转换成一个Schema对象列表。

const requestConfig: RequestConfig = { graph: "miniCircle" };
const response = await driver.gql("SHOW NODE SCHEMA", requestConfig);
const schemas = response.get(0).asSchemas();
for (const schema of schemas) {
  console.log(schema.name)
}

default
account
celebrity
country
movie

asProperties()

如果一个查询获取图中定义的点、边属性，使用asProperties()将它们转换成一个Property对象列表。

const requestConfig: RequestConfig = { graph: "miniCircle" };
const response = await driver.gql("SHOW NODE account PROPERTY", requestConfig);
const properties = response.get(0).asProperties();
for (const property of properties) {
  console.log(property.name)
}

_id
gender
year
industry
name

asAttr()

如果一个查询返回属性、表达式或计算结果等值，使用asAttr()将它们转换成一个Attr对象。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH (n:User) LIMIT 2 RETURN n.name", requestConfig);
const attr = response.alias("n.name").asAttr();
console.log(attr)

Attr {
  propertyType: 7,
  resultType: 4,
  values: [ 'mochaeach', 'Brainy' ],
  name: 'n.name'
}

asTable()

如果一个查询使用table()函数返回行和列，使用asTable()将它们转换成一个Table对象。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("MATCH (n:User) LIMIT 2 RETURN table(n._id, n.name) AS result", requestConfig);
const table = response.alias("result").asTable();
console.log(table)

Table {
  name: 'result',
  headers: [
    Header { propertyName: 'n._id', propertyType: 7 },
    Header { propertyName: 'n.name', propertyType: 7 }
  ],
  rows: [ [ 'U4', 'mochaeach' ], [ 'U2', 'Brainy' ] ]
}

asHDCGraphs()

如果一个查询获取一个图的HDC图，使用asHDCGraphs()将它们转换成一个HDCGraph对象列表。

const response = await driver.gql("SHOW HDC GRAPH ON 'hdc-server-1'");
const hdcGraphs = response.get(0).asHDCGraphs();
for (const hdcGraph of hdcGraphs) {
  console.log(hdcGraph.name)
}

g1_hdc_full
g1_hdc_nodes

asAlgos()

如果一个查询获取数据库中安装的算法，使用asAlgos()将它们转换成一个Algo对象列表。

const response = await driver.gql("SHOW HDC ALGO ON 'hdc-server-1'");
const algos = response.get(0).asAlgos();
for (const algo of algos) {
  if (algo.type === "algo") {
    console.log(algo.name)
  }
}

bipartite
fastRP

asProjections()

如果一个查询获取一个图的映射，使用asProjections()将它们转换成一个Projection对象列表。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("SHOW PROJECTION", requestConfig);
const projections = response.get(0).asProjections();
for (const projection of projections) {
  console.log(projection.name)
}

distG1
distG1_nodes

asIndexes()

如果一个查询获取图中点、边的索引，使用asIndexes()将它们转换成一个Index对象列表。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("SHOW NODE INDEX", requestConfig);
const indexes = response.get(0).asIndexes();
for (const index of indexes) {
  console.log(index)
}

Index {
  id: '1',
  name: 'User_name',
  properties: 'name(1024)',
  schema: 'User',
  status: 'DONE',
  size: undefined,
  dbType: 0
}

asPrivileges()

如果一个查询获取嬴图中定义的权限，使用asPrivileges()将它们转换成一个Privilege对象列表。

const response = await driver.uql("show().privilege()");
const privileges = response.get(0).asPrivileges();

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

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

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

asPolicies()

如果一个查询获取数据库中定义的策略（角色），使用asPolicies()将它们转换成一个Policy对象列表。

const response = await driver.gql("SHOW ROLE");
const policies = response.get(0).asPolicies();
for (const policy of policies) {
  console.log(policy.name)
}

manager
Tester
operator
superADM

asUsers()

如果一个查询获取数据库用户，使用asUsers()将它们转换成一个User对象列表。

const response = await driver.gql("SHOW USER");
const users = response.get(0).asUsers();
for (const user of users) {
  console.log(user.name)
}

user01
root
johndoe

asProcesses()

如果一个查询获取数据库中的进程，使用asProcesses()将它们转换成一个Process对象列表。

const response = await driver.gql("TOP");
const processes = response.get(0).asProcesses();
for (const process of processes) {
  console.log(process)
}

Process {
  processId: '1060719',
  processQuery: 'MATCH p = ()-{1,7}() RETURN p',
  duration: '1',
  status: 'RUNNING'
}

asJobs()

如果一个查询获取一个图的作业，使用asJobs()将它们转换成一个Job对象列表。

const requestConfig: RequestConfig = { graph: "g1" };
const response = await driver.gql("SHOW JOB", requestConfig);
const jobs = response.get(0).asJobs();
for (const job of jobs) {
  console.log(job)
}

Job {
  id: '5',
  graphName: 'g1',
  query: 'CREATE INDEX User_name ON NODE User (name)',
  type: 'CREATE_INDEX',
  errMsg: '',
  result: null,
  startTime: '2025-09-23 17:43:54',
  endTime: '2025-09-23 17:43:55',
  status: 'FINISHED',
  progress: ''
}
Job {
  id: '5_1',
  graphName: 'g1',
  query: '',
  type: 'CREATE_INDEX',
  errMsg: '',
  result: null,
  startTime: '2025-09-23 17:43:55',
  endTime: '2025-09-23 17:43:55',
  status: 'FINISHED',
  progress: ''
}
Job {
  id: '5_2',
  graphName: 'g1',
  query: '',
  type: 'CREATE_INDEX',
  errMsg: '',
  result: null,
  startTime: '2025-09-23 17:43:55',
  endTime: '2025-09-23 17:43:55',
  status: 'FINISHED',
  progress: ''
}
Job {
  id: '5_3',
  graphName: 'g1',
  query: '',
  type: 'CREATE_INDEX',
  errMsg: '',
  result: null,
  startTime: '2025-09-23 17:43:55',
  endTime: '2025-09-23 17:43:55',
  status: 'FINISHED',
  progress: ''
}
Job {
  id: '1',
  graphName: 'g1',
  query: 'CREATE HDC GRAPH g1_hdc_full ON "hdc-server-1" OPTIONS {\n' +
    '  nodes: {"*": ["*"]},\n' +
    '  edges: {"*": ["*"]},\n' +
    '  direction: "undirected",\n' +
    '  load_id: true,\n' +
    '  update: "static"\n' +
    '}',
  type: 'CREATE_HDC_GRAPH',
  errMsg: '',
  result: Map(4) {
    'edge_count' => 4,
    'edge_schema' => { Follows: [Object], default: [Object] },
    'node_count' => 5,
    'node_schema' => { User: [Object], default: [Object] }
  },
  startTime: '2025-09-23 17:29:05',
  endTime: '2025-09-23 17:29:07',
  status: 'FINISHED',
  progress: ''
}
Job {
  id: '1_1',
  graphName: 'g1',
  query: '',
  type: 'CREATE_HDC_GRAPH',
  errMsg: '',
  result: null,
  startTime: '2025-09-23 17:29:05',
  endTime: '2025-09-23 17:29:07',
  status: 'FINISHED',
  progress: ''
}

完整示例

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 = {
    // 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);

  const requestConfig: RequestConfig = { graph: "g1" };
  const response = await driver.gql("MATCH (n:User) RETURN n LIMIT 2", requestConfig);
  const nodes = response.alias("n").asNodes();
  for (const node of nodes) {
    console.log(node)
  };
};

sdkUsage().catch(console.error);