Distributed Data Management

The distributed data management module implements collaboration between databases of different devices for applications. The APIs provided by distributed data management can be used to save data to distributed databases and perform operations such as adding, deleting, modifying, querying, and synchronizing data in distributed databases.

This module provides the following functions:

• KVManager: provides a KVManager instance to manage key-value (KV) stores.
• KvStoreResultSet⁸⁺: provides methods to obtain the KV store result set and query or move the data read position.
• Query⁸⁺: provides methods to query data from the database through a Query instance by using predicates.
• KVStore: provides methods to add data, delete data, and observe data changes and data synchronization through a KVStore instance.
• SingleKVStore: provides methods to query and synchronize data in a single KV store. This class inherits from KVStore, and data is not distinguished by device.
• DeviceKVStore⁸⁺ : provides methods to query and synchronize data in a device KV store. This class inherits from KVStore, and data is distinguished by device.

NOTE

The initial APIs of this module are supported since API version 7. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import distributedData from '@ohos.data.distributedData';

distributedData.createKVManager

createKVManager(config: KVManagerConfig, callback: AsyncCallback<KVManager>): void

Creates a KVManager instance to manage KV stores. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
config	KVManagerConfig	Yes	Configuration of the KVManager instance, including the bundle name and user information of the caller.
callback	AsyncCallback<KVManager>	Yes	Callback invoked to return the KVManager instance created.

Example

Stage model:

import AbilityStage from '@ohos.application.Ability'
let kvManager;
export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    console.log("MyAbilityStage onCreate")
    let context = this.context
    const kvManagerConfig = {
      context: context,
      bundleName: 'com.example.datamanagertest',
      userInfo: {
        userId: '0',
        userType: distributedData.UserType.SAME_USER_ID
      }
    }
    distributedData.createKVManager(kvManagerConfig, function (err, manager) {
      if (err) {
        console.log("Failed to create KVManager: " + JSON.stringify(err));
        return;
      }
      console.log("Created KVManager");
      kvManager = manager;
    });
  }
}

FA model:

import AbilityStage from '@ohos.application.Ability'
let kvManager;
export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    console.log("MyAbilityStage onCreate")
    let context = this.context
    const kvManagerConfig = {
      context: context.getApplicationContext(),
      bundleName: 'com.example.datamanagertest',
      userInfo: {
        userId: '0',
        userType: distributedData.UserType.SAME_USER_ID
      }
    }
    distributedData.createKVManager(kvManagerConfig, function (err, manager) {
      if (err) {
        console.log("Failed to create KVManager: " + JSON.stringify(err));
        return;
      }
      console.log("Created KVManager");
      kvManager = manager;
    });
  }
}

distributedData.createKVManager

createKVManager(config: KVManagerConfig): Promise<KVManager>

Creates a KVManager instance to manage KV stores. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
config	KVManagerConfig	Yes	Configuration of the KVManager instance, including the bundle name and user information of the caller.

Return value

Type	Description
Promise<KVManager>	Promise used to return the KVManager instance created.

Example

Stage model:

import AbilityStage from '@ohos.application.Ability'
let kvManager;
export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    console.log("MyAbilityStage onCreate")
    let context = this.context
    const kvManagerConfig = {
      context: context,
      bundleName: 'com.example.datamanagertest',
      userInfo: {
        userId: '0',
        userType: distributedData.UserType.SAME_USER_ID
      }
    }
    distributedData.createKVManager(kvManagerConfig, function (err, manager) {
      if (err) {
        console.log("Failed to create KVManager: " + JSON.stringify(err));
        return;
      }
      console.log("Created KVManager");
      kvManager = manager;
    });
  }
}

FA model:

import AbilityStage from '@ohos.application.Ability'
let kvManager;
export default class MyAbilityStage extends AbilityStage {
  onCreate() {
    console.log("MyAbilityStage onCreate")
    let context = this.context
    const kvManagerConfig = {
      context: context.getApplicationContext(),
      bundleName: 'com.example.datamanagertest',
      userInfo: {
        userId: '0',
        userType: distributedData.UserType.SAME_USER_ID
      }
    }
    distributedData.createKVManager(kvManagerConfig, function (err, manager) {
      if (err) {
        console.log("Failed to create KVManager: " + JSON.stringify(err));
        return;
      }
      console.log("Created KVManager");
      kvManager = manager;
    });
  }
}

KVManagerConfig

Provides configuration of the KVManager object, including the bundle name and user information of the caller.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Type	Mandatory	Description
context9+	Context	Yes	Application context. For the application context of the FA model, see Context. For the application context of the stage model, see Context.
userInfo	UserInfo	Yes	User information.
bundleName	string	Yes	Bundle name.

UserInfo

Defines user information.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Type	Mandatory	Description
userId	string	Yes	User ID.
userType	UserType	Yes	User type.

UserType

Enumerates the user types.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Value	Description
SAME_USER_ID	0	User who logs in to different devices using the same account.

KVManager

Creates a KVManager object to obtain KV store information. Before calling any method in KVManager, you must use createKVManager to create a KVManager object.

getKVStore

getKVStore<T extends KVStore>(storeId: string, options: Options, callback: AsyncCallback<T>): void

Creates and obtains a KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
storeId	string	Yes	Unique identifier of the KV store. The length cannot exceed MAX_STORE_ID_LENGTH.
options	Options	Yes	Configuration of the KV store.
callback	AsyncCallback<T> , <T extends KVStore>	Yes	Callback invoked to return the KV store created.

Example

