@ohos.data.graphStore (Graph Database) (System API)

A graph database (GDB) is a data management system designed to efficiently store and query graph data. It organizes data as vertexes and edges. The graphStore module provides a complete set of mechanisms for local GDB management. It provides read (query), write (add, delete, and modify), and transaction management APIs that can directly run the Graph Query Language (GQL) statements to store, query, and analyze highly interconnected data.

• Vertex: represents an entity or instance, such as a person, enterprise, account, or any other item to be tracked. It is equivalent to a record, relationship, or row in a relational database, or a document in a document database.
• Edge: represents the relationship between vertexes. Edge is a unique data abstraction exclusive to GDB, and must be materialized at runtime when queried.
• Path: a sequence of vertices and edges in a certain sequence.
• PathSegment: an edge along with its start and end vertexes in a path.

The graphStore module provides the following functionalities:

• GraphStore: provides APIs for manipulating a GDB.
• Result: provides the result returned by the read() or write() API.
• Transaction: provides APIs for managing transaction objects.

NOTE

• The initial APIs of this module are supported since API version 18. Newly added APIs will be marked with a superscript to indicate their earliest API version.
• The current page contains only the system interfaces of this module.

Modules to Import

import { graphStore } from '@kit.ArkData';

graphStore.getStore

getStore(context: Context, config: StoreConfig): Promise<GraphStore>

Obtains a GraphStore instance for GDB operations. You can set parameters for the instance as required and call related APIs through this instance to perform data operations. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: graphStore.GraphStore|null = null;

class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    const STORE_CONFIG: graphStore.StoreConfig = {
      name: "testGraphDb",
      securityLevel: graphStore.SecurityLevel.S2
    };

    graphStore.getStore(this.context, STORE_CONFIG).then(async (gdb: graphStore.GraphStore) => {
      store = gdb;
      console.info('Get GraphStore successfully.');
    }).catch((err: BusinessError) => {
      console.error(`Get GraphStore failed, code is ${err.code}, message is ${err.message}`);
    })
  }
}

graphStore.deleteStore

deleteStore(context: Context, config: StoreConfig): Promise<void>

Deletes a graph store. This API uses a promise to return the result.

Before calling this API, call close to close the graph store to be deleted. After the deletion, you are advised to set the graph store instance to null.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

let store: graphStore.GraphStore|null = null;

const STORE_CONFIG: graphStore.StoreConfig = {
  name: "testGraphDb",
  securityLevel: graphStore.SecurityLevel.S2
};

class EntryAbility extends UIAbility {
  onWindowStageDestroy() {
    graphStore.deleteStore(this.context, STORE_CONFIG).then(() => {
      store = null;
      console.info('Delete GraphStore successfully.');
    }).catch((err: BusinessError) => {
      console.error(`Delete GraphStore failed, code is ${err.code},message is ${err.message}`);
    })
  }
}

StoreConfig

Represents the configuration of a graph store.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

SecurityLevel

Enumerates the graph store security levels. Use the enum name rather than the enum value.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

ValueType

type ValueType = null|number|string

Represents the allowed value types. The value type varies, depending on its usage.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Vertex

Represents information about a vertex. Vertex is used only as the type in the return value (Result) and cannot be customized. You can use read to obtain its value.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Edge

Represents information about an edge. Edge is used only as the type in the return value (Result) and cannot be customized. You can use read to obtain its value.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

PathSegment

Represents information about a path segment, including the edge along with the start and end vertexes. PathSegment is used only as the type of the return value (Path.segments) and cannot be customized. You can use the read API to obtain related information.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Path

Represents information about a path. Path is used only as the type in the return value (Result) and cannot be customized. You can use read to obtain its value.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Result

Represents the GQL statement execution result.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Transaction

Provides APIs for transaction management in a graph store.

Operations on different transaction objects are isolated. The graph stores use database-level locks. If commit or rollback is not called after a transaction is written using write, calling read or write for another transaction instance or calling GraphStore.read or GraphStore.write with the GraphStore instance will return error 31300003. If commit or rollback is not called after read is called for a transaction, calling write for another transaction instance or calling GraphStore.write with the GraphStore instance will return error 31300003.

Before calling any Transaction API, you must create a transaction instance using createTransaction.

read

read(gql: string): Promise<Result>

Reads data, which includes the data written by using GraphStore.write, data written by another transaction using write and committed by using commit, and data written by the current transaction using write.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

const QUERY_PATH_GQL = "MATCH path=(a:Person {name : \'name_1\'})-[]->{2, 2}(b:Person {name : \'name_3\'}) RETURN path;";
if(transaction != undefined) {
  (transaction as graphStore.Transaction).read(QUERY_PATH_GQL).then((result: graphStore.Result) => {
    console.info('Read successfully');
    result.records?.forEach((data) => {
      for (let item of Object.entries(data)) {
        const key = item[0];
        const value = item[1];
        const path = value as graphStore.Path;
        console.info(`key : ${key}, path.length : ${path.length}`);
      }
    });
  }).catch((err: BusinessError) => {
    console.error(`Read failed, code is ${err.code}, message is ${err.message}`);
  })
}

