@ohos.data.distributedKVStore (分布式键值数据库)

分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口,应用程序可将数据保存到分布式键值数据库中,并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。

该模块提供以下分布式键值数据库相关的常用功能:

  • KVManager:分布式键值数据库管理实例,用于获取数据库的相关信息。
  • KVStoreResultSet:提供获取数据库结果集的相关方法,包括查询和移动数据读取位置等。
  • Query:使用谓词表示数据库查询,提供创建Query实例、查询数据库中的数据和添加谓词的方法。
  • SingleKVStore:单版本分布式键值数据库,不对数据所属设备进行区分,提供查询数据和同步数据的方法。
  • DeviceKVStore:设备协同数据库,继承自SingleKVStore,以设备维度对数据进行区分,提供查询数据和同步数据的方法。

说明:

本模块首批接口从API version 9开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。

导入模块

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

KVManagerConfig

提供KVManager实例的配置信息,包括调用方的包名和应用的上下文。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 类型 必填 说明
context Context 应用的上下文。
FA模型的应用Context定义见Context
Stage模型的应用Context定义见Context
bundleName string 调用方的包名。

Constants

分布式键值数据库常量。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 说明
MAX_KEY_LENGTH 1024 数据库中Key允许的最大长度,单位字节。
MAX_VALUE_LENGTH 4194303 数据库中Value允许的最大长度,单位字节。
MAX_KEY_LENGTH_DEVICE 896 最大设备密钥长度,单位字节。
MAX_STORE_ID_LENGTH 128 数据库标识符允许的最大长度,单位字节。
MAX_QUERY_LENGTH 512000 最大查询长度,单位字节。
MAX_BATCH_SIZE 128 最大批处理操作数量。

ValueType

数据类型枚举。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 说明
STRING 表示值类型为字符串。
INTEGER 表示值类型为整数。
FLOAT 表示值类型为浮点数。
BYTE_ARRAY 表示值类型为字节数组。
BOOLEAN 表示值类型为布尔值。
DOUBLE 表示值类型为双浮点数。

Value

存储在数据库中的值对象。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 类型 必填 说明
type ValueType 值类型。
value Uint8Array | string | number | boolean 值。

Entry

存储在数据库中的键值对。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 类型 必填 说明
key string 键值。
value Value 值对象。

ChangeNotification

数据变更时通知的对象,包括数据插入的数据、更新的数据、删除的数据和设备ID。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 类型 必填 说明
insertEntries Entry[] 数据添加记录。
updateEntries Entry[] 数据更新记录。
deleteEntries Entry[] 数据删除记录。
deviceId string 设备ID,此处为设备UUID。

SyncMode

同步模式枚举。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 说明
PULL_ONLY 表示只能从远端拉取数据到本端。
PUSH_ONLY 表示只能从本端推送数据到远端。
PUSH_PULL 表示从本端推送数据到远端,然后从远端拉取数据到本端。

SubscribeType

订阅类型枚举。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 说明
SUBSCRIBE_TYPE_LOCAL 表示订阅本地数据变更。
SUBSCRIBE_TYPE_REMOTE 表示订阅远端数据变更。
SUBSCRIBE_TYPE_ALL 表示订阅远端和本地数据变更。

KVStoreType

分布式键值数据库类型枚举。

名称 说明
DEVICE_COLLABORATION 表示多设备协同数据库。
数据库特点: 数据以设备的维度管理,不存在冲突;支持按照设备的维度查询数据。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore
SINGLE_VERSION 表示单版本数据库。
数据库特点: 数据不分设备,设备之间修改相同的key会覆盖。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core

SecurityLevel

数据库的安全级别枚举。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

名称 说明
S1 表示数据库的安全级别为低级别,当数据泄露时会产生较低影响。例如,包含壁纸等系统数据的数据库。
S2 表示数据库的安全级别为中级别,当数据泄露时会产生较大影响。例如,包含录音、视频等用户生成数据或通话记录等信息的数据库。
S3 表示数据库的安全级别为高级别,当数据泄露时会产生重大影响。例如,包含用户运动、健康、位置等信息的数据库。
S4 表示数据库的安全级别为关键级别,当数据泄露时会产生严重影响。例如,包含认证凭据、财务数据等信息的数据库。

Options

用于提供创建数据库的配置信息。

名称 类型 必填 说明
createIfMissing boolean 当数据库文件不存在时是否创建数据库,默认为true,即创建。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
encrypt boolean 设置数据库文件是否加密,默认为false,即不加密。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
backup boolean 设置数据库文件是否备份,默认为true,即备份。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
autoSync boolean 设置数据库文件是否自动同步。默认为false,即手动同步;设置为true时,表示自动同步。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
需要权限: ohos.permission.DISTRIBUTED_DATASYNC
kvStoreType KVStoreType 设置要创建的数据库类型,默认为DEVICE_COLLABORATION,即多设备协同数据库。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
securityLevel SecurityLevel 设置数据库安全级别。
系统能力: SystemCapability.DistributedDataManager.KVStore.Core
schema Schema 设置定义存储在数据库中的值,默认为undefined, 即不使用Schema。
系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

Schema

表示数据库模式,可以在创建或打开数据库时创建Schema对象并将它们放入Options中。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

名称 类型 可读 可写 说明
root FieldNode 表示json根对象。
indexes Array<string> 表示json类型的字符串数组。
mode number 表示Schema的模式。
skip number Schema的跳跃大小。

constructor

constructor()

用于创建Schema实例的构造函数。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

FieldNode

表示 Schema 实例的节点,提供定义存储在数据库中的值的方法。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

名称 类型 可读 可写 说明
nullable boolean 表示数据库字段是否可以为空。
default string 表示Fieldnode的默认值。
type number 表示指定节点对应数据类型的值。

constructor

constructor(name: string)

用于创建带有string字段FieldNode实例的构造函数。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
name string FieldNode的值。

appendChild

appendChild(child: FieldNode): boolean

在当前 FieldNode 中添加一个子节点。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
child FieldNode 要附加的域节点。

返回值:

类型 说明
boolean 返回true表示子节点成功添加到FieldNode;返回false则表示操作失败。

示例:

import ddm from '@ohos.data.distributedKVStore';

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);
}

distributedKVStore.createKVManager

createKVManager(config: KVManagerConfig): KVManager

创建一个KVManager对象实例,用于管理数据库对象。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
config KVManagerConfig 提供KVManager实例的配置信息,包括调用方的包名和用户信息。

返回值:

类型 说明
KVManager 返回创建的KVManager对象实例。

示例:

Stage模型下的示例:

import UIAbility from '@ohos.app.ability.UIAbility';