let kvStore;
let kvManager;
try {
    const options = {
        createIfMissing : true,
        encrypt : false,
        backup : false,
        autoSync : true,
        kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
        securityLevel : distributedData.SecurityLevel.S2,
    };
    kvManager.getKVStore('storeId', options, function (err, store) {
        if (err) {
            console.log("getKVStore err: "  + JSON.stringify(err));
            return;
        }
        console.log("getKVStore success");
        kvStore = store;
    });
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

getKVStore

getKVStore<T extends KVStore>(storeId: string, options: Options): Promise<T>

Creates and obtains a KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
storeId	string	Yes	Unique identifier of the KV store. The length cannot exceed MAX_STORE_ID_LENGTH.
options	Options	Yes	Configuration of the KV store.

Return value

Type	Description
Promise<T>, <T extends KVStore>	Promise used to return the KV store created.

Example

let kvStore;
let kvManager;
try {
    const options = {
        createIfMissing : true,
        encrypt : false,
        backup : false,
        autoSync : true,
        kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
        securityLevel : distributedData.SecurityLevel.S2,
    };
    kvManager.getKVStore('storeId', options).then((store) => {
        console.log("getKVStore success");
        kvStore = store;
    }).catch((err) => {
        console.log("getKVStore err: "  + JSON.stringify(err));
    });
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

closeKVStore⁸⁺

closeKVStore(appId: string, storeId: string, kvStore: KVStore, callback: AsyncCallback<void>): void

Closes a KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Bundle name of the app that invokes the KV store.
storeId	string	Yes	Unique identifier of the KV store to close. The length cannot exceed MAX_STORE_ID_LENGTH.
kvStore	KVStore	Yes	KV store to close.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
let kvManager;
const options = {
    createIfMissing : true,
    encrypt : false,
    backup : false,
    autoSync : true,
    kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
    schema : '',
    securityLevel : distributedData.SecurityLevel.S2,
 }
 try {
    kvManager.getKVStore('storeId', options, async function (err, store) {
    console.log('getKVStore success');
    kvStore = store;
    kvManager.closeKVStore('appId', 'storeId', kvStore, function (err, data) {
        console.log('closeKVStore success');
    });
    });
} catch (e) {
    console.log('closeKVStore e ' + e);
}

closeKVStore⁸⁺

closeKVStore(appId: string, storeId: string, kvStore: KVStore): Promise<void>

Closes a KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Bundle name of the app that invokes the KV store.
storeId	string	Yes	Unique identifier of the KV store to close. The length cannot exceed MAX_STORE_ID_LENGTH.
kvStore	KVStore	Yes	KV store to close.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvManager;
let kvStore;
const options = {
    createIfMissing : true,
    encrypt : false,
    backup : false,
    autoSync : true,
    kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
    schema : '',
    securityLevel : distributedData.SecurityLevel.S2,
}
 try {
    kvManager.getKVStore('storeId', options).then(async (store) => {
    console.log('getKVStore success');
    kvStore = store;
    kvManager.closeKVStore('appId', 'storeId', kvStore).then(() => {
        console.log('closeKVStore success');
    }).catch((err) => {
        console.log('closeKVStore err ' + JSON.stringify(err));
    });
    }).catch((err) => {
        console.log('CloseKVStore getKVStore err ' + JSON.stringify(err));
    });
 } catch (e) {
    console.log('closeKVStore e ' + e);
}  

deleteKVStore⁸⁺

deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void

Deletes a KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Bundle name of the app that invokes the KV store.
storeId	string	Yes	Unique identifier of the KV store to delete. The length cannot exceed MAX_STORE_ID_LENGTH.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvManager;
let kvStore;
const options = {
    createIfMissing : true,
    encrypt : false,
    backup : false,
    autoSync : true,
    kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
    schema : '',
    securityLevel : distributedData.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('store', options, async function (err, store) {
        console.log('getKVStore success');
        kvStore = store;
        kvManager.deleteKVStore('appId', 'storeId', function (err, data) {
            console.log('deleteKVStore success');
        });
    });
} catch (e) {
    console.log('DeleteKVStore e ' + e);
}

deleteKVStore⁸⁺

deleteKVStore(appId: string, storeId: string): Promise<void>

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

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Bundle name of the app that invokes the KV store.
storeId	string	Yes	Unique identifier of the KV store to delete. The length cannot exceed MAX_STORE_ID_LENGTH.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvManager;
let kvStore;
const options = {
    createIfMissing : true,
    encrypt : false,
    backup : false,
    autoSync : true,
    kvStoreType : distributedData.KVStoreType.SINGLE_VERSION,
    schema : '',
    securityLevel : distributedData.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options).then(async (store) => {
        console.log('getKVStore success');
        kvStore = store;
        kvManager.deleteKVStore('appId', 'storeId').then(() => {
            console.log('deleteKVStore success');
        }).catch((err) => {
            console.log('deleteKVStore err ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('getKVStore err ' + JSON.stringify(err));
    });
} catch (e) {
    console.log('deleteKVStore e ' + e);
}

getAllKVStoreId⁸⁺

getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void

Obtains the IDs of all KV stores that are created by getKVStore() and have not been deleted by deleteKVStore(). This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Bundle name of the app that invokes the KV store.
callback	AsyncCallback<string[]>	Yes	Callback used to return the KV store IDs obtained.

Example

let kvManager;
try {
    kvManager.getAllKVStoreId('appId', function (err, data) {
        console.log('GetAllKVStoreId success');
        console.log('GetAllKVStoreId size = ' + data.length);
    });
} catch (e) {
    console.log('GetAllKVStoreId e ' + e);
}

getAllKVStoreId⁸⁺

getAllKVStoreId(appId: string): Promise<string[]>

Obtains the IDs of all KV stores that are created by getKVStore() and have not been deleted by deleteKVStore(). This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
appId	string	Yes	Bundle name of the app that invokes the KV store.

Return value

Type	Description
Promise<string[]>	Promise used to return the KV store IDs obtained.

Example

let kvManager;
try {
    console.log('GetAllKVStoreId');
    kvManager.getAllKVStoreId('appId').then((data) => {
        console.log('getAllKVStoreId success');
        console.log('size = ' + data.length);
    }).catch((err) => {
        console.log('getAllKVStoreId err ' + JSON.stringify(err));
    });
} catch(e) {
    console.log('getAllKVStoreId e ' + e);
}

on(‘distributedDataServiceDie’)⁸⁺

on(event: ‘distributedDataServiceDie’, deathCallback: Callback<void>): void

Subscribes to service status changes.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is distributedDataServiceDie, which indicates service status changes.
deathCallback	Callback<void>	Yes	Callback invoked to return service status changes.

Example

let kvManager;
try {
    
    console.log('KVManagerOn');
    const deathCallback = function () {
        console.log('death callback call');
    }
    kvManager.on('distributedDataServiceDie', deathCallback);
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

off(‘distributedDataServiceDie’)⁸⁺

off(event: ‘distributedDataServiceDie’, deathCallback?: Callback<void>): void

Unsubscribes from the service status changes.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is distributedDataServiceDie, which indicates service status changes.
deathCallback	Callback<void>	No	Callback used to return service status changes.

Example

let kvManager;
try {
    console.log('KVManagerOff');
    const deathCallback = function () {
        console.log('death callback call');
    }
    kvManager.off('distributedDataServiceDie', deathCallback);
} catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}
    

Options

Provides KV store configuration.

Name	Type	Mandatory	Description
createIfMissing	boolean	No	Whether to create a KV store if no database file exists. By default, a KV store is created. System capability: SystemCapability.DistributedDataManager.KVStore.Core
encrypt	boolean	No	Whether to encrypt database files. By default, database files are not encrypted. System capability: SystemCapability.DistributedDataManager.KVStore.Core
backup	boolean	No	Whether to back up database files. By default, database files are backed up. System capability: SystemCapability.DistributedDataManager.KVStore.Core
autoSync	boolean	No	Whether database files are automatically synchronized. By default, database files are not automatically synchronized. System capability: SystemCapability.DistributedDataManager.KVStore.Core Required permissions: ohos.permission.DISTRIBUTED_DATASYNC
kvStoreType	KVStoreType	No	Type of the KV store to create. By default, a device KV store is created. The device KV store stores data for multiple devices that collaborate with each other. System capability: SystemCapability.DistributedDataManager.KVStore.Core
securityLevel	SecurityLevel	No	Security level of the KV store. By default, the security level is not set. System capability: SystemCapability.DistributedDataManager.KVStore.Core
schema8+	Schema	No	Schema used to define the values stored in a KV store. System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

KVStoreType

Enumerates the KV store types.

Name	Value	Description
DEVICE_COLLABORATION	0	Device KV store. System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
SINGLE_VERSION	1	Single KV store. System capability: SystemCapability.DistributedDataManager.KVStore.Core
MULTI_VERSION	2	Multi-version KV store. This type is not supported currently. System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

SecurityLevel

Enumerates the KV store security levels.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Value	Description
NO_LEVEL	0	No security level is set for the KV store.
S0	1	The KV store security level is public.
S1	2	The KV store security level is low. If data leakage occurs, minor impact will be caused on the database. For example, a KV store that contains system data such as wallpapers.
S2	3	The KV store security level is medium. If data leakage occurs, moderate impact will be caused on the database. For example, a KV store that contains information created by users or call records, such as audio or video clips.
S3	5	The KV store security level is high. If data leakage occurs, major impact will be caused on the database. For example, a KV store that contains information such as user fitness, health, and location data.
S4	6	The KV store security level is critical. If data leakage occurs, severe impact will be caused on the database. For example, a KV store that contains information such as authentication credentials and financial data.

Constants

Defines the KV store constants.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Value	Description
MAX_KEY_LENGTH	1024	Maximum length of a key in the KV store, in bytes.
MAX_VALUE_LENGTH	4194303	Maximum length of a value in the KV store, in bytes.
MAX_KEY_LENGTH_DEVICE	896	Maximum length of a device key, in bytes.
MAX_STORE_ID_LENGTH	128	Maximum length of a KV store ID, in bytes.
MAX_QUERY_LENGTH	512000	Maximum query length, in bytes.
MAX_BATCH_SIZE	128	Maximum number of batch operations.

Schema⁸⁺

Defines the schema of a KV store. You can create a Schema object and place it in Options when creating or opening a KV store.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Name	Type	Description
root8+	FieldNode	JSON root object.
indexes8+	Array<string>	String array in JSON format.
mode8+	number	Schema mode.
skip8+	number	Size of a skip of the schema.

constructor⁸⁺

constructor()

A constructor used to create a Schema instance.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

FieldNode⁸⁺

Represents a Schema instance, which provides the methods for defining the values stored in a KV store.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Name	Type	Description
nullable8+	boolean	Whether the database field can be null.
default8+	string	Default value of a FieldNode.
type8+	number	Value of the data type corresponding to the specified node.

constructor⁸⁺

constructor(name: string)

A constructor used to create a FieldNode instance with a string field.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
name	string	Yes	Value of FieldNode.

appendChild⁸⁺

appendChild(child: FieldNode): boolean

Appends a child node to this FieldNode.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
child	FieldNode	Yes	Child node to append.

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

import ddm from '@ohos.data.distributedData';
try {
    let node = new ddm.FieldNode("root");
    let child1 = new ddm.FieldNode("child1");
    let child2 = new ddm.FieldNode("child2");
    let child3 = new ddm.FieldNode("child3");
    node.appendChild(child1);
    node.appendChild(child2);
    node.appendChild(child3);
    console.log("appendNode " + JSON.stringify(node));
    child1 = null;
    child2 = null;
    child3 = null;
    node = null;
} catch (e) {
    console.log("AppendChild " + e);
}

KvStoreResultSet⁸⁺

Provides methods to obtain the KV store result sets, and query and move the data read position.

Before calling any method in KvStoreResultSet, you must use getKVStore to obtain a KVStore object.

getCount⁸⁺

getCount(): number

Obtains the total number of rows in the result set.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
number	Total number of rows obtained.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const count = resultSet.getCount();
    console.log("getCount succeed:" + count);
} catch (e) {
    console.log("getCount failed: " + e);
}

getPosition⁸⁺

getPosition(): number

Obtains the current data read position (position from which data is read) in the result set.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
number	Current data read position obtained.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeeded.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const position = resultSet.getPosition();
    console.log("getPosition succeed:" + position);
} catch (e) {
    console.log("getPosition failed: " + e);
}

moveToFirst⁸⁺

moveToFirst(): boolean

Moves the data read position to the first row. If the result set is empty, false will be returned.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved1 = resultSet.moveToFirst();
    console.log("moveToFirst succeed: " + moved1);
} catch (e) {
    console.log("moveToFirst failed " + e);
}

moveToLast⁸⁺

moveToLast(): boolean

Moves the data read position to the last row. If the result set is empty, false will be returned.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved2 = resultSet.moveToLast();
    console.log("moveToLast succeed:" + moved2);
} catch (e) {
    console.log("moveToLast failed: " + e);
}