write

write(gql: string): Promise<Result>

Writes data. You can use this API to add, delete, and modify data. Currently, it cannot be used to modify the table structure (types or properties of Vertex and Edge), create or delete graphs or indexes. This API cannot be used to execute transaction operation statements, including START TRANSACTION, COMMIT, and ROLLBACK.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

const INSERT_GQL = "INSERT (:Person {name: 'name_1', age: 11});";
if(transaction != undefined) {
  (transaction as graphStore.Transaction).write(INSERT_GQL).then(() => {
    console.info('Write successfully');
  }).catch((err: BusinessError) => {
    console.error(`Write failed, code is ${err.code}, message is ${err.message}`);
  })
}

commit

commit(): Promise<void>

Commits the GQL statements executed in this transaction. After the commit, the transaction will be no longer available.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

if(transaction != undefined) {
  (transaction as graphStore.Transaction).commit().then(() => {
    console.info(`Commit successfully`);
  }).catch ((err: BusinessError) => {
    console.error(`Commit failed, code is ${err.code}, message is ${err.message}`);
  })
}

rollback

rollback(): Promise<void>

Rolls back the GQL statements executed in this transaction. After the rollback, the transaction will be no longer available.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

if(transaction != undefined) {
  (transaction as graphStore.Transaction).rollback().then(() => {
    console.info(`Rollback successfully`);
  }).catch ((err: BusinessError) => {
    console.error(`Rollback failed, code is ${err.code}, message is ${err.message}`);
  })
}

GraphStore

Provides APIs for managing the data in a graph store.

Before calling any GraphStore API, you must create a GraphStore instance by using getStore.

read

read(gql: string): Promise<Result>

Reads data, which includes the data written by using write and the data written by using Transaction.write and committed by Transaction.commit in all transactions.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

const QUERY_PATH_GQL = "MATCH path=(a:Person {name : \'name_1\'})-[]->{2, 2}(b:Person {name : \'name_3\'}) RETURN path;";
if(store != null) {
  (store as graphStore.GraphStore).read(QUERY_PATH_GQL).then((result: graphStore.Result) => {
    console.info('Read successfully');
    result.records?.forEach((data) => {
      for (let item of Object.entries(data)) {
        const key = item[0];
        const value = item[1];
        const path = value as graphStore.Path;
        console.info(`key : ${key}, path.length : ${path.length}`);
      }
    });
  }).catch((err: BusinessError) => {
    console.error(`Read failed, code is ${err.code}, message is ${err.message}`);
  })
}

write

write(gql: string): Promise<Result>

Writes data. You can use this API to create or delete a graph, and add, delete, or modify data. Currently, the table structure (types or properties of Vertex and Edge) cannot be modified. This API cannot be used to execute transaction operation statements, including START TRANSACTION, COMMIT, and ROLLBACK.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Parameters

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

const CREATE_GRAPH_GQL = "CREATE GRAPH test { (person:Person {name STRING, age INT}),(person)-[:Friend {year INT}]->(person) };"
if(store != null) {
  (store as graphStore.GraphStore).write(CREATE_GRAPH_GQL).then(() => {
    console.info('Write successfully');
  }).catch((err: BusinessError) => {
    console.error(`Write failed, code is ${err.code}, message is ${err.message}`);
  })
}

createTransaction

createTransaction(): Promise<Transaction>

Creates a transaction instance. Currently, a maximum of four transaction instances can be created at a time in a graph store.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let transaction: graphStore.Transaction|undefined = undefined;

if(store != null) {
  (store as graphStore.GraphStore).createTransaction().then((trans: graphStore.Transaction) => {
    transaction = trans;
    console.info('createTransaction successfully');
  }).catch((err: BusinessError) => {
    console.error(`createTransaction failed, code is ${err.code}, message is ${err.message}`);
  })
}

close

close(): Promise<void>

Closes this graph store. After this API is called, uncommitted transactions will be rolled back.

System capability: SystemCapability.DistributedDataManager.DataIntelligence.Core

Return value

Error codes

For details about the error codes, see Universal Error Codes and Graph Store Error Codes.

Example

import { BusinessError } from '@kit.BasicServicesKit';

if(store != null) {
  (store as graphStore.GraphStore).close().then(() => {
    console.info(`Close successfully`);
  }).catch ((err: BusinessError) => {
    console.error(`Close failed, code is ${err.code}, message is ${err.message}`);
  })
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (ArkData Management)

harmony 鸿蒙Data

harmony 鸿蒙OH_Cursor

harmony 鸿蒙OH_Predicates

harmony 鸿蒙OH_Rdb_Config

harmony 鸿蒙OH_Rdb_Store

harmony 鸿蒙OH_VBucket

harmony 鸿蒙OH_VObject

harmony 鸿蒙Preferences

harmony 鸿蒙_r_d_b