let kvManager;
export default class EntryAbility extends UIAbility {
    onCreate() {
        console.log("MyAbilityStage onCreate")
        let context = this.context
        const kvManagerConfig = {
            context: context,
            bundleName: 'com.example.datamanagertest',
        }
        try {
            kvManager = distributedKVStore.createKVManager(kvManagerConfig);
            console.log("Succeeded in creating KVManager");
        } catch (e) {
            console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`);
        }
    }
}

FA模型下的示例:

import featureAbility from '@ohos.ability.featureAbility';
let kvManager;
let context = featureAbility.getContext()
const kvManagerConfig = {
    context: context,
    bundleName: 'com.example.datamanagertest',
}
try {
    kvManager = distributedKVStore.createKVManager(kvManagerConfig);
    console.log("Succeeded in creating KVManager");
} catch (e) {
    console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`);
}

KVManager

分布式键值数据库管理实例,用于获取分布式键值数据库的相关信息。在调用KVManager的方法前,需要先通过createKVManager构建一个KVManager实例。

getKVStore

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

通过指定Options和storeId,创建并获取分布式键值数据库,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
storeId string 数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH
options Options 创建分布式键值实例的配置信息。
callback AsyncCallback<T> 回调函数。返回创建的分布式键值数据库实例(根据kvStoreType的不同,可以创建SingleKVStore实例和DeviceKVStore实例)。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100002 Open existed database with changed options.
15100003 Database corrupted.

示例:

let kvStore;
let kvManager;
try {
    const options = {
        createIfMissing: true,
        encrypt: false,
        backup: false,
        autoSync: true,
        kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
        securityLevel: distributedKVStore.SecurityLevel.S2,
    };
    kvManager.getKVStore('storeId', options, function (err, store) {
        if (err) {
            console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log("Succeeded in getting KVStore");
        kvStore = store;
    });
} catch (e) {
    console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

getKVStore

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

通过指定Options和storeId,创建并获取分布式键值数据库,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
storeId string 数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH
options Options 创建分布式键值实例的配置信息。

返回值:

类型 说明
Promise<T> Promise对象。返回创建的分布式键值数据库实例(根据kvStoreType的不同,可以创建SingleKVStore实例和DeviceKVStore实例。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100002 Open existed database with changed options.
15100003 Database corrupted.

示例:

let kvStore;
let kvManager;
try {
    const options = {
        createIfMissing: true,
        encrypt: false,
        backup: false,
        autoSync: true,
        kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
        securityLevel: distributedKVStore.SecurityLevel.S2,
    };
    kvManager.getKVStore('storeId', options).then((store) => {
        console.log("Succeeded in getting KVStore");
        kvStore = store;
    }).catch((err) => {
        console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

closeKVStore

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

通过storeId的值关闭指定的分布式键值数据库,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
appId string 所调用数据库方的包名。
storeId string 要关闭的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH
callback AsyncCallback<void> 回调函数。

示例:

let kvStore;
let kvManager;
const options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true,
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    schema: undefined,
    securityLevel: distributedKVStore.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options, async function (err, store) {
        console.log('Succeeded in getting KVStore');
        kvStore = store;
        kvManager.closeKVStore('appId', 'storeId', function (err, data) {
            if (err != undefined) {
                console.error(`Fail to close KVStore.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in closing KVStore');
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

closeKVStore

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

通过storeId的值关闭指定的分布式键值数据库,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
appId string 所调用数据库方的包名。
storeId string 要关闭的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

let kvManager;
let kvStore;
const options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true,
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    schema: undefined,
    securityLevel: distributedKVStore.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options).then(async (store) => {
        console.log('Succeeded in getting KVStore');
        kvStore = store;
        kvManager.closeKVStore('appId', 'storeId').then(() => {
            console.log('Succeeded in closing KVStore');
        }).catch((err) => {
            console.error(`Fail to close KVStore.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to close KVStore.code is ${e.code},message is ${e.message}`);
}

deleteKVStore

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

通过storeId的值删除指定的分布式键值数据库,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
appId string 所调用数据库方的包名。
storeId string 要删除的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100004 Not found.

示例:

let kvManager;
let kvStore;
const options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true,
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    schema: undefined,
    securityLevel: distributedKVStore.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('store', options, async function (err, store) {
        if (err != undefined) {
            console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting KVStore');
        kvStore = store;
        kvManager.deleteKVStore('appId', 'storeId', function (err, data) {
            if (err != undefined) {
                console.error(`Fail to delete KVStore.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log(`Succeeded in deleting KVStore`);
        });
    });
} catch (e) {
    console.error(`Fail to delete KVStore.code is ${e.code},message is ${e.message}`);
}

deleteKVStore

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

通过storeId的值删除指定的分布式键值数据库,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
appId string 所调用数据库方的包名。
storeId string 要删除的数据库唯一标识符,长度不大于MAX_STORE_ID_LENGTH

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100004 Not found.

示例:

let kvManager;
let kvStore;
const options = {
    createIfMissing: true,
    encrypt: false,
    backup: false,
    autoSync: true,
    kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
    schema: undefined,
    securityLevel: distributedKVStore.SecurityLevel.S2,
}
try {
    kvManager.getKVStore('storeId', options).then(async (store) => {
        console.log('Succeeded in getting KVStore');
        kvStore = store;
        kvManager.deleteKVStore('appId', 'storeId').then(() => {
            console.log('Succeeded in deleting KVStore');
        }).catch((err) => {
            console.error(`Fail to delete KVStore.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to get KVStore.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to delete KVStore.code is ${e.code},message is ${e.message}`);
}

getAllKVStoreId

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

获取所有通过getKVStore方法创建的且没有调用deleteKVStore方法删除的分布式键值数据库的storeId,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
appId string 所调用数据库方的包名。
callback AsyncCallback<string[]> 回调函数。返回所有创建的分布式键值数据库的storeId。

示例:

let kvManager;
try {
    kvManager.getAllKVStoreId('appId', function (err, data) {
        if (err != undefined) {
            console.error(`Fail to get AllKVStoreId.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting AllKVStoreId');
        console.log(`GetAllKVStoreId size = ${data.length}`);
    });
} catch (e) {
    console.error(`Fail to get AllKVStoreId.code is ${e.code},message is ${e.message}`);
}

getAllKVStoreId

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

获取所有通过getKVStore方法创建的且没有调用deleteKVStore方法删除的分布式键值数据库的storeId,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
appId string 所调用数据库方的包名。

返回值:

类型 说明
Promise<string[]> Promise对象。返回所有创建的分布式键值数据库的storeId。

示例:

let kvManager;
try {
    console.log('GetAllKVStoreId');
    kvManager.getAllKVStoreId('appId').then((data) => {
        console.log('Succeeded in getting AllKVStoreId');
        console.log(`GetAllKVStoreId size = ${data.length}`);
    }).catch((err) => {
        console.error(`Fail to get AllKVStoreId.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to get AllKVStoreId.code is ${e.code},message is ${e.message}`);
}

on('distributedDataServiceDie')

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

订阅服务状态变更通知。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
event string 订阅的事件名,固定为'distributedDataServiceDie',即服务状态变更事件。
deathCallback Callback<void> 回调函数。

示例:

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.code is ${e.code},message is ${e.message}`);
}

off('distributedDataServiceDie')

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

取消订阅服务状态变更通知。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
event string 取消订阅的事件名,固定为'distributedDataServiceDie',即服务状态变更事件。
deathCallback Callback<void> 回调函数。

示例:

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.code is ${e.code},message is ${e.message}`);
}

KVStoreResultSet

提供获取数据库结果集的相关方法,包括查询和移动数据读取位置等。

在调用KVStoreResultSet的方法前,需要先通过getKVStore构建一个SingleKVStore或者DeviceKVStore实例。

getCount

getCount(): number

获取结果集中的总行数。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
number 返回数据的总行数。

示例:

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

获取结果集中当前的读取位置。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
number 返回当前读取位置。

示例:

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

将读取位置移动到第一行。如果结果集为空,则返回false。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示操作成功;返回false则表示操作失败。

示例:

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

将读取位置移动到最后一行。如果结果集为空,则返回false。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示操作成功;返回false则表示操作失败。

示例:

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

将读取位置移动到下一行。如果结果集为空,则返回false。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示操作成功;返回false则表示操作失败。

示例:

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

将读取位置移动到上一行。如果结果集为空,则返回false。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示操作成功;返回false则表示操作失败。

示例:

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

将读取位置移动到当前位置的相对偏移量。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
offset number 表示与当前位置的相对偏移量,负偏移表示向后移动,正偏移表示向前移动。

返回值:

类型 说明
boolean 返回true表示操作成功;返回false则表示操作失败。

示例:

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('Succeeded in getting resultSet');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
    });
    const moved5 = resultSet.move(1);
    console.log(`Succeeded in moving.moved5 = ${moved5}`);
} catch (e) {
    console.log(`Fail to move.code is ${e.code},message is ${e.message}`);
}

moveToPosition

moveToPosition(position: number): boolean

将读取位置从 0 移动到绝对位置。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
position number 表示绝对位置。

返回值:

类型 说明
boolean 返回true表示操作成功;返回false则表示操作失败。

示例

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('Succeeded in getting resultSet');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
    });
    const moved6 = resultSet.moveToPosition(1);
    console.log(`Succeeded in moving to position.moved6=${moved6}`);
} catch (e) {
    console.error(`Fail to move to position.code is ${e.code},message is ${e.message}`);
}

isFirst

isFirst(): boolean

检查读取位置是否为第一行。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示读取位置为第一行;返回false表示读取位置不是第一行。

示例:

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

检查读取位置是否为最后一行。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示读取位置为最后一行;返回false表示读取位置不是最后一行。

示例:

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

检查读取位置是否在第一行之前。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示读取位置在第一行之前;返回false表示读取位置不在第一行之前。

示例:

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

检查读取位置是否在最后一行之后。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
boolean 返回true表示读取位置在最后一行之后;返回false表示读取位置不在最后一行之后。

示例:

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

从当前位置获取对应的键值对。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Entry 返回键值对。

示例:

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

使用谓词表示数据库查询,提供创建Query实例、查询数据库中的数据和添加谓词的方法。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

constructor

constructor()

用于创建Schema实例的构造函数。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

reset

reset(): Query

重置Query对象。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Query 返回重置的Query对象。

示例:

try {
    let query = new distributedKVStore.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

构造一个Query对象来查询具有指定字段的条目,其值等于指定的值。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value number|string|boolean 表示指定的值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.equalTo("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.ode is ${e.code},message is ${e.message}`);
}

notEqualTo

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

构造一个Query对象以查询具有指定字段且值不等于指定值的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value number|string|boolean 表示指定的值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.notEqualTo("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

greaterThan

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

构造一个Query对象以查询具有大于指定值的指定字段的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value number|string|boolean 表示指定的值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.greaterThan("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

lessThan

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

构造一个Query对象以查询具有小于指定值的指定字段的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value number|string 表示指定的值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.lessThan("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

greaterThanOrEqualTo

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

构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value number|string 表示指定的值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.greaterThanOrEqualTo("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

lessThanOrEqualTo

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

构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value number|string 表示指定的值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.lessThanOrEqualTo("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

isNull

isNull(field: string): Query

构造一个Query对象以查询具有值为null的指定字段的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.isNull("field");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

inNumber

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

构造一个Query对象以查询具有指定字段的条目,其值在指定的值列表中。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
valueList number[] 表示指定的值列表。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.inNumber("field", [0, 1]);
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

inString

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

构造一个Query对象以查询具有指定字段的条目,其值在指定的字符串值列表中。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
valueList string[] 表示指定的字符串值列表。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.inString("field", ['test1', 'test2']);
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

notInNumber

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

构造一个Query对象以查询具有指定字段的条目,该字段的值不在指定的值列表中。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
valueList number[] 表示指定的值列表。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.notInNumber("field", [0, 1]);
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

notInString

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

构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
valueList string[] 表示指定的字符串值列表。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.notInString("field", ['test1', 'test2']);
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

like

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

构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value string 表示指定的字符串值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.like("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

unlike

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

构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。
value string 表示指定的字符串值。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.unlike("field", "value");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

and

and(): Query

构造一个带有与条件的查询对象。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Query 返回查询对象。

示例:

try {
    let query = new distributedKVStore.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

构造一个带有或条件的Query对象。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Query 返回查询对象。

示例:

try {
    let query = new distributedKVStore.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

构造一个Query对象,将查询结果按升序排序。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.notEqualTo("field", "value");
    query.orderByAsc("field");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

orderByDesc

orderByDesc(field: string): Query

构造一个Query对象,将查询结果按降序排序。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.notEqualTo("field", "value");
    query.orderByDesc("field");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

limit

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

构造一个Query对象来指定结果的数量和开始位置。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
total number 表示指定的结果数。
offset number 表示起始位置。

返回值:

类型 说明
Query 返回Query对象。

示例:

let total = 10;
let offset = 1;
try {
    let query = new distributedKVStore.Query();
    query.notEqualTo("field", "value");
    query.limit(total, offset);
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
     console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

isNotNull

isNotNull(field: string): Query

构造一个Query对象以查询具有值不为null的指定字段的条目。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
fieId string 表示指定字段,不能包含' ^ '。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.isNotNull("field");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

beginGroup

beginGroup(): Query

创建一个带有左括号的查询条件组。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.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

创建一个带有右括号的查询条件组。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.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

创建具有指定键前缀的查询条件。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
prefix string 表示指定的键前缀。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.prefixKey("$.name");
    query.prefixKey("0");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

setSuggestIndex

setSuggestIndex(index: string): Query

设置一个指定的索引,将优先用于查询。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
index string 指示要设置的索引。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.setSuggestIndex("$.name");
    query.setSuggestIndex("0");
    console.log(`query is ${query.getSqlLike()}`);
    query = null;
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

deviceId

deviceId(deviceId:string):Query

添加设备ID作为key的前缀。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
deviceId string 指示查询的设备ID。

返回值:

类型 说明
Query 返回Query对象。

示例:

try {
    let query = new distributedKVStore.Query();
    query.deviceId("deviceId");
    console.log(`query is ${query.getSqlLike()}`);
} catch (e) {
    console.error(`duplicated calls should be ok.code is ${e.code},message is ${e.message}`);
}

getSqlLike

getSqlLike():string

获取Query对象的查询语句。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
string 返回一个字段列中包含对应子串的结果。

示例:

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

SingleKVStore

SingleKVStore数据库实例,提供增加数据、删除数据和订阅数据变更、订阅数据同步完成的方法。

在调用SingleKVStore的方法前,需要先通过getKVStore构建一个SingleKVStore实例。

put

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

添加指定类型键值对到数据库,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要添加数据的key,不能为空且长度不大于MAX_KEY_LENGTH
value Uint8Array | string | number | boolean 要添加数据的value,支持Uint8Array、number 、 string 、boolean,Uint8Array、string 的长度不大于MAX_VALUE_LENGTH
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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.error(`Fail to put.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log("Succeeded in putting");
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

put

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

添加指定类型键值对到数据库,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要添加数据的key,不能为空且长度不大于MAX_KEY_LENGTH
value Uint8Array | string | number | boolean 要添加数据的value,支持Uint8Array、number 、 string 、boolean,Uint8Array、string 的长度不大于MAX_VALUE_LENGTH

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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(`Succeeded in putting.data=${data}`);
    }).catch((err) => {
        console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

putBatch

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

批量插入键值对到SingleKVStore数据库中,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
entries Entry[] 表示要批量插入的键值对。
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting Batch');
        kvStore.getEntries('batch_test_string_key', function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
            }
            console.log('Succeeded in getting Entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `);
}

putBatch

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

批量插入键值对到SingleKVStore数据库中,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
entries Entry[] 表示要批量插入的键值对。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries).then(async (entries) => {
        console.log('Succeeded in putting Batch');
        kvStore.getEntries('batch_test_string_key').then((entries) => {
            console.log('Succeeded in getting Entries');
            console.log(`PutBatch ${entries}`);
        }).catch((err) => {
            console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `);
}

putBatch

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

将值写入SingleKVStore数据库,使用callback异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
value Array<ValuesBucket> 表示要插入的数据。
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
    })
} catch (e) {
    console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`);
}

putBatch

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

将valuesbucket类型的值写入SingleKVStore数据库,使用Promise异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
value Array<ValuesBucket> 表示要插入的数据。

返回值:

类型 说明
Promise<void> 五返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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 (data) => {
        console.log(`Succeeded in putting patch`);
    }).catch((err) => {
        console.error(`putBatch fail.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`putBatch fail.code is ${e.code},message is ${e.message}`);
}

delete

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

从数据库中删除指定键值的数据,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要删除数据的key,不能为空且长度不大于MAX_KEY_LENGTH
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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.error(`Fail to put.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting');
        kvStore.delete(KEY_TEST_STRING_ELEMENT, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to delete.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in deleting');
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

delete

delete(key: string): Promise<void>

从数据库中删除指定键值的数据,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要删除数据的key,不能为空且长度不大于MAX_KEY_LENGTH

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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(`Succeeded in putting: ${data}`);
        kvStore.delete(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log('Succeeded in deleting');
        }).catch((err) => {
            console.error(`Fail to delete.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

delete

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

从数据库中删除符合predicates条件的键值对,使用callback异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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('Succeeded in deleting');
        } else {
            console.error(`Fail to delete.code is ${err.code},message is ${err.message}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

delete

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

从数据库中删除符合predicates条件的键值对,使用Promise异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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(`Succeeded in putting: ${data}`);
        kvStore.delete(predicates).then((data) => {
            console.log('Succeeded in deleting');
        }).catch((err) => {
            console.error(`Fail to delete.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

deleteBatch

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

批量删除SingleKVStore数据库中的键值对,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keys string[] 表示要批量删除的键值对。
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
        keys.push(key + i);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting Batch');
        kvStore.deleteBatch(keys, async function (err, data) {
            if (err != undefined) {
                console.error(`Fail to delete Batch.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in deleting Batch');
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

deleteBatch

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

批量删除SingleKVStore数据库中的键值对,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keys string[] 表示要批量删除的键值对。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
        keys.push(key + i);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries).then(async (data) => {
        console.log('Succeeded in putting Batch');
        kvStore.deleteBatch(keys).then((err) => {
            console.log('Succeeded in deleting Batch');
        }).catch((err) => {
            console.error(`Fail to delete Batch.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

removeDeviceData

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

删除指定设备的数据,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 表示要删除设备的名称。
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

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('Succeeded in putting data');
        const deviceid = 'no_exist_device_id';
        kvStore.removeDeviceData(deviceid, async function (err, data) {
            if (err == undefined) {
                console.log('succeeded in removing device data');
            } else {
                console.error(`Fail to remove device data.code is ${err.code},message is ${err.message} `);
                kvStore.get(KEY_TEST_STRING_ELEMENT, async function (err, data) {
                    console.log('Succeeded in getting data');
                });
            }
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`)
}

removeDeviceData

removeDeviceData(deviceId: string): Promise<void>

删除指定设备的数据,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 表示要删除设备的名称。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

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('Succeeded in putting data');
    }).catch((err) => {
        console.error(`Fail to put data.code is ${err.code},message is ${err.message} `);
    });
    const deviceid = 'no_exist_device_id';
    kvStore.removeDeviceData(deviceid).then((err) => {
        console.log('succeeded in removing device data');
    }).catch((err) => {
        console.error(`Fail to remove device data.code is ${err.code},message is ${err.message} `);
    });
    kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => {
        console.log('Succeeded in getting data');
    }).catch((err) => {
        console.error(`Fail to get data.code is ${err.code},message is ${err.message} `);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`)
}

get

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

获取指定键的值,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要查询数据的key,不能为空且长度不大于MAX_KEY_LENGTH
callback AsyncCallback<boolean | string | number | Uint8Array> 回调函数。返回获取查询的值。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.
15100005 Database or result set already closed.

示例:

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.error(`Fail to put.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log("Succeeded in putting");
        kvStore.get(KEY_TEST_STRING_ELEMENT, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to get.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log(`Succeeded in getting data.data=${data}`);
        });
    });
} catch (e) {
    console.error(`Fail to get.code is ${e.code},message is ${e.message}`);
}

get

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

获取指定键的值,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要查询数据的key,不能为空且长度不大于MAX_KEY_LENGTH

返回值:

类型 说明
Promise<Uint8Array | string | boolean | number> Promise对象。返回获取查询的值。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.
15100005 Database or result set already closed.

示例:

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(`Succeeded in putting data.data=${data}`);
        kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log(`Succeeded in getting data.data=${data}`);
        }).catch((err) => {
            console.error(`Fail to get.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to get.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取匹配指定键前缀的所有键值对,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。
callback AsyncCallback<Entry[]> 回调函数。返回匹配指定前缀的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting Batch');
        kvStore.getEntries('batch_test_string_key', function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting Entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `);
}

getEntries

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

获取匹配指定键前缀的所有键值对,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。

返回值:

类型 说明
Promise<Entry[]> Promise对象。返回匹配指定前缀的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries).then(async (entries) => {
        console.log('Succeeded in putting Batch');
        kvStore.getEntries('batch_test_string_key').then((entries) => {
            console.log('Succeeded in getting Entries');
            console.log(`PutBatch ${entries}`);
        }).catch((err) => {
            console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `);
}

getEntries

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

获取与指定Query对象匹配的键值对列表,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示要匹配的键前缀。
callback AsyncCallback<Entry[]> 回调函数。返回与指定Query对象匹配的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.BYTE_ARRAY,
                value: arr
            }
        }
        entries.push(entry);
    }
    console.log(`entries: {entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        console.log('Succeeded in putting Batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query, function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting Entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        });
    });
} catch (e) {
    console.error(`Fail to get Entries.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取与指定Query对象匹配的键值对列表,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。

返回值:

类型 说明
Promise<Entry[]> Promise对象。返回与指定Query对象匹配的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.BYTE_ARRAY,
                value: arr
            }
        }
        entries.push(entry);
    }
    console.log(`entries: {entries}`);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting Batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query).then((entries) => {
            console.log('Succeeded in getting Entries');
        }).catch((err) => {
            console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`)
    });
    console.log('Succeeded in getting Entries');
} catch (e) {
    console.error(`Fail to get Entries.code is ${e.code},message is ${e.message}`);
}

getResultSet

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

从SingleKVStore数据库中获取具有指定前缀的结果集,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。
callback AsyncCallback<KVStoreResultSet> 回调函数。返回具有指定前缀的结果集。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        kvStore.getResultSet('batch_test_string_key', async function (err, result) {
            if (err != undefined) {
                console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting result set');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                if (err != undefined) {
                    console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
                    return;
                }
                console.log('Succeeded in closing result set');
            })
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

getResultSet

getResultSet(keyPrefix: string): Promise<KVStoreResultSet>

从SingleKVStore数据库中获取具有指定前缀的结果集,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。返回具有指定前缀的结果集。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing result set');
    }).catch((err) => {
        console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSet

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

获取与指定Query对象匹配的KVStoreResultSet对象,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。
callback AsyncCallback<KVStoreResultSet> 回调函数,获取与指定Query对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSet(query, async function (err, result) {
            if (err != undefined) {
                console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting result set');
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

getResultSet

getResultSet(query: Query): Promise<KVStoreResultSet>

获取与指定Query对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。获取与指定Query对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    const query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet(query).then((result) => {
        console.log('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}    

getResultSet

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

获取与指定Predicate对象匹配的KVStoreResultSet对象,使用callback异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。
callback AsyncCallback<KVStoreResultSet> 回调函数,获取与指定Predicates对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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) {
        if (err != undefined) {
            console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting result set');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in closing result set');
        })
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSet

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

获取与指定Predicate对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。

返回值:

类型 说明
Promise<KVStoreResultSet> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing result set');
    }).catch((err) => {
        console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

closeResultSet

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

关闭由SingleKvStore.getResultSet返回的KVStoreResultSet对象,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
resultSet KVStoreResultSet 表示要关闭的KVStoreResultSet对象。
callback AsyncCallback<void> 回调函数。

示例:

let kvStore;
try {
    let resultSet = null;
    kvStore.closeResultSet(resultSet, function (err, data) {
        if (err == undefined) {
            console.log('Succeeded in closing result set');
        } else {
            console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

closeResultSet

closeResultSet(resultSet: KVStoreResultSet): Promise<void>

关闭由SingleKvStore.getResultSet返回的KVStoreResultSet对象,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
resultSet KVStoreResultSet 表示要关闭的KVStoreResultSet对象。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

let kvStore;
try {
    let resultSet = null;
    kvStore.closeResultSet(resultSet).then(() => {
        console.log('Succeeded in closing result set');
    }).catch((err) => {
        console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSize

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

获取与指定Query对象匹配的结果数,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。
callback AsyncCallback<number> 回调函数。返回与指定Query对象匹配的结果数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('Succeeded in putting batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSize(query, async function (err, resultSize) {
            if (err != undefined) {
                console.error(`Fail to get result size.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting result set size');
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSize

getResultSize(query: Query): Promise<number>

获取与指定Query对象匹配的结果数,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。

返回值:

类型 说明
Promise<number> Promise对象。获取与指定QuerV9对象匹配的结果数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    const query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSize(query).then((resultSize) => {
        console.log('Succeeded in getting result set size');
    }).catch((err) => {
        console.error(`Fail to get result size.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

backup

backup(file:string, callback: AsyncCallback<void>):void

以指定名称备份数据库,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
file string 备份数据库的指定名称,不能为空且长度不大于MAX_KEY_LENGTH
callback AsyncCallback<void> 回调函数。当以指定名称备份数据库成功,err为undefined,否则为错误对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
let file = "BK001";
try {
    kvStore.backup(file, (err, data) => {
        if (err) {
            console.error(`Fail to backup.code is ${err.code},message is ${err.message} `);
        } else {
            console.info(`Succeeded in backupping data.data=${data}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

backup

backup(file:string): Promise<void>

以指定名称备份数据库,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
file string 备份数据库的指定名称,不能为空且长度不大于MAX_KEY_LENGTH

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
let file = "BK001";
try {
    kvStore.backup(file).then((data) => {
        console.info(`Succeeded in backupping data.data=${data}`);
    }).catch((err) => {
        console.error(`Fail to backup.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

restore

restore(file:string, callback: AsyncCallback<void>):void

从指定的数据库文件恢复数据库,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
file string 指定的数据库文件名称,不能为空且长度不大于MAX_KEY_LENGTH
callback AsyncCallback<void> 回调函数。当从指定的数据库文件恢复数据库成功,err为undefined,否则为错误对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
let file = "BK001";
try {
    kvStore.restore(file, (err, data) => {
        if (err) {
            console.error(`Fail to restore.code is ${err.code},message is ${err.message}`);
        } else {
            console.info(`Succeeded in restoring data.data=${data}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

restore

restore(file:string): Promise<void>

从指定的数据库文件恢复数据库,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
file string 指定的数据库文件名称,不能为空且长度不大于MAX_KEY_LENGTH

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
let file = "BK001";
try {
    kvStore.restore(file).then((data) => {
        console.info(`Succeeded in restoring data.data=${data}`);
    }).catch((err) => {
        console.error(`Fail to restore.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

deleteBackup

deleteBackup(files:Array<string>, callback: AsyncCallback<Array<[string, number]>>):void

根据指定名称删除备份文件,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
files Array<string> 删除备份文件所指定的名称,不能为空且长度不大于MAX_KEY_LENGTH
callback AsyncCallback<Array<[string, number]>> 回调函数,返回删除备份的文件名及其处理结果。

示例:

let kvStore;
let files = ["BK001", "BK002"];
try {
    kvStore.deleteBackup(files, (err, data) => {
        if (err) {
            console.error(`Fail to delete Backup.code is ${err.code},message is ${err.message}`);
        } else {
            console.info(`Succeed in deleting Backup.data=${data}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

deleteBackup

deleteBackup(files:Array<string>): Promise<Array<[string, number]>>

根据指定名称删除备份文件,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
files Array<string> 删除备份文件所指定的名称,不能为空且长度不大于MAX_KEY_LENGTH

返回值:

类型 说明
Promise<Array<[string, number]>> Promise对象,返回删除备份的文件名及其处理结果。

示例:

let kvStore;
let files = ["BK001", "BK002"];
try {
    kvStore.deleteBackup(files).then((data) => {
        console.info(`Succeed in deleting Backup.data=${data}`);
    }).catch((err) => {
        console.error(`Fail to delete Backup.code is ${err.code},message is ${err.message}`);
    })
} catch (e) {
    console.log(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

startTransaction

startTransaction(callback: AsyncCallback<void>): void

启动SingleKVStore数据库中的事务,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
function putBatchString(len, prefix) {
    let entries = [];
    for (var i = 0; i < len; i++) {
        var entry = {
            key: prefix + i,
            value: {
                type: distributedKVStore.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) {
        if (err != undefined) {
            console.error(`Fail to start Transaction.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in starting Transaction');
        let entries = putBatchString(10, 'batch_test_string_key');
        console.log(`entries: ${entries}`);
        kvStore.putBatch(entries, async function (err, data) {
            if (err != undefined) {
                console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in putting Batch');
        });
    });
} catch (e) {
    console.error(`Fail to start Transaction.code is ${e.code},message is ${e.message}`);
}

startTransaction

startTransaction(): Promise<void>

启动SingleKVStore数据库中的事务,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    var count = 0;
    kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, function (data) {
        console.log(`startTransaction 0 ${data}`);
        count++;
    });
    kvStore.startTransaction().then(async (err) => {
        console.log('Succeeded in starting Transaction');
    }).catch((err) => {
        console.error(`Fail to start Transaction.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to start Transaction.code is ${e.code},message is ${e.message}`);
}

commit

commit(callback: AsyncCallback<void>): void

提交SingleKVStore数据库中的事务,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.commit(function (err, data) {
        if (err == undefined) {
            console.log('Succeeded in committing');
        } else {
            console.error(`Fail to commit.code is ${err.code},message is ${err.message}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

commit

commit(): Promise<void>

提交SingleKVStore数据库中的事务,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.commit().then(async (err) => {
        console.log('Succeeded in committing');
    }).catch((err) => {
        console.error(`Fail to commit.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.ode is ${e.code},message is ${e.message}`);
}

rollback

rollback(callback: AsyncCallback<void>): void

在SingleKVStore数据库中回滚事务,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<void> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.rollback(function (err,data) {
        if (err == undefined) {
            console.log('Succeeded in rolling back');
        } else {
            console.error(`Fail to rollback.code is ${err.code},message is ${err.message}`);
        }
    });
}catch(e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

rollback

rollback(): Promise<void>

在SingleKVStore数据库中回滚事务,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.rollback().then(async (err) => {
        console.log('Succeeded in rolling back');
    }).catch((err) => {
        console.error(`Fail to rollback.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

enableSync

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

设定是否开启同步,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
enabled boolean 设定是否开启同步,true表示开启同步,false表示不启用同步。
callback AsyncCallback<void> 回调函数。

示例:

let kvStore;
try {
    kvStore.enableSync(true, function (err, data) {
        if (err == undefined) {
            console.log('Succeeded in enabling sync');
        } else {
            console.error(`Fail to enable sync.code is ${err.code},message is ${err.message}`);
        }
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

enableSync

enableSync(enabled: boolean): Promise<void>

设定是否开启同步,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
enabled boolean 设定是否开启同步,true表示开启同步,false表示不启用同步。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

let kvStore;
try {
    kvStore.enableSync(true).then((err) => {
        console.log('Succeeded in enabling sync');
    }).catch((err) => {
        console.error(`Fail to enable sync.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

setSyncRange

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

设置同步范围标签,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
localLabels string[] 表示本地设备的同步标签。
remoteSupportLabels string[] 表示要同步数据的设备的同步标签。
callback AsyncCallback<void> 回调函数。

示例:

let kvStore;
try {
    const localLabels = ['A', 'B'];
    const remoteSupportLabels = ['C', 'D'];
    kvStore.setSyncRange(localLabels, remoteSupportLabels, function (err, data) {
        if (err != undefined) {
            console.error(`Fail to set syncRange.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in setting syncRange');
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

setSyncRange

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

设置同步范围标签,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
localLabels string[] 表示本地设备的同步标签。
remoteSupportLabels string[] 表示要同步数据的设备的同步标签。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

let kvStore;
try {
    const localLabels = ['A', 'B'];
    const remoteSupportLabels = ['C', 'D'];
    kvStore.setSyncRange(localLabels, remoteSupportLabels).then((err) => {
        console.log('Succeeded in setting syncRange');
    }).catch((err) => {
        console.error(`Fail to set syncRange.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

setSyncParam

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

设置数据库同步允许的默认延迟,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
defaultAllowedDelayMs number 表示数据库同步允许的默认延迟,以毫秒为单位。
callback AsyncCallback<void> 回调函数。

示例:

let kvStore;
try {
    const defaultAllowedDelayMs = 500;
    kvStore.setSyncParam(defaultAllowedDelayMs, function (err, data) {
        if (err != undefined) {
            console.error(`Fail to set syncParam.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in setting syncParam');
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

setSyncParam

setSyncParam(defaultAllowedDelayMs: number): Promise<void>

设置数据库同步允许的默认延迟,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
defaultAllowedDelayMs number 表示数据库同步允许的默认延迟,以毫秒为单位。

返回值:

类型 说明
Promise<void> 无返回结果的Promise对象。

示例:

let kvStore;
try {
    const defaultAllowedDelayMs = 500;
    kvStore.setSyncParam(defaultAllowedDelayMs).then((err) => {
        console.log('Succeeded in setting syncParam');
    }).catch((err) => {
        console.error(`Fail to set syncParam.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

sync

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

在手动同步方式下,触发数据库同步。关于键值型数据库的同步方式说明,请见键值型数据库跨设备数据同步

说明:

其中deviceIds通过调用deviceManager.getTrustedDeviceListSync方法得到。deviceManager模块的接口均为系统接口,仅系统应用可用。

需要权限: ohos.permission.DISTRIBUTED_DATASYNC。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
deviceIds string[] 同一组网环境下,需要同步的设备的deviceId列表。
mode SyncMode 同步模式。
delayMs number 可选参数,允许延时时间,单位:ms(毫秒),默认为0。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.

示例:

import deviceManager from '@ohos.distributedHardware.deviceManager';

let devManager;
let kvStore;
const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
// create deviceManager
deviceManager.createDeviceManager('bundleName', (err, value) => {
  if (!err) {
    devManager = value;
    let deviceIds = [];
    if (devManager != null) {
      var devices = devManager.getTrustedDeviceListSync();
      for (var i = 0; i < devices.length; i++) {
        deviceIds[i] = devices[i].deviceId;
      }
    }
    try {
      kvStore.on('syncComplete', function (data) {
        console.log('Sync dataChange');
      });
      kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err, data) {
        if (err != undefined) {
          console.error(`Fail to sync.code is ${err.code},message is ${err.message}`);
          return;
        }
        console.log('Succeeded in putting data');
        const mode = distributedKVStore.SyncMode.PULL_ONLY;
        kvStore.sync(deviceIds, mode, 1000);
      });
    } catch (e) {
      console.error(`Fail to sync.code is ${e.code},message is ${e.message}`);
    }
  }
});

sync

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

在手动同步方式下,触发数据库同步,此方法为同步方法。关于键值型数据库的同步方式说明,请见键值型数据库跨设备数据同步

说明:

其中deviceIds通过调用deviceManager.getTrustedDeviceListSync方法得到。deviceManager模块的接口均为系统接口,仅系统应用可用。

需要权限: ohos.permission.DISTRIBUTED_DATASYNC。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
deviceIds string[] 同一组网环境下,需要同步的设备的deviceId列表。
mode SyncMode 同步模式。
query Query 表示数据库的查询谓词条件
delayMs number 可选参数,允许延时时间,单位:ms(毫秒),默认为0。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.

示例:

import deviceManager from '@ohos.distributedHardware.deviceManager';

let devManager;
let kvStore;
const KEY_TEST_SYNC_ELEMENT = 'key_test_sync';
const VALUE_TEST_SYNC_ELEMENT = 'value-string-001';
// create deviceManager
deviceManager.createDeviceManager('bundleName', (err, value) => {
  if (!err) {
    devManager = value;
    let deviceIds = [];
    if (devManager != null) {
      var devices = devManager.getTrustedDeviceListSync();
      for (var i = 0; i < devices.length; i++) {
        deviceIds[i] = devices[i].deviceId;
      }
    }
    try {
      kvStore.on('syncComplete', function (data) {
        console.log('Sync dataChange');
      });
      kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err, data) {
        if (err != undefined) {
          console.error(`Fail to sync.code is ${err.code},message is ${err.message}`);
          return;
        }
        console.log('Succeeded in putting data');
        const mode = distributedKVStore.SyncMode.PULL_ONLY;
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        query.deviceId('localDeviceId');
        kvStore.sync(deviceIds, query, mode, 1000);
      });
    } catch (e) {
      console.error(`Fail to sync.code is ${e.code},message is ${e.message}`);
    }
  }
});

on('dataChange')

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

订阅指定类型的数据变更通知。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
event string 订阅的事件名,固定为'dataChange',表示数据变更事件。
type SubscribeType 表示订阅的类型。
listener Callback<ChangeNotification> 回调函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100001 Over max subscribe limits.
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_LOCAL, function (data) {
        console.log(`dataChange callback call data: ${data}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

on('syncComplete')

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

订阅同步完成事件回调通知。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
event string 订阅的事件名,固定为'syncComplete',表示同步完成事件。
syncCallback Callback<Array<[string, number]>> 回调函数。用于向调用方发送同步结果的回调。

示例:

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('succeeded in putting');
    }).catch((err) => {
        console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to subscribe syncComplete.code is ${e.code},message is ${e.message}`);
}

off('dataChange')

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

取消订阅数据变更通知。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
event string 取消订阅的事件名,固定为'dataChange',表示数据变更事件。
listener Callback<ChangeNotification> 取消订阅的函数。如不设置callback,则取消所有已订阅的函数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
class KvstoreModel {
    call(data) {
        console.log(`dataChange : ${data}`);
    }

    subscribeDataChange() {
        try {
            if (kvStore != null) {
                kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call);
            }
        } catch (err) {
            console.error(`Fail to subscribeDataChange.code is ${err.code},message is ${err.message}`);
        }
    }

    unsubscribeDataChange() {
        try {
            if (kvStore != null) {
                kvStore.off('dataChange', this.call);
            }
        } catch (err) {
            console.error(`Fail to unsubscribeDataChange.code is ${err.code},message is ${err.message}`);
        }
    }
}

off('syncComplete')

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

取消订阅同步完成事件回调通知。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
event string 取消订阅的事件名,固定为'syncComplete',表示同步完成事件。
syncCallback Callback<Array<[string, number]>> 取消订阅的函数。如不设置callback,则取消所有已订阅的函数。

示例:

let kvStore;
class KvstoreModel {
    call(data) {
        console.log(`syncComplete : ${data}`);
    }

    subscribeDataChange() {
        try {
            if (kvStore != null) {
                kvStore.on('syncComplete', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call);
            }
        } catch (err) {
            console.error(`Fail to subscribeDataChange.code is ${err.code},message is ${err.message}`);
        }
    }

    unsubscribeDataChange() {
        try {
            if (kvStore != null) {
                kvStore.off('dsyncComplete', this.call);
            }
        } catch (err) {
            console.error(`Fail to unsubscribeDataChange.code is ${err.code},message is ${err.message}`);
        }
    }
}

getSecurityLevel

getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void

获取数据库的安全级别,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
callback AsyncCallback<SecurityLevel> 回调函数。返回数据库的安全级别。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.getSecurityLevel(function (err, data) {
        if (err != undefined) {
            console.error(`Fail to get SecurityLevel.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting securityLevel');
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

getSecurityLevel

getSecurityLevel(): Promise<SecurityLevel>

获取数据库的安全级别,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

返回值:

类型 说明
Promise<SecurityLevel> Promise对象。返回数据库的安全级别。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    kvStore.getSecurityLevel().then((data) => {
        console.log('Succeeded in getting securityLevel');
    }).catch((err) => {
        console.error(`Fail to get SecurityLevel.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

DeviceKVStore

设备协同数据库,继承自SingleKVStore,提供查询数据和同步数据的方法。

设备协同数据库,以设备维度对数据进行区分,每台设备仅能写入和修改本设备的数据,其它设备的数据对其是只读的,无法修改其它设备的数据。

比如,可以使用设备协同数据库实现设备间的图片分享,可以查看其他设备的图片,但无法修改和删除其他设备的图片。

在调用DeviceKVStore的方法前,需要先通过getKVStore构建一个DeviceKVStore实例。

get

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

获取本设备指定键的值,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要查询数据的key,不能为空且长度不大于MAX_KEY_LENGTH
callback AsyncCallback<boolean | string | number | Uint8Array> 回调函数。返回获取查询的值。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.
15100005 Database or result set already closed.

示例:

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.error(`Fail to put.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log("Succeeded in putting");
        kvStore.get(KEY_TEST_STRING_ELEMENT, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to get.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log(`Succeeded in getting data.data=${data}`);
        });
    });
} catch (e) {
    console.error(`Fail to get.code is ${e.code},message is ${e.message}`);
}

get

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

获取本设备指定键的值,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
key string 要查询数据的key,不能为空且长度不大于MAX_KEY_LENGTH

返回值:

类型 说明
Promise<Uint8Array | string | boolean | number> Promise对象。返回获取查询的值。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.
15100005 Database or result set already closed.

示例:

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(`Succeeded in putting data.data=${data}`);
        kvStore.get(KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log(`Succeeded in getting data.data=${data}`);
        }).catch((err) => {
            console.error(`Fail to get.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to get.code is ${e.code},message is ${e.message}`);
}

get

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

获取与指定设备ID和key匹配的string值,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
key string 表示要查询key值的键。
callback AsyncCallback<boolean|string|number|Uint8Array> 回调函数,返回匹配给定条件的字符串值。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.
15100005 Database or result set already closed.

示例:

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) {
        if (err != undefined) {
            console.error(`Fail to put.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting');
        kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to get.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting');
        });
    })
} catch (e) {
    console.error(`Fail to get.code is ${e.code},message is ${e.message}`);
}

get

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

获取与指定设备ID和key匹配的string值,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
key string 表示要查询key值的键。

返回值:

类型 说明
Promise<boolean|string|number|Uint8Array> Promise对象。返回匹配给定条件的字符串值。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100004 Not found.
15100005 Database or result set already closed.

示例:

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('Succeeded in putting');
        kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data) => {
            console.log('Succeeded in getting');
        }).catch((err) => {
            console.error(`Fail to get.code is ${err.code},message is ${err.message}`);
        });
    }).catch((error) => {
        console.error(`Fail to put.code is ${error.code},message is ${error.message}`);
    });
} catch (e) {
    console.error(`Fail to get.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取匹配本设备指定键前缀的所有键值对,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。
callback AsyncCallback<Entry[]> 回调函数。返回匹配指定前缀的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting Batch');
        kvStore.getEntries('batch_test_string_key', function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting Entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `);
}

getEntries

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

获取匹配本设备指定键前缀的所有键值对,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。

返回值:

类型 说明
Promise<Entry[]> Promise对象。返回匹配指定前缀的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries).then(async (entries) => {
        console.log('Succeeded in putting Batch');
        kvStore.getEntries('batch_test_string_key').then((entries) => {
            console.log('Succeeded in getting Entries');
            console.log(`PutBatch ${entries}`);
        }).catch((err) => {
            console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put Batch.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message} `);
}

getEntries

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

获取与指定设备ID和key前缀匹配的所有键值对,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
keyPrefix string 表示要匹配的键前缀。
callback AsyncCallback<Entry[]> 回调函数,返回满足给定条件的所有键值对的列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries : ${entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        kvStore.getEntries('localDeviceId', 'batch_test_string_key', function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        });
    });
} catch (e) {
    console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取与指定设备ID和key前缀匹配的所有键值对,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
keyPrefix string 表示要匹配的键前缀。

返回值:

类型 说明
Promise<Entry[]> Promise对象。返回匹配给定条件的所有键值对的列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
        kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries) => {
            console.log('Succeeded in getting entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
            console.log(`entries[0].value: ${entries[0].value}`);
            console.log(`entries[0].value.value: ${entries[0].value.value}`);
        }).catch((err) => {
            console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to put batch.code is ${e.code},message is ${e.message}`);
}    

getEntries

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

获取本设备与指定Query对象匹配的键值对列表,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示要匹配的键前缀。
callback AsyncCallback<Entry[]> 回调函数。返回本设备与指定Query对象匹配的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.BYTE_ARRAY,
                value: arr
            }
        }
        entries.push(entry);
    }
    console.log(`entries: {entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        console.log('Succeeded in putting Batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query, function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting Entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        });
    });
} catch (e) {
    console.error(`Fail to get Entries.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取本设备与指定Query对象匹配的键值对列表,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。

返回值:

类型 说明
Promise<Entry[]> Promise对象。返回本设备与指定Query对象匹配的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.BYTE_ARRAY,
                value: arr
            }
        }
        entries.push(entry);
    }
    console.log(`entries: {entries}`);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting Batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getEntries(query).then((entries) => {
            console.log('Succeeded in getting Entries');
        }).catch((err) => {
            console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to get Entries.code is ${err.code},message is ${err.message}`)
    });
    console.log('Succeeded in getting Entries');
} catch (e) {
    console.error(`Fail to get Entries.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取与指定设备ID和Query对象匹配的键值对列表,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 键值对所属的设备ID。
query Query 表示查询对象。
callback AsyncCallback<Entry[]> 回调函数。返回与指定设备ID和Query对象匹配的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.BYTE_ARRAY,
                value: arr
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        var query = new distributedKVStore.Query();
        query.deviceId('localDeviceId');
        query.prefixKey("batch_test");
        kvStore.getEntries('localDeviceId', query, function (err, entries) {
            if (err != undefined) {
                console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting entries');
            console.log(`entries.length: ${entries.length}`);
            console.log(`entries[0]: ${entries[0]}`);
        })
    });
    console.log('Succeeded in getting entries');
} catch (e) {
    console.error(`Fail to get entries.code is ${e.code},message is ${e.message}`);
}

getEntries

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

获取与指定设备ID和Query对象匹配的键值对列表,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 键值对所属的设备ID。
query Query 表示查询对象。

返回值:

类型 说明
Promise<Entry[]> Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.BYTE_ARRAY,
                value: arr
            }
        }
        entries.push(entry);
    }
    console.log(`entries: ${entries}`);
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
        var query = new distributedKVStore.Query();
        query.deviceId('localDeviceId');
        query.prefixKey("batch_test");
        kvStore.getEntries('localDeviceId', query).then((entries) => {
            console.log('Succeeded in getting entries');
        }).catch((err) => {
            console.error(`Fail to get entries.code is ${err.code},message is ${err.message}`);
        });
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    console.log('Succeeded in getting entries');
} catch (e) {
    console.error(`Fail to get entries.code is ${e.code},message is ${e.message}`);
}

getResultSet

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

从DeviceKVStore数据库中获取本设备具有指定前缀的结果集,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。
callback AsyncCallback<KVStoreResultSet> 回调函数。返回具有指定前缀的结果集。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        kvStore.getResultSet('batch_test_string_key', async function (err, result) {
            if (err != undefined) {
                console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting result set');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                if (err != undefined) {
                    console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
                    return;
                }
                console.log('Succeeded in closing result set');
            })
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.message}`);
}

getResultSet

getResultSet(keyPrefix: string): Promise<KVStoreResultSet>

从DeviceKVStore数据库中获取本设备具有指定前缀的结果集,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
keyPrefix string 表示要匹配的键前缀。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。返回具有指定前缀的结果集。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    kvStore.getResultSet('batch_test_string_key').then((result) => {
        console.log('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing result set');
    }).catch((err) => {
        console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSet

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

获取与指定设备ID和key前缀匹配的KVStoreResultSet对象,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
keyPrefix string 表示要匹配的键前缀。
callback AsyncCallback<KVStoreResultSet> 回调函数。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async function (err, result) {
        if (err != undefined) {
            console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting resultSet');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in closing resultSet');
        })
    });
} catch (e) {
    console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`);
}

getResultSet

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

获取与指定设备ID和key前缀匹配的KVStoreResultSet对象,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
keyPrefix string 表示要匹配的键前缀。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

let kvStore;
try {
    let resultSet;
    kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result) => {
        console.log('Succeeded in getting resultSet');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing resultSet');
    }).catch((err) => {
        console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`);
}

getResultSet

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

获取与指定设备ID和Query对象匹配的KVStoreResultSet对象,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string KVStoreResultSet对象所属的设备ID。
query Query 表示查询对象。
callback AsyncCallback<KVStoreResultSet> 回调函数。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSet('localDeviceId', query, async function (err, result) {
            if (err != undefined) {
                console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting resultSet');
            resultSet = result;
            kvStore.closeResultSet(resultSet, function (err, data) {
                if (err != undefined) {
                    console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`);
                    return;
                }
                console.log('Succeeded in closing resultSet');
            })
        });
    });
} catch (e) {
    console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`);
}

getResultSet

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

获取与指定设备ID和Query对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string KVStoreResultSet对象所属的设备ID。
query Query 表示查询对象。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    const query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet('localDeviceId', query).then((result) => {
        console.log('Succeeded in getting resultSet');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
    });
    query.deviceId('localDeviceId');
    console.log("GetResultSet " + query.getSqlLike());
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing resultSet');
    }).catch((err) => {
        console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`);
    });

} catch (e) {
    console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`);
}

getResultSet

getResultSet(query: Query): Promise<KVStoreResultSet>

获取与本设备指定Query对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。获取与本设备指定Query对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    const query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet(query).then((result) => {
        console.log('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}    

getResultSet

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

获取与指定设备ID和Query对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string KVStoreResultSet对象所属的设备ID。
query Query 表示查询对象。

返回值:

类型 说明
Promise<KVStoreResultSet> Promise对象。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    const query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSet('localDeviceId', query).then((result) => {
        console.log('Succeeded in getting resultSet');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultSet.code is ${err.code},message is ${err.message}`);
    });
    query.deviceId('localDeviceId');
    console.log("GetResultSet " + query.getSqlLike());
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing resultSet');
    }).catch((err) => {
        console.error(`Fail to close resultSet.code is ${err.code},message is ${err.message}`);
    });

} catch (e) {
    console.error(`Fail to get resultSet.code is ${e.code},message is ${e.message}`);
}

getResultSet

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

获取与本设备指定Predicate对象匹配的KVStoreResultSet对象,使用callback异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。
callback AsyncCallback<KVStoreResultSet> 回调函数,获取与指定Predicates对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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) {
        if (err != undefined) {
            console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting result set');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in closing result set');
        })
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSet

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

获取与本设备指定Predicate对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。

返回值:

类型 说明
Promise<KVStoreResultSet> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing result set');
    }).catch((err) => {
        console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSet

getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void

获取与指定Predicate对象匹配的KVStoreResultSet对象,使用callback异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。
callback AsyncCallback<KVStoreResultSet> 回调函数,获取与指定Predicates对象匹配的KVStoreResultSet对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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

let kvStore;
try {
    let resultSet;
    let predicates = new dataSharePredicates.DataSharePredicates();
    predicates.prefixKey("batch_test_string_key");
    kvStore.getResultSet('localDeviceId', predicates, async function (err, result) {
        if (err != undefined) {
            console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in getting result set');
        resultSet = result;
        kvStore.closeResultSet(resultSet, function (err, data) {
            if (err != undefined) {
                console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in closing result set');
        })
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSet

getResultSet(deviceId: string, predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet>

获取与指定Predicate对象匹配的KVStoreResultSet对象,使用Promise异步回调。

系统接口: 此接口为系统接口。

系统能力: SystemCapability.DistributedDataManager.DataShare.Provider

参数:

参数名 类型 必填 说明
deviceId string 标识要查询其数据的设备。
predicates dataSharePredicates.DataSharePredicates 指示筛选条件,当此参数为null时,应定义处理逻辑。

返回值:

类型 说明
Promise<KVStoreResultSet> 无返回结果的Promise对象。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

import dataSharePredicates from '@ohos.data.dataSharePredicates';
let kvStore;
try {
    let resultSet;
    let predicates = new dataSharePredicates.DataSharePredicates();
    predicates.prefixKey("batch_test_string_key");
    kvStore.getResultSet('localDeviceId', predicates).then((result) => {
        console.log('Succeeded in getting result set');
        resultSet = result;
    }).catch((err) => {
        console.error(`Fail to get resultset.code is ${err.code},message is ${err.message}`);
    });
    kvStore.closeResultSet(resultSet).then((err) => {
        console.log('Succeeded in closing result set');
    }).catch((err) => {
        console.error(`Fail to close resultset.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSize

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

获取与本设备指定Query对象匹配的结果数,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。
callback AsyncCallback<number> 回调函数。返回与本设备指定Query对象匹配的结果数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        console.log('Succeeded in putting batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSize(query, async function (err, resultSize) {
            if (err != undefined) {
                console.error(`Fail to get result size.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting result set size');
        });
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSize

getResultSize(query: Query): Promise<number>

获取与本设备指定Query对象匹配的结果数,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.Core

参数:

参数名 类型 必填 说明
query Query 表示查询对象。

返回值:

类型 说明
Promise<number> Promise对象。获取与本设备指定Query对象匹配的结果数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    const query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSize(query).then((resultSize) => {
        console.log('Succeeded in getting result set size');
    }).catch((err) => {
        console.error(`Fail to get result size.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`An unexpected error occurred.code is ${e.code},message is ${e.code}`);
}

getResultSize

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

获取与指定设备ID和Query对象匹配的结果数,使用callback异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string KVStoreResultSet对象所属的设备ID。
query Query 表示查询对象。
callback AsyncCallback<number> 回调函数。返回与指定设备ID和Query对象匹配的结果数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries, async function (err, data) {
        if (err != undefined) {
            console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
            return;
        }
        console.log('Succeeded in putting batch');
        const query = new distributedKVStore.Query();
        query.prefixKey("batch_test");
        kvStore.getResultSize('localDeviceId', query, async function (err, resultSize) {
            if (err != undefined) {
                console.error(`Fail to get resultSize.code is ${err.code},message is ${err.message}`);
                return;
            }
            console.log('Succeeded in getting resultSize');
            ;
        });
    });
} catch (e) {
    console.error(`Fail to get resultSize.code is ${e.code},message is ${e.message}`);
}

getResultSize

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

获取与指定设备ID和Query对象匹配的结果数,使用Promise异步回调。

系统能力: SystemCapability.DistributedDataManager.KVStore.DistributedKVStore

参数:

参数名 类型 必填 说明
deviceId string KVStoreResultSet对象所属的设备ID。
query Query 表示查询对象。

返回值:

类型 说明
Promise<number> Promise对象。返回与指定设备ID和Query对象匹配的结果数。

错误码:

以下错误码的详细介绍请参见分布式键值数据库错误码

错误码ID 错误信息
15100003 Database corrupted.
15100005 Database or result set already closed.

示例:

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: distributedKVStore.ValueType.STRING,
                value: 'batch_test_string_value'
            }
        }
        entries.push(entry);
    }
    kvStore.putBatch(entries).then(async (err) => {
        console.log('Succeeded in putting batch');
    }).catch((err) => {
        console.error(`Fail to put batch.code is ${err.code},message is ${err.message}`);
    });
    var query = new distributedKVStore.Query();
    query.prefixKey("batch_test");
    kvStore.getResultSize('localDeviceId', query).then((resultSize) => {
        console.log('Succeeded in getting resultSize');
        ;
    }).catch((err) => {
        console.error(`Fail to get resultSize.code is ${err.code},message is ${err.message}`);
    });
} catch (e) {
    console.error(`Fail to get resultSize.code is ${e.code},message is ${e.message}`);
}