moveToNext⁸⁺

moveToNext(): boolean

Moves the data read position to the next row. If the result set is empty, false will be returned.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved3 = resultSet.moveToNext();
    console.log("moveToNext succeed: " + moved3);
} catch (e) {
    console.log("moveToNext failed: " + e);
}

moveToPrevious⁸⁺

moveToPrevious(): boolean

Moves the data read position to the previous row. If the result set is empty, false will be returned.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved4 = resultSet.moveToPrevious();
    console.log("moveToPrevious succeed:" + moved4);
} catch (e) {
    console.log("moveToPrevious failed: " + e);
}

move⁸⁺

move(offset: number): boolean

Moves the data read position with the specified offset from the current position.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
offset	number	Yes	Offset to move the data read position. A negative value means to move backward, and a positive value means to move forward.

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved5 = resultSet.move();
    console.log("move succeed:" + moved5);
} catch (e) {
    console.log("move failed: " + e);
}

moveToPosition⁸⁺

moveToPosition(position: number): boolean

Moves the data read position from 0 to an absolute position.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
position	number	Yes	Absolute position to move to.

Return value

Type	Description
boolean	Returns true if the operation is successful; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const moved6 = resultSet.moveToPosition();
    console.log("moveToPosition succeed: " + moved6);
} catch (e) {
    console.log("moveToPosition failed: " + e);
}

isFirst⁸⁺

isFirst(): boolean

Checks whether the data read position is the first row.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the first row is being read; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const isfirst = resultSet.isFirst();
    console.log("Check isFirst succeed:" + isfirst);
} catch (e) {
    console.log("Check isFirst failed: " + e);
}

isLast⁸⁺

isLast(): boolean

Checks whether the data read position is the last row.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the last row is being read; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const islast = resultSet.isLast();
    console.log("Check isLast succeed: " + islast);
} catch (e) {
    console.log("Check isLast failed: " + e);
}

isBeforeFirst⁸⁺

isBeforeFirst(): boolean

Checks whether the data read position is before the first row.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the data read position is before the first row; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const isbeforefirst = resultSet.isBeforeFirst();
    console.log("Check isBeforeFirst succeed: " + isbeforefirst);
} catch (e) {
    console.log("Check isBeforeFirst failed: " + e);
}

isAfterLast⁸⁺

isAfterLast(): boolean

Checks whether the data read position is after the last row.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
boolean	Returns true if the data read position is after the last row; returns false otherwise.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const isafterlast = resultSet.isAfterLast();
    console.log("Check isAfterLast succeed:" + isafterlast);
} catch (e) {
    console.log("Check isAfterLast failed: " + e);
}

getEntry⁸⁺

getEntry(): Entry

Obtains the KV pair from the current position.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Entry	KV pair obtained.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + err);
    });
    const entry  = resultSet.getEntry();
    console.log("getEntry succeed:" + JSON.stringify(entry));
} catch (e) {
    console.log("getEntry failed: " + e);
}

Query⁸⁺

Provides methods to create a Query object, which defines different data query criteria.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

constructor⁸⁺

constructor()

A constructor used to create a Schema instance.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

reset⁸⁺

reset(): Query

Resets the Query object.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Query	Query object reset.

Example

try {
    let query = new distributedData.Query();
    query.equalTo("key", "value");
    console.log("query is " + query.getSqlLike());
    query.reset();
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("simply calls should be ok :" + e);
}

equalTo⁸⁺

equalTo(field: string, value: number|string|boolean): Query

Creates a Query object to match the specified field whose value is equal to the given value.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	number|string|boolean	Yes	Value specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.equalTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

notEqualTo⁸⁺

notEqualTo(field: string, value: number|string|boolean): Query

Creates a Query object to match the specified field whose value is not equal to the specified value.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	number|string|boolean	Yes	Value specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

greaterThan⁸⁺

greaterThan(field: string, value: number|string|boolean): Query

Creates a Query object to match the specified field whose value is greater than the specified value.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	number|string|boolean	Yes	Value specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.greaterThan("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

lessThan⁸⁺

lessThan(field: string, value: number|string): Query

Creates a Query object to match the specified field whose value is less than the specified value.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	number|string|boolean	Yes	Value specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.lessThan("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

greaterThanOrEqualTo⁸⁺

greaterThanOrEqualTo(field: string, value: number|string): Query

Creates a Query object to match the specified field whose value is greater than or equal to the specified value.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	number|string|boolean	Yes	Value specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.greaterThanOrEqualTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

lessThanOrEqualTo⁸⁺

lessThanOrEqualTo(field: string, value: number|string): Query

Creates a Query object to match the specified field whose value is less than or equal to the specified value.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	number|string|boolean	Yes	Value specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.lessThanOrEqualTo("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

isNull⁸⁺

isNull(field: string): Query

Creates a Query object to match the specified field whose value is null.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.isNull("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

inNumber⁸⁺

inNumber(field: string, valueList: number[]): Query

Creates a Query object to match the specified field whose value is within the specified list of numbers.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
valueList	number[]	Yes	List of numbers.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.inNumber("field", [0, 1]);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

inString⁸⁺

inString(field: string, valueList: string[]): Query

Creates a Query object to match the specified field whose value is within the specified list of strings.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
valueList	string[]	Yes	List of strings.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.inString("field", ['test1', 'test2']);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

notInNumber⁸⁺

notInNumber(field: string, valueList: number[]): Query

Creates a Query object to match the specified field whose value is not within the specified list of numbers.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
valueList	number[]	Yes	List of numbers.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.notInNumber("field", [0, 1]);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

notInString⁸⁺

notInString(field: string, valueList: string[]): Query

Creates a Query object to match the specified field whose value is not within the specified list of strings.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
valueList	string[]	Yes	List of strings.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.notInString("field", ['test1', 'test2']);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

like⁸⁺

like(field: string, value: string): Query

Creates a Query object to match the specified field whose value is similar to the specified string.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	string	Yes	String specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.like("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

unlike⁸⁺

unlike(field: string, value: string): Query

Creates a Query object to match the specified field whose value is not similar to the specified string.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.
value	string	Yes	String specified.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.unlike("field", "value");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

and⁸⁺

and(): Query

Creates a Query object with the AND condition.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Query	Query object Created.

Example

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value1");
    query.and();
    query.notEqualTo("field", "value2");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

or⁸⁺

or(): Query

Creates a Query object with the OR condition.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Query	Query object Created.

Example

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value1");
    query.or();
    query.notEqualTo("field", "value2");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

orderByAsc⁸⁺

orderByAsc(field: string): Query

Creates a Query object to sort the query results in ascending order.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    query.orderByAsc("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

orderByDesc⁸⁺

orderByDesc(field: string): Query

Creates a Query object to sort the query results in descending order.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    query.orderByDesc("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

limit⁸⁺

limit(total: number, offset: number): Query

Creates a Query object to specify the number of results and where to start.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
total	number	Yes	Number of results to query.
offset	number	Yes	Start position for query.

Return value

Type	Description
Query	Query object created.

Example

let total = 10;
let offset = 1;
try {
    let query = new distributedData.Query();
    query.notEqualTo("field", "value");
    query.limit(total, offset);
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

isNotNull⁸⁺

isNotNull(field: string): Query

Creates a Query object to match the specified field whose value is not null.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
fieId	string	Yes	Field to match. It cannot contain ‘^’.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.isNotNull("field");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

beginGroup⁸⁺

beginGroup(): Query

Creates a Query object for a query condition group with a left parenthesis.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.beginGroup();
    query.isNotNull("field");
    query.endGroup();
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

endGroup⁸⁺

endGroup(): Query

Creates a Query object for a query condition group with a right parenthesis.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.beginGroup();
    query.isNotNull("field");
    query.endGroup();
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

prefixKey⁸⁺

prefixKey(prefix: string): Query

Creates a Query object with a specified key prefix.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
prefix	string	Yes	Key prefix.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.prefixKey("$.name");
    query.prefixKey("0");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
    console.log("duplicated calls should be ok :" + e);
}

setSuggestIndex⁸⁺

setSuggestIndex(index: string): Query

Creates a Query object with an index preferentially used for query.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
index	string	Yes	Index preferentially used for query.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.setSuggestIndex("$.name");
    query.setSuggestIndex("0");
    console.log("query is " + query.getSqlLike());
    query = null;
} catch (e) {
   console.log("duplicated calls should be ok :" + e);
}

deviceId⁸⁺

deviceId(deviceId:string):Query

Creates a Query object with the device ID as the key prefix.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	Device ID.

Return value

Type	Description
Query	Query object created.

Example

try {
    let query = new distributedData.Query();
    query.deviceId("deviceId");
    console.log("query is " + query.getSqlLike());
} catch (e) {
    console.log("should be ok on Method Chaining : " + e);
}

getSqlLike⁸⁺

getSqlLike():string

Obtains the query statement of the Query object.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
string	Returns the query statement obtained.

Example

try {
    let query = new distributedData.Query();
    let sql1 = query.getSqlLike();
    console.log("GetSqlLike sql=" + sql1);
} catch (e) {
    console.log("duplicated calls should be ok : " + e);
}

KVStore

Provides methods to manage data in a KV store, for example, adding or deleting data and subscribing to data changes or completion of data synchronization.

Before calling any method in KVStore, you must use getKVStore to obtain a KVStore object.

put

put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void

Adds a KV pair of the specified type to this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to add. It cannot be empty, and the length cannot exceed MAX_KEY_LENGTH.
value	Uint8Array | string | number | boolean	Yes	Value of the KV pair to add. The value type can be Uint8Array, number, string, or boolean. A value of the Uint8Array or string type cannot exceed MAX_VALUE_LENGTH.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) {
        if (err != undefined) {
            console.log("put err: " + JSON.stringify(err));
            return;
        }
        console.log("put success");
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

put

put(key: string, value: Uint8Array | string | number | boolean): Promise<void>

Adds a KV pair of the specified type to this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to add. It cannot be empty, and the length cannot exceed MAX_KEY_LENGTH.
value	Uint8Array | string | number | boolean	Yes	Value of the KV pair to add. The value type can be Uint8Array, number, string, or boolean. A value of the Uint8Array or string type cannot exceed MAX_VALUE_LENGTH.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => {
        console.log("put success: " + JSON.stringify(data));
    }).catch((err) => {
        console.log("put err: " + JSON.stringify(err));
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

delete

delete(key: string, callback: AsyncCallback<void>): void

Deletes a KV pair from this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to delete. It cannot be empty, and the length cannot exceed MAX_KEY_LENGTH.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) {
        if (err != undefined) {
            console.log("put err: " + JSON.stringify(err));
            return;
        }
        console.log("put success");
        kvStore.delete(KEY_TEST_STRING_ELEMENT, function (err,data) {
            if (err != undefined) {
                console.log("delete err: " + JSON.stringify(err));
                return;
            }
            console.log("delete success");
        });
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

delete

delete(key: string): Promise<void>

Deletes a KV pair from this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the KV pair to delete. It cannot be empty, and the length cannot exceed MAX_KEY_LENGTH.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => {
        console.log("put success: " + JSON.stringify(data));
        kvStore.delete(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log("delete success");
        }).catch((err) => {
            console.log("delete err: " + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log("put err: " + JSON.stringify(err));
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

delete⁹⁺

delete(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<void>)

Deletes KV pairs that meet the specified predicates. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
predicates	DataSharePredicates	Yes	Conditions for deleting data. If this parameter is null, define the processing logic.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
let kvStore;
try {
	let predicates = new dataSharePredicates.DataSharePredicates();
	kvStore.delete(predicates, function (err, data) {
		if (err == undefined) {
			console.log('delete success');
		} else {
			console.log('delete fail' + err);
		}
    });  
} catch (e) {
	console.log('An unexpected error occurred. Error:' + e);
}

delete⁹⁺

delete(predicates: dataSharePredicates.DataSharePredicates): Promise<void>

Deletes KV pairs that meet the specified predicates. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
predicates	DataSharePredicates	Yes	Conditions for deleting data. If this parameter is null, define the processing logic.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
let kvStore;
try {
	let predicates = new dataSharePredicates.DataSharePredicates();
	let arr = ["name"];
	predicates.inKeys(arr);
	kvStore.put("name", "bob").then((data) => {
		console.log('put success' + JSON.stringify(data));
		kvStore.delete(predicates).then((data) => {
			console.log('delete success');
		}).catch((err) => {
			console.log('delete fail' + JSON.stringify(err));
		});
	}) .catch((err) => {
		console.log(' put fail' + err);
	});
}catch (e) {
	console.log("An unexpected error occurred. Error:" + e);
}

on(‘dataChange’)

on(event: ‘dataChange’, type: SubscribeType, listener: Callback<ChangeNotification>): void

Subscribes to data change notifications of the specified type.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is dataChange, which indicates data changes.
type	SubscribeType	Yes	Type of data changes.
listener	Callback<ChangeNotification>	Yes	Callback used to return the data changes.

Example

let kvStore;
kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
    console.log("dataChange callback call data: " + JSON.stringify(data));
});

on(‘syncComplete’)

on(event: ‘syncComplete’, syncCallback: Callback<Array<[string, number]>>): void

Subscribes to data synchronization complete events.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is syncComplete, which indicates completion of a data synchronization.
syncCallback	Callback<Array<[string, number]>>	Yes	Callback used to return the data synchronization result.

Example

let kvStore;
kvStore.on('syncComplete', function (data) {
    console.log("callback call data: " + data);
});

off(‘dataChange’)⁸⁺

off(event:‘dataChange’, listener?: Callback<ChangeNotification>): void

Unsubscribes from data change notifications.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is dataChange, which indicates data changes.
listener	Callback<ChangeNotification>	No	Callback used to return the data changes.

Example

let kvStore;
kvStore.on('dataChange', function (data) {
    console.log("callback call data: " + data);
});
kvStore.off('dataChange', function (data) {
    console.log("callback call data: " + data);
});

off(‘syncComplete’)⁹⁺

off(event: ‘syncComplete’, syncCallback?: Callback<Array<[string, number]>>): void

Unsubscribes from data change events. This API uses a synchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is syncComplete, which indicates completion of a data synchronization.
syncCallback	Callback<Array<[string, number]>>	No	Callback used to return the synchronization result.

Example

let kvStore;
try {
    const func = function (data) {
        console.log('syncComplete ' + data)
    };
    kvStore.on('syncComplete', func);
    kvStore.off('syncComplete', func);
}catch(e) {
    console.log('syncComplete e ' + e);
}

putBatch⁸⁺

putBatch(entries: Entry[], callback: AsyncCallback<void>): void

Inserts KV pairs in batches to this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
entries	Entry[]	Yes	KV pairs to insert in batches.
callback	Asyncallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.getEntries('batch_test_string_key', function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
}catch(e) {
    console.log('PutBatch e ' + JSON.stringify(e));
}

putBatch⁸⁺

putBatch(entries: Entry[]): Promise<void>

Inserts KV pairs in batches to this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
entries	Entry[]	Yes	KV pairs to insert in batches.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.getEntries('batch_test_string_key').then((entries) => {
            console.log('getEntries success');
            console.log('PutBatch ' + JSON.stringify(entries));
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('PutBatch e ' + JSON.stringify(e));
}

putBatch⁹⁺

putBatch(value: Array<ValuesBucket>, callback: AsyncCallback<void>): void

Writes data to this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
value	Array<ValuesBucket>	Yes	Data to write.
callback	Asyncallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    let v8Arr = [];
    let arr = new Uint8Array([4,5,6,7]);
    let vb1 = {key : "name_1", value : 32}
    let vb2 = {key : "name_2", value : arr};
    let vb3 = {key : "name_3", value : "lisi"};

    v8Arr.push(vb1);
    v8Arr.push(vb2);
    v8Arr.push(vb3);
    kvStore.putBatch(v8Arr, async function (err,data) {
                console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('putBatch e ' + JSON.stringify(e));
}

putBatch⁹⁺

putBatch(value: Array<ValuesBucket>): Promise<void>

Writes data of the valuesbucket type to this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
value	Array<ValuesBucket>	Yes	Data to write.

Return value

Type	Description
Promise<void>	Promise used to return the result.

Example

let kvStore;
try {
    let v8Arr = [];
    let arr = new Uint8Array([4,5,6,7]);
    let vb1 = {key : "name_1", value : 32}
    let vb2 = {key : "name_2", value : arr};
    let vb3 = {key : "name_3", value : "lisi"};

    v8Arr.push(vb1);
    v8Arr.push(vb2);
    v8Arr.push(vb3);
    kvStore.putBatch(v8Arr).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('PutBatch e ' + JSON.stringify(e));
}

deleteBatch⁸⁺

deleteBatch(keys: string[], callback: AsyncCallback<void>): void

Deletes KV pairs in batches from this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
keys	string[]	Yes	KV pairs to delete in batches.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    let entries = [];
    let keys = [];
    for (var i = 0; i < 5; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
        keys.push(key + i);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.deleteBatch(keys, async function (err,data) {
            console.log('deleteBatch success');
        });
    });
}catch(e) {
    console.log('DeleteBatch e ' + e);
}

deleteBatch⁸⁺

deleteBatch(keys: string[]): Promise<void>

Deletes KV pairs in batches from this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
keys	string[]	Yes	KV pairs to delete in batches.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    let entries = [];
    let keys = [];
    for (var i = 0; i < 5; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
        keys.push(key + i);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.deleteBatch(keys).then((err) => {
            console.log('deleteBatch success');
        }).catch((err) => {
            console.log('deleteBatch fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('DeleteBatch e ' + e);
}

startTransaction⁸⁺

startTransaction(callback: AsyncCallback<void>): void

Starts the transaction in this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
function putBatchString(len, prefix) {
    let entries = [];
    for (var i = 0; i < len; i++) {
        var entry = {
            key : prefix + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    return entries;
}
try {
    var count = 0;
    kvStore.on('dataChange', 0, function (data) {
        console.log('startTransaction 0' + data)
        count++;
    });
    kvStore.startTransaction(async function (err,data) {
        console.log('startTransaction success');
        let entries = putBatchString(10, 'batch_test_string_key');
        console.log('entries: ' + JSON.stringify(entries));
        kvStore.putBatch(entries, async function (err,data) {
            console.log('putBatch success');
        });
    });
}catch(e) {
    console.log('startTransaction e ' + e);
}

startTransaction⁸⁺

startTransaction(): Promise<void>

Starts the transaction in this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    var count = 0;
    kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) {
        console.log('startTransaction ' + JSON.stringify(data));
        count++;
    });
    kvStore.startTransaction().then(async (err) => {
        console.log('startTransaction success');
    }).catch((err) => {
        console.log('startTransaction fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('startTransaction e ' + e);
}

commit⁸⁺

commit(callback: AsyncCallback<void>): void

Commits the transaction in this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    kvStore.commit(function (err,data) {
        if (err == undefined) {
            console.log('commit success');
        } else {
            console.log('commit fail');
        }
    });
}catch(e) {
    console.log('Commit e ' + e);
}

commit⁸⁺

commit(): Promise<void>

Commits the transaction in this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    kvStore.commit().then(async (err) => {
        console.log('commit success');
    }).catch((err) => {
        console.log('commit fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('Commit e ' + e);
}

rollback⁸⁺

rollback(callback: AsyncCallback<void>): void

Rolls back the transaction in this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    kvStore.rollback(function (err,data) {
        if (err == undefined) {
            console.log('commit success');
        } else {
            console.log('commit fail');
        }
    });
}catch(e) {
    console.log('Rollback e ' + e);
}

rollback⁸⁺

rollback(): Promise<void>

Rolls back the transaction in this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    kvStore.rollback().then(async (err) => {
        console.log('rollback success');
    }).catch((err) => {
        console.log('rollback fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('Rollback e ' + e);
}

enableSync⁸⁺

enableSync(enabled: boolean, callback: AsyncCallback<void>): void

Sets data synchronization, which can be enabled or disabled. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
enabled	boolean	Yes	Whether to enable data synchronization. The value true means to enable data synchronization, and false means the opposite.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    kvStore.enableSync(true, function (err,data) {
        if (err == undefined) {
            console.log('enableSync success');
        } else {
            console.log('enableSync fail');
        }
    });
}catch(e) {
    console.log('EnableSync e ' + e);
}

enableSync⁸⁺

enableSync(enabled: boolean): Promise<void>

Sets data synchronization, which can be enabled or disabled. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
enabled	boolean	Yes	Whether to enable data synchronization. The value true means to enable data synchronization, and false means the opposite.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    kvStore.enableSync(true).then((err) => {
        console.log('enableSync success');
    }).catch((err) => {
        console.log('enableSync fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('EnableSync e ' + e);
}

setSyncRange⁸⁺

setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void

Sets the data synchronization range. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
localLabels	string[]	Yes	Synchronization labels set for the local device.
remoteSupportLabels	string[]	Yes	Synchronization labels set for remote devices.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    const localLabels = ['A', 'B'];
    const remoteSupportLabels = ['C', 'D'];
    kvStore.setSyncRange(localLabels, remoteSupportLabels, function (err,data) {
        console.log('SetSyncRange put success');
    });
}catch(e) {
    console.log('SetSyncRange e ' + e);
}

setSyncRange⁸⁺

setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void>

Sets the data synchronization range. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
localLabels	string[]	Yes	Synchronization labels set for the local device.
remoteSupportLabels	string[]	Yes	Synchronization labels set for remote devices.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    const localLabels = ['A', 'B'];
    const remoteSupportLabels = ['C', 'D'];
    kvStore.setSyncRange(localLabels, remoteSupportLabels).then((err) => {
        console.log('setSyncRange success');
    }).catch((err) => {
        console.log('delete fail ' + err);
    });
}catch(e) {
    console.log('SetSyncRange e ' + e);
}

SubscribeType

Enumerates the subscription types.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Value	Description
SUBSCRIBE_TYPE_LOCAL	0	Local data changes.
SUBSCRIBE_TYPE_REMOTE	1	Remote data changes.
SUBSCRIBE_TYPE_ALL	2	Local and remote data changes.

ChangeNotification

Defines the content of data change notifications, including inserted data, updated data, deleted data, and device ID.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Type	Readable	Writable	Description
insertEntries	Entry[]	Yes	Yes	Data inserted.
updateEntries	Entry[]	Yes	Yes	Data updated.
deleteEntries	Entry[]	Yes	Yes	Data deleted.
deviceId	string	Yes	Yes	UUID of the device.

Entry

Defines the KV pairs stored in the KV store.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Type	Readable	Writable	Description
key	string	Yes	Yes	Key of the KV pair stored in the KV store.
value	Value	Yes	Yes	Value of the KV pair stored in the KV store.

Value

Defines the value object in a KV store.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Type	Readable	Writable	Description
type	ValueType	Yes	Yes	Type of the value.
value	Uint8Array | string | number | boolean	Yes	Yes	Value of the KV pair stored in the KV store.

ValueType

Enumerates the data types.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Value	Description
STRING	0	String.
INTEGER	1	Integer.
FLOAT	2	Float (single-precision floating point).
BYTE_ARRAY	3	Byte array.
BOOLEAN	4	Boolean.
DOUBLE	5	Double (double-precision floating point).

SingleKVStore

Provides methods to query and synchronize data in a single KV store. This class inherits from KVStore.

Data is not distinguished by device in a single KV store. The data written to different devices using the same key will be overwritten. For example, a single KV store can be used to synchronize a user’s calendar and contact data between different devices.

Before calling any method in SingleKVStore, you must use getKVStore to obtain a SingleKVStore instance.

get

get(key: string, callback: AsyncCallback<Uint8Array | string | boolean | number>): void

Obtains the value of the specified key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the value to obtain. It cannot be empty, and the length cannot exceed MAX_KEY_LENGTH.
callback	AsyncCallback<Uint8Array | string | boolean | number>)	Yes	Callback invoked to return the value obtained.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, function (err,data) {
        if (err != undefined) {
            console.log("put err: " + JSON.stringify(err));
            return;
        }
        console.log("put success");
        kvStore.get(KEY_TEST_STRING_ELEMENT, function (err,data) {
            console.log("get success data: " + data);
        });
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

get

get(key: string): Promise<Uint8Array | string | boolean | number>

Obtains the value of the specified key. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
key	string	Yes	Key of the value to obtain. It cannot be empty, and the length cannot exceed MAX_KEY_LENGTH.

Return value

Type	Description
Promise<Uint8Array | string | boolean | number>	Promise used to return the value obtained.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-test-string';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((data) => {
        console.log("put success: " + JSON.stringify(data));
        kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log("get success data: " + data);
        }).catch((err) => {
            console.log("get err: " + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log("put err: " + JSON.stringify(err));
    });
}catch (e) {
    console.log("An unexpected error occurred. Error:" + e);
}

getEntries⁸⁺

getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void

Obtains all KV pairs that match the specified key prefix. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
keyPrefix	string	Yes	Key prefix to match.
callback	AsyncCallback<Entry[]>	Yes	Callback invoked to return the KV pairs obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_number_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.INTEGER,
                value : 222
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.getEntries('batch_test_number_key', function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
}catch(e) {
    console.log('PutBatch e ' + e);
}

getEntries⁸⁺

getEntries(keyPrefix: string): Promise<Entry[]>

Obtains all KV pairs that match the specified key prefix. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
keyPrefix	string	Yes	Key prefix to match.

Return value

Type	Description
Promise<Entry[]>	Promise used to return the KV pairs obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + entries);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.getEntries('batch_test_string_key').then((entries) => {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
            console.log('entries[0].value: ' + JSON.stringify(entries[0].value));
            console.log('entries[0].value.value: ' + entries[0].value.value);
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('PutBatch e ' + e);
}

getEntries⁸⁺

getEntries(query: Query, callback: AsyncCallback<Entry[]>): void

Obtains the KV pairs that match the specified Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Key prefix to match.
callback	AsyncCallback<Entry[]>	Yes	Callback used to return the KV pairs obtained.

Example

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query, function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}

getEntries⁸⁺

getEntries(query: Query): Promise<Entry[]>

Obtains the KV pairs that match the specified Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<Entry[]>	Promise used to return the KV pairs obtained.

Example

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query).then((entries) => {
            console.log('getEntries success');
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('GetEntries putBatch fail ' + JSON.stringify(err))
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}

getResultSet⁸⁺

getResultSet(keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void

Obtains the result set with the specified prefix. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
keyPrefix	string	Yes	Key prefix to match.
callback	AsyncCallback<KvStoreResultSet>	Yes	Callback invoked to return the result set obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('GetResultSet putBatch success');
        kvStore.getResultSet('batch_test_string_key', async function (err, result) {
            console.log('GetResultSet getResultSet succeed.');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                console.log('GetResultSet closeResultSet success');
            })
        });
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(keyPrefix: string): Promise<KvStoreResultSet>

Obtains the result set with the specified prefix. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
keyPrefix	string	Yes	Key prefix to match.

Return value

Type	Description
Promise<KvStoreResultSet>	Promise used to return the result set obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('PutBatch putBatch fail ' + JSON.stringify(err));
    });
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('GetResult getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('GetResult closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResult e ' + e);
}

getResultSet⁸⁺

getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void

Obtains a KvStoreResultSet object that matches the specified Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.
callback	AsyncCallback<KvStoreResultSet>	Yes	Callback invoked to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSet(query, async function (err, result) {
            console.log('getResultSet succeed.');
            resultSet = result;
        });
    });
} catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(query: Query): Promise<KvStoreResultSet>

Obtains a KvStoreResultSet object that matches the specified Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<KvStoreResultSet>	Promise used to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet(query).then((result) => {
        console.log(' getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁹⁺

getResultSet(predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KvStoreResultSet>): void

Obtains a KvStoreResultSet object that matches the specified DataSharePredicates object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
predicates	DataSharePredicates	Yes	DataSharePredicates object to match. If this parameter is null, define the processing logic.
callback	AsyncCallback<KvStoreResultSet>	Yes	Callback invoked to return the KvStoreResultSet object obtained.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
let kvStore;
try {
    let resultSet;
    let predicates = new dataSharePredicates.DataSharePredicates();
    predicates.prefixKey("batch_test_string_key");
    kvStore.getResultSet(predicates, async function (err, result) {
    console.log(' GetResultSet success');
    resultSet = result;
    kvStore.closeResultSet(resultSet, function (err, data) {
        console.log(' closeResultSet success');
        })
    });
}catch(e) {
    console.log('An unexpected error occurred. Error:' + e);
}

getResultSet⁹⁺

getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KvStoreResultSet>

Obtains a KvStoreResultSet object that matches the specified DataSharePredicates object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
predicates	DataSharePredicates	Yes	DataSharePredicates object to match. If this parameter is null, define the processing logic.

Return value

Type	Description
Promise<KvStoreResultSet>	Promise used to return the KvStoreResultSet object obtained.

Example

import dataSharePredicates from '@ohos.data.dataSharePredicates';
let kvStore;
try {
	let resultSet;
    let predicates =  new dataSharePredicates.DataSharePredicates();
    predicates.prefixKey("batch_test_string_key");
    kvStore.getResultSet(predicates) .then((result) => {
        console.log(' GetResultSet success');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            console.log(' closeResultSet success');
        })
    });
}catch(e) {
	console.log('An unexpected error occurred. Error:' + e);
}

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void

Closes the KvStoreResultSet object obtained by SingleKvStore.getResultSet. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
resultSet	KvStoreResultSet	Yes	KvStoreResultSet object to close.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    let resultSet = null;
    kvStore.closeResultSet(resultSet, function (err, data) {
        if (err == undefined) {
            console.log('closeResultSet success');
        } else {
            console.log('closeResultSet fail');
        }
    });
}catch(e) {
    console.log('CloseResultSet e ' + e);
}

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet): Promise<void>

Closes the KvStoreResultSet object obtained by SingleKvStore.getResultSet. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
resultSet	KvStoreResultSet	Yes	KvStoreResultSet object to close.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    let resultSet = null;
    kvStore.closeResultSet(resultSet).then(() => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('CloseResultSet e ' + e);
}

getResultSize⁸⁺

getResultSize(query: Query, callback: AsyncCallback<number>): void

Obtains the number of results that matches the specified Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.
callback	AsyncCallback<number>	Yes	Callback invoked to return the number of results obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSize(query, async function (err, resultSize) {
            console.log('getResultSet succeed.');
        });
    });
} catch(e) {
    console.log('GetResultSize e ' + e);
}

getResultSize⁸⁺

getResultSize(query: Query): Promise<number>

Obtains the number of results that matches the specified Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<number>	Promise used to return the number of results obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSize(query).then((resultSize) => {
        console.log('getResultSet succeed.');
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSize e ' + e);
}

removeDeviceData⁸⁺

removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void

Deletes data of a device. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
const VALUE_TEST_STRING_ELEMENT = 'value-string-002';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) {
        console.log('put success');
        const deviceid = 'no_exist_device_id';
        kvStore.removeDeviceData(deviceid, async function (err,data) {
            if (err == undefined) {
                console.log('removeDeviceData success');
            } else {
                console.log('removeDeviceData fail');
                kvStore.get(KEY_TEST_STRING_ELEMENT, async function (err,data) {
                    console.log('RemoveDeviceData get success');
                });
            }
        });
    });
}catch(e) {
    console.log('RemoveDeviceData e ' + e);
}

removeDeviceData⁸⁺

removeDeviceData(deviceId: string): Promise<void>

Deletes data of a device. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
const VALUE_TEST_STRING_ELEMENT = 'value-string-001';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((err) => {
        console.log('removeDeviceData put success');
    }).catch((err) => {
        console.log('put fail ' + JSON.stringify(err));
    });
    const deviceid = 'no_exist_device_id';
    kvStore.removeDeviceData(deviceid).then((err) => {
        console.log('removeDeviceData success');
    }).catch((err) => {
        console.log('removeDeviceData fail ' + JSON.stringify(err));
    });
    kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => {
        console.log('get success data:' + data);
    }).catch((err) => {
        console.log('RemoveDeviceData get fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('RemoveDeviceData e ' + e);
}

on(‘syncComplete’)⁸⁺

on(event: ‘syncComplete’, syncCallback: Callback<Array<[string, number]>>): void

Subscribes to the data synchronization complete events.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is syncComplete, which indicates completion of a data synchronization.
syncCallback	Callback<Array<[string, number]>>	Yes	Callback called to return the synchronization result.

Example

let kvStore;
const KEY_TEST_FLOAT_ELEMENT = 'key_test_float';
const VALUE_TEST_FLOAT_ELEMENT = 321.12;
try {
    kvStore.on('syncComplete', function (data) {
        console.log('syncComplete ' + data)
    });
    kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => {
        console.log('syncComplete put success');
    }).catch((error) => {
        console.log('syncComplete put fail ' + error);
    });
}catch(e) {
    console.log('syncComplete put e ' + e);
}

off(‘syncComplete’)⁸⁺

off(event: ‘syncComplete’, syncCallback?: Callback<Array<[string, number]>>): void

Unsubscribes from the data synchronization complete events.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is syncComplete, which indicates completion of a data synchronization.
syncCallback	Callback<Array<[string, number]>>	No	Callback used to return the synchronization result.

Example

let kvStore;
try {
    const func = function (data) {
        console.log('syncComplete ' + data)
    };
    kvStore.on('syncComplete', func);
    kvStore.off('syncComplete', func);
}catch(e) {
    console.log('syncComplete e ' + e);
}

on(‘dataChange’)⁹⁺

on(event: ‘dataChange’, type: SubscribeType, listener: Callback<ChangeNotification>): void

Subscribes to data changes of the specified type. This API returns the result synchronously.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is dataChange, which indicates data changes.
type	SubscribeType	Yes	Subscription type.
listener	Callback<ChangeNotification>	Yes	Callback used to return the result.

Example

let kvStore;
kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
    console.log("dataChange callback call data: " + JSON.stringify(data));
});

off(‘dataChange’)⁹⁺

off(event:‘dataChange’, listener?: Callback<ChangeNotification>): void

Unsubscribes from the data change events. This API returns the result synchronously.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is dataChange, which indicates data changes.
listener	Callback<ChangeNotification>	No	Callback used to return the result.

Example

let kvStore;
kvStore.on('dataChange', function (data) {
    console.log("callback call data: " + data);
});
kvStore.off('dataChange', function (data) {
    console.log("callback call data: " + data);
});

sync⁷⁺

sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void

Synchronizes the KV store manually. For details about the synchronization modes of the distributed data service, see Distributed Data Service Overview.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceIds	string[]	Yes	List of IDs of the devices in the same networking environment to be synchronized.
mode	SyncMode	Yes	Synchronization mode.
delayMs	number	No	Allowed synchronization delay time, in ms.

Example

let kvStore;
kvStore.sync('deviceIds', distributedData.SyncMode.PULL_ONLY, 1000);

sync⁹⁺

sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void

Synchronizes the KV store manually. This API returns the result synchronously. For details about the synchronization modes of the distributed data service, see Distributed Data Service Overview.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceIds	string[]	Yes	List of IDs of the devices in the same networking environment to be synchronized.
mode	SyncMode	Yes	Synchronization mode.
query	Query	Yes	Query object to match.
delayMs	number	No	Allowed synchronization delay time, in ms.

Example

let kvStore;
const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
try {
    kvStore.on('syncComplete', function (data) {
        console.log('Sync dataChange');
    });
    kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) {
        console.log('Sync put success');
        const devices = ['deviceList'];
        const mode = distributedData.SyncMode.PULL_ONLY;
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.sync(devices, query, mode , 1000);
    });
}catch(e) {
    console.log('Sync e' + e);
}

setSyncParam⁸⁺

setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void

Sets the default delay allowed for KV store synchronization. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
defaultAllowedDelayMs	number	Yes	Default delay allowed for database synchronization, in ms.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    const defaultAllowedDelayMs = 500;
    kvStore.setSyncParam(defaultAllowedDelayMs, function (err,data) {
        console.log('SetSyncParam put success');
    });
}catch(e) {
    console.log('testSingleKvStoreSetSyncParam e ' + e);
}

setSyncParam⁸⁺

setSyncParam(defaultAllowedDelayMs: number): Promise<void>

Sets the default delay allowed for KV store synchronization. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
defaultAllowedDelayMs	number	Yes	Default delay allowed for database synchronization, in ms.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    const defaultAllowedDelayMs = 500;
    kvStore.setSyncParam(defaultAllowedDelayMs).then((err) => {
        console.log('SetSyncParam put success');
    }).catch((err) => {
        console.log('SetSyncParam put fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('SetSyncParam e ' + e);
}

getSecurityLevel⁸⁺

getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void

Obtains the security level of this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
callback	AsyncCallback<SecurityLevel>	Yes	Callback invoked to return the security level obtained.

Example

let kvStore;
try {
    kvStore.getSecurityLevel(function (err,data) {
        console.log('getSecurityLevel success');
    });
}catch(e) {
    console.log('GetSecurityLevel e ' + e);
}

getSecurityLevel⁸⁺

getSecurityLevel(): Promise<SecurityLevel>

Obtains the security level of this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Return value

Type	Description
Promise<SecurityLevel>	Promise used to return the security level obtained.

Example

let kvStore;
try {
    kvStore.getSecurityLevel().then((data) => {
        console.log(' getSecurityLevel success');
    }).catch((err) => {
        console.log('getSecurityLevel fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetSecurityLevel e ' + e);
}

DeviceKVStore⁸⁺

Provides methods to query and synchronize data in a device KV store. This class inherits from KVStore.

Data is distinguished by device in a device KV store. Each device can only write and modify its own data. Data of other devices is read-only and cannot be modified.

For example, a device KV store can be used to implement image sharing between devices. The images of other devices can be viewed, but not be modified or deleted.

Before calling any method in DeviceKVStore, you must use getKVStore to obtain a DeviceKVStore object.

get⁸⁺

get(deviceId: string, key: string, callback: AsyncCallback<boolean|string|number|Uint8Array>): void

Obtains a string value that matches the specified device ID and key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
key	string	Yes	Key to match.
callback	AsyncCallback<boolean|string|number|Uint8Array>	Yes	Callback used to return the value obtained.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
const VALUE_TEST_STRING_ELEMENT = 'value-string-002';
try{
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) {
        console.log('put success');
        kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, function (err,data) {
            console.log('get success');
        });
    })
}catch(e) {
    console.log('get e' + e);
}

get⁸⁺

get(deviceId: string, key: string): Promise<boolean|string|number|Uint8Array>

Obtains a string value that matches the specified device ID and key. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
key	string	Yes	Key to match.

Return value

Type	Description
Promise<boolean|string|number|Uint8Array>	Promise used to return the string value obtained.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string_2';
const VALUE_TEST_STRING_ELEMENT = 'value-string-002';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(async (data) => {
        console.log(' put success');
        kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log('get success');
        }).catch((err) => {
            console.log('get fail ' + JSON.stringify(err));
        });
    }).catch((error) => {
        console.log('put error' + error);
    });
} catch (e) {
    console.log('Get e ' + e);
}

getEntries⁸⁺

getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void

Obtains all KV pairs that match the specified device ID and key prefix. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
keyPrefix	string	Yes	Key prefix to match.
callback	AsyncCallback<Entry[]>	Yes	Callback used to return the KV pairs obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + entries);
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        kvStore.getEntries('localDeviceId', 'batch_test_string_key', function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
}catch(e) {
    console.log('PutBatch e ' + e);
}

getEntries⁸⁺

getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]>

Obtains all KV pairs that match the specified device ID and key prefix. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
keyPrefix	string	Yes	Key prefix to match.

Return value

Type	Description
Promise<Entry[]>	Promise used to return the KV pairs obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + entries);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries) => {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
            console.log('entries[0].value: ' + JSON.stringify(entries[0].value));
            console.log('entries[0].value.value: ' + entries[0].value.value);
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('PutBatch e ' + e);
}

getEntries⁸⁺

getEntries(query: Query, callback: AsyncCallback<Entry[]>): void

Obtains the KV pairs that match the specified Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.
callback	AsyncCallback<Entry[]>	Yes	Callback used to return the KV pairs obtained.

Example

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.getEntries(query, function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        });
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}

getEntries⁸⁺

getEntries(query: Query): Promise<Entry[]>

Obtains the KV pairs that match the specified Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<Entry[]>	Promise used to return the KV pairs obtained.

Example

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query).then((entries) => {
            console.log('getEntries success');
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('GetEntries putBatch fail ' + JSON.stringify(err))
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}

getEntries⁸⁺

getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void

Obtains the KV pairs that match the specified device ID and Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
query	Query	Yes	Query object to match.
callback	AsyncCallback<Entry[]>	Yes	Callback invoked to return the KV pairs obtained.

Example

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries, async function (err,data) {
        console.log('putBatch success');
        var query = new distributedData.Query();
        query.deviceId('localDeviceId');
        query.prefixKey("batch_test");
        kvStore.getEntries('localDeviceId', query, function (err,entries) {
            console.log('getEntries success');
            console.log('entries.length: ' + entries.length);
            console.log('entries[0]: ' + JSON.stringify(entries[0]));
        })
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}

getEntries⁸⁺

getEntries(deviceId: string, query: Query): Promise<Entry[]>

Obtains the KV pairs that match the specified device ID and Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<Entry[]>	Promise used to return the KV pairs obtained.

Example

let kvStore;
try {
    var arr = new Uint8Array([21,31]);
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_bool_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.BYTE_ARRAY,
                value : arr
            }
        }
        entries.push(entry);
    }
    console.log('entries: ' + JSON.stringify(entries));
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
        var query = new distributedData.Query();
        query.deviceId('localDeviceId');
        query.prefixKey("batch_test");
        kvStore.getEntries('localDeviceId', query).then((entries) => {
            console.log('getEntries success');
        }).catch((err) => {
            console.log('getEntries fail ' + JSON.stringify(err));
        });
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    console.log('GetEntries success');
}catch(e) {
    console.log('GetEntries e ' + e);
}

getResultSet⁸⁺

getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KvStoreResultSet>): void

Obtains a KvStoreResultSet object that matches the specified device ID and key prefix. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
keyPrefix	string	Yes	Key prefix to match.
callback	AsyncCallback<KvStoreResultSet[]>	Yes	Callback invoked to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async function (err, result) {
        console.log('getResultSet succeed.');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            console.log('closeResultSet success');
        })
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(deviceId: string, keyPrefix: string): Promise<KvStoreResultSet>

Obtains a KvStoreResultSet object that matches the specified device ID and key prefix. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
keyPrefix	string	Yes	Key prefix to match.

Return value

Type	Description
Promise<KvStoreResultSet[]>	Promise used to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(query: Query, callback: AsyncCallback<KvStoreResultSet>): void

Obtains a KvStoreResultSet object that matches the specified Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.
callback	AsyncCallback<KvStoreResultSet[]>	Yes	Callback invoked to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.getResultSet(query, async function (err, result) {
            console.log('getResultSet succeed.');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                console.log('closeResultSet success');
            })
        });
    });
} catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(query: Query): Promise<KvStoreResultSet>

Obtains a KvStoreResultSet object that matches the specified Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<KvStoreResultSet[]>	Promise used to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + err);
    });
    const query = new distributedData.Query();
    query.deviceId('localDeviceId');
    query.prefixKey("batch_test");
    console.log("GetResultSet " + query.getSqlLike());
    kvStore.getResultSet(query).then((result) => {
        console.log('getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KvStoreResultSet>): void

Obtains a KvStoreResultSet object that matches the specified device ID and Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
query	Query	Yes	Query object to match.
callback	AsyncCallback<KvStoreResultSet[]>	Yes	Callback invoked to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSet('localDeviceId', query, async function (err, result) {
            console.log('getResultSet succeed.');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                console.log('closeResultSet success');
            })
        });
    });
} catch(e) {
    console.log('GetResultSet e ' + e);
}

getResultSet⁸⁺

getResultSet(deviceId: string, query: Query): Promise<KvStoreResultSet>

Obtains a KvStoreResultSet object that matches the specified device ID and Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<KvStoreResultSet[]>	Promise used to return the KvStoreResultSet object obtained.

Example

let kvStore;
try {
    let resultSet;
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('GetResultSet putBatch success');
    }).catch((err) => {
        console.log('PutBatch putBatch fail ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet('localDeviceId', query).then((result) => {
        console.log('GetResultSet getResultSet succeed.');
        resultSet = result;
    }).catch((err) => {
        console.log('GetResultSet getResultSet failed: ' + JSON.stringify(err));
    });
    query.deviceId('localDeviceId');
    console.log("GetResultSet " + query.getSqlLike());
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('GetResultSet closeResultSet success');
    }).catch((err) => {
        console.log('GetResultSet closeResultSet fail ' + JSON.stringify(err));
    });

}catch(e) {
    console.log('GetResultSet e ' + e);
}

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet, callback: AsyncCallback<void>): void

Closes the KvStoreResultSet object obtained by DeviceKVStore.getResultSet. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
resultSet	KvStoreResultSet	Yes	KvStoreResultSet object to close.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
try {
    console.log('CloseResultSet success');
    let resultSet = null;
    kvStore.closeResultSet(resultSet, function (err, data) {
        if (err == undefined) {
            console.log('closeResultSet success');
        } else {
            console.log('closeResultSet fail');
        }
    });
}catch(e) {
    console.log('CloseResultSet e ' + e);
}

closeResultSet⁸⁺

closeResultSet(resultSet: KvStoreResultSet): Promise<void>

Closes the KvStoreResultSet object obtained by DeviceKVStore.getResultSet. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
resultSet	KvStoreResultSet	Yes	KvStoreResultSet object to close.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
try {
    console.log('CloseResultSet success');
    let resultSet = null;
    kvStore.closeResultSet(resultSet).then(() => {
        console.log('closeResultSet success');
    }).catch((err) => {
        console.log('closeResultSet fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('CloseResultSet e ' + e);
}

getResultSize⁸⁺

getResultSize(query: Query, callback: AsyncCallback<number>): void

Obtains the number of results that matches the specified Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.
callback	AsyncCallback<number>	Yes	Callback invoked to return the number of results obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.getResultSize(query, async function (err, resultSize) {
            console.log('getResultSet succeed.');
        });
    });
} catch(e) {
    console.log('GetResultSize e ' + e);
}

getResultSize⁸⁺

getResultSize(query: Query): Promise<number>

Obtains the number of results that matches the specified Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<number>	Promise used to return the number of results obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    const query = new distributedData.Query();
    query.prefixKey("batch_test");
    query.deviceId('localDeviceId');
    kvStore.getResultSize(query).then((resultSize) => {
        console.log('getResultSet succeed.');
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSize e ' + e);
}

getResultSize⁸⁺

getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void;

Obtains the number of results that matches the specified device ID and Query object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
query	Query	Yes	Query object to match.
callback	AsyncCallback<number>	Yes	Callback invoked to return the number of results obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('putBatch success');
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSize('localDeviceId', query, async function (err, resultSize) {
            console.log('getResultSet succeed.');
        });
    });
} catch(e) {
    console.log('GetResultSize e ' + e);
}

getResultSize⁸⁺

getResultSize(deviceId: string, query: Query): Promise<number>

Obtains the number of results that matches the specified device ID and Query object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
query	Query	Yes	Query object to match.

Return value

Type	Description
Promise<number>	Promise used to return the number of results obtained.

Example

let kvStore;
try {
    let entries = [];
    for (var i = 0; i < 10; i++) {
        var key = 'batch_test_string_key';
        var entry = {
            key : key + i,
            value : {
                type : distributedData.ValueType.STRING,
                value : 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('putBatch success');
    }).catch((err) => {
        console.log('putBatch fail ' + JSON.stringify(err));
    });
    var query = new distributedData.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSize('localDeviceId', query).then((resultSize) => {
        console.log('getResultSet succeed.');
    }).catch((err) => {
        console.log('getResultSet failed: ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('GetResultSize e ' + e);
}

removeDeviceData⁸⁺

removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void

Deletes data of the specified device from this KV store. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.
callback	AsyncCallback<void>	Yes	Callback used to return the result.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-string-001';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async function (err,data) {
        console.log('RemoveDeviceData  put success');
        const deviceid = 'no_exist_device_id';
        kvStore.removeDeviceData(deviceid, async function (err,data) {
            if (err == undefined) {
                console.log('removeDeviceData success');
            } else {
                console.log('removeDeviceData fail');
                kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, async function (err,data) {
                    console.log('RemoveDeviceData get success');
                });
            }
        });
    });
}catch(e) {
    console.log('RemoveDeviceData e ' + e);
}

removeDeviceData⁸⁺

removeDeviceData(deviceId: string): Promise<void>

Deletes data of the specified device from this KV store. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Parameters

Name	Type	Mandatory	Description
deviceId	string	Yes	ID of the target device.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Example

let kvStore;
const KEY_TEST_STRING_ELEMENT = 'key_test_string';
const VALUE_TEST_STRING_ELEMENT = 'value-string-001';
try {
    kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then((err) => {
        console.log('RemoveDeviceData put success');
    }).catch((err) => {
        console.log('RemoveDeviceData put fail ' + JSON.stringify(err));
    });
    const deviceid = 'no_exist_device_id';
    kvStore.removeDeviceData(deviceid).then((err) => {
        console.log('removeDeviceData success');
    }).catch((err) => {
        console.log('removeDeviceData fail ' + JSON.stringify(err));
    });
    kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => {
        console.log('RemoveDeviceData get success data:' + data);
    }).catch((err) => {
        console.log('RemoveDeviceData get fail ' + JSON.stringify(err));
    });
}catch(e) {
    console.log('RemoveDeviceData e ' + e);
}

sync⁸⁺

sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void

Synchronizes the KV store manually. For details about the synchronization modes of the distributed data service, see Distributed Data Service Overview.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceIds	string[]	Yes	IDs of the devices to be synchronized.
mode	SyncMode	Yes	Synchronization mode.
delayMs	number	No	Allowed synchronization delay time, in ms.

Example

let kvStore;
const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
try {
    kvStore.on('syncComplete', function (data) {
        console.log('Sync dataChange');
    });
    kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) {
        console.log('Sync put success');
        const devices = ['deviceList'];
        const mode = distributedData.SyncMode.PULL_ONLY;
        kvStore.sync(devices, mode);
    });
}catch(e) {
    console.log('Sync e' + e);
}

sync⁹⁺

sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void

Synchronizes the KV store manually. This API returns the result synchronously. For details about the synchronization modes of the distributed data service, see Distributed Data Service Overview.

Required permissions: ohos.permission.DISTRIBUTED_DATASYNC

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
deviceIds	string[]	Yes	IDs of the devices to be synchronized.
query	Query	Yes	Query object to match.
delayMs	number	No	Allowed synchronization delay time, in ms.

Example

let kvStore;
const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
try {
    kvStore.on('syncComplete', function (data) {
        console.log('Sync dataChange');
    });
    kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err,data) {
        console.log('Sync put success');
        const devices = ['deviceList'];
        const mode = distributedData.SyncMode.PULL_ONLY;
        const query = new distributedData.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.sync(devices, query, 1000);
    });
}catch(e) {
    console.log('Sync e' + e);
}

on(‘syncComplete’)⁸⁺

on(event: ‘syncComplete’, syncCallback: Callback<Array<[string, number]>>): void

Subscribes to the data synchronization complete events.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is syncComplete, which indicates the data synchronization complete event.
syncCallback	Callback	Yes	Callback used to return the synchronization result.

Example

let kvStore;
const KEY_TEST_FLOAT_ELEMENT = 'key_test_float';
const VALUE_TEST_FLOAT_ELEMENT = 321.12;
try {
    kvStore.on('syncComplete', function (data) {
        console.log('syncComplete ' + data)
    });
    kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then((data) => {
        console.log('syncComplete put success');
    }).catch((error) => {
        console.log('syncComplete put fail ' + error);
    });
}catch(e) {
    console.log('syncComplete put e ' + e);
}

off(‘syncComplete’)⁸⁺

off(event: ‘syncComplete’, syncCallback?: Callback<Array<[string, number]>>): void

Unsubscribes from the synchronization complete events. This API returns the result synchronously.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is syncComplete, which indicates the data synchronization complete event.
syncCallback	Callback	No	Callback used to return the synchronization result.

Example

let kvStore;
try {
    const func = function (data) {
        console.log('syncComplete ' + data)
    };
    kvStore.on('syncComplete', func);
    kvStore.off('syncComplete', func);
}catch(e) {
    console.log('syncComplete e ' + e);
}

on(‘dataChange’)⁹⁺

on(event: ‘dataChange’, type: SubscribeType, listener: Callback<ChangeNotification>): void

Subscribes to data changes of the specified type. This API returns the result synchronously.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to subscribe to. The value is dataChange, which indicates data changes.
type	SubscribeType	Yes	Subscription type.
listener	Callback<ChangeNotification>	Yes	Callback used to return the result.

Example

let kvStore;
kvStore.on('dataChange', distributedData.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
    console.log("dataChange callback call data: " + JSON.stringify(data));
});

off(‘dataChange’)⁹⁺

off(event:‘dataChange’, listener?: Callback<ChangeNotification>): void

Unsubscribes from the data change events. This API returns the result synchronously.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Parameters

Name	Type	Mandatory	Description
event	string	Yes	Event to unsubscribe from. The value is dataChange, which indicates data changes.
listener	Callback<ChangeNotification>	No	Callback used to return the result.

Example

let kvStore;
kvStore.on('dataChange', function (data) {
    console.log("callback call data: " + data);
});
kvStore.off('dataChange', function (data) {
    console.log("callback call data: " + data);
});

SyncMode

Enumerates the synchronization modes.

System capability: SystemCapability.DistributedDataManager.KVStore.Core

Name	Value	Description
PULL_ONLY	0	Pull data from the peer end to the local end only.
PUSH_ONLY	1	Push data from the local end to the peer end only.
PUSH_PULL	2	Push data from the local end to the peer end and then pull data from the peer end to the local end.

你可能感兴趣的文章

开源鸿蒙 APIs

开源鸿蒙 API Reference Document Description

开源鸿蒙 Bundle

开源鸿蒙 Context

开源鸿蒙 DataUriUtils

开源鸿蒙 EnterpriseAdminExtensionAbility

开源鸿蒙 Work Scheduler Callbacks

开源鸿蒙 AbilityContext

开源鸿蒙 ErrorCode

开源鸿蒙 wantConstant