# 分布式键值数据库分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口，应用程序可将数据保存到分布式键值数据库中，并可对分布式键值数据库中的数据进行增加、删除、修改、查询、同步等操作。该模块提供以下分布式键值数据库相关的常用功能： - [KVManager](#kvmanager)：分布式键值数据库管理实例，用于获取数据库的相关信息。 - [KVStoreResultSet](#kvstoreresultset)：提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。 - [Query](#query)：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。 - [SingleKVStore](#singlekvstore)：单版本分布式键值数据库，不对数据所属设备进行区分，提供查询数据和同步数据的方法。 - [DeviceKVStore](#devicekvstore)：设备协同数据库，继承自[SingleKVStore](#kvstore)，以设备维度对数据进行区分，提供查询数据和同步数据的方法。 > **说明：** > > 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 ## 导入模块 ```js import distributedKVStore from '@ohos.data.distributedKVStore'; ``` ## KVManagerConfig 提供KVManager实例的配置信息，包括调用方的包名和应用的上下文。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ---------- | --------------------- | ---- | ---- | ------------------------------------------------------------ | | context | Context | 是 | 是 |应用的上下文。
FA模型的应用Context定义见[Context](js-apis-Context.md)。
Stage模型的应用Context定义见[Context](js-apis-ability-context.md)。 | | 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](#valuetype) | 是 | 是 |值类型。 | | value | Uint8Array \| string \| number \| boolean| 是 | 是 |值。 | ## Entry 存储在数据库中的键值对。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ----- | --------------- | ---- | ---- | -------- | | key | string | 是 | 是 | 键值。 | | value | [Value](#value) | 是 | 是 | 值对象。 | ## ChangeNotification 数据变更时通知的对象，包括数据插入的数据、更新的数据、删除的数据和设备ID。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 名称 | 类型 | 可读 | 可写 | 说明 | | ------------- | ----------------- | ---- | ---- | ------------------------ | | insertEntries | [Entry](#entry)[] | 是 | 是 | 数据添加记录。 | | updateEntries | [Entry](#entry)[] | 是 | 是 | 数据更新记录。 | | deleteEntries | [Entry](#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 | 表示单版本数据库。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | ## SecurityLevel 数据库的安全级别枚举。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 名称 | 说明 | | -------: | ------------------------------------------------------------ | | S1 | 表示数据库的安全级别为低级别，当数据泄露时会产生较低影响。例如，包含壁纸等系统数据的数据库。 | | S2 | 表示数据库的安全级别为中级别，当数据泄露时会产生较大影响。例如，包含录音、视频等用户生成数据或通话记录等信息的数据库。 | | S3 | 表示数据库的安全级别为高级别，当数据泄露时会产生重大影响。例如，包含用户运动、健康、位置等信息的数据库。 | | S4 | 表示数据库的安全级别为关键级别，当数据泄露时会产生严重影响。例如，包含认证凭据、财务数据等信息的数据库。 | ## Options 用于提供创建数据库的配置信息。 | 名称 | 类型 | 可读 | 可写 | 说明 | | --------------- | ------------------------------- | ---- | ---- | ------------------------------------------------------------ | | createIfMissing | boolean | 是 | 是 | 当数据库文件不存在时是否创建数据库，默认创建。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | | encrypt | boolean | 是 | 是 | 设置数据库文件是否加密，默认不加密。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | | backup | boolean | 是 | 是 | 设置数据库文件是否备份，默认备份。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | | autoSync | boolean | 是 | 是 | 设置数据库文件是否自动同步，默认不自动同步。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core
**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC | | kvStoreType | [KVStoreType](#kvstoretype) | 是 | 是 | 设置要创建的数据库类型，默认为多设备协同数据库。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | | securityLevel | [SecurityLevel](#securitylevel) | 是 | 是 |设置数据库安全级别。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | | schema | [Schema](#schema) | 是 | 是 | 设置定义存储在数据库中的值，默认不使用Schema。
**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | ## Schema 表示数据库模式，可以在创建或打开数据库时创建Schema对象并将它们放入[Options](#options)中。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 名称 | 类型 | 可读 | 可写 | 说明 | | ------- | ----------------------- | ---- | ---- | -------------------------- | | root | [FieldNode](#fieldnode) | 是 | 是 | 表示json根对象。 | | indexes | Array\ | 是 | 是 | 表示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](#fieldnode) | 是 | 要附加的域节点。 | **返回值：** | 类型 | 说明 | | ------- | ------------------------------------------------------------ | | boolean | 返回true表示子节点成功添加到FieldNode；返回false则表示操作失败。 | **示例：** ```js 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, callback: AsyncCallback<KVManager>): void 创建一个KVManager对象实例，用于管理数据库对象，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------------- | ---- | ----------------------------------------------------------- | | config | [KVManagerConfig](#kvmanagerconfig) | 是 | 提供KVManager实例的配置信息，包括调用方的包名和应用上下文。 | | callback | AsyncCallback<[KVManager](#kvmanager)> | 是 | 回调函数。返回创建的KVManager对象实例。 | **示例：** Stage模型下的示例： ```js import AbilityStage from '@ohos.application.Ability' let kvManager; export default class MyAbilityStage extends AbilityStage { onCreate() { console.log("MyAbilityStage onCreate") let context = this.context const kvManagerConfig = { context: context, bundleName: 'com.example.datamanagertest', } try { distributedKVStore.createKVManager(kvManagerConfig, function (err, manager) { if (err) { console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); return; } console.log("Succeeded in creating KVManager"); kvManager = manager; }); } catch (e) { console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); } } } ``` FA模型下的示例： ```js import featureAbility from '@ohos.ability.featureAbility' let kvManager; let context = featureAbility.getContext() const kvManagerConfig = { context: context, bundleName: 'com.example.datamanagertest', } try { distributedKVStore.createKVManager(kvManagerConfig, function (err, manager) { if (err) { console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); return; } console.log("Succeeded in creating KVManager"); kvManager = manager; }); } catch (e) { console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); } ``` ## distributedKVStore.createKVManager createKVManager(config: KVManagerConfig): Promise<KVManager> 创建一个KVManager对象实例，用于管理数据库对象，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | ----------------------------- | ---- | --------------------------------------------------------- | | config | [KVManagerConfig](#kvmanager) | 是 | 提供KVManager实例的配置信息，包括调用方的包名和用户信息。 | **返回值：** | 类型 | 说明 | | -------------------------------------- | ------------------------------------------ | | Promise<[KVManager](#kvmanager)> | Promise对象。返回创建的KVManager对象实例。 | **示例：** Stage模型下的示例： ```js import AbilityStage from '@ohos.application.Ability' let kvManager; export default class MyAbilityStage extends AbilityStage { onCreate() { console.log("MyAbilityStage onCreate") let context = this.context const kvManagerConfig = { context: context, bundleName: 'com.example.datamanagertest', } try { distributedKVStore.createKVManager(kvManagerConfig).then((manager) => { console.log("Succeeded in creating KVManager"); kvManager = manager; }).catch((err) => { console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); }); } catch (e) { console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); } } } ``` FA模型下的示例： ```js import featureAbility from '@ohos.ability.featureAbility' let kvManager; let context = featureAbility.getContext() const kvManagerConfig = { context: context, bundleName: 'com.example.datamanagertest', } try { distributedKVStore.createKVManager(kvManagerConfig).then((manager) => { console.log("Succeeded in creating KVManager"); kvManager = manager; }).catch((err) => { console.error(`Failed to create KVManager.code is ${err.code},message is ${err.message}`); }); } catch (e) { console.error(`Failed to create KVManager.code is ${e.code},message is ${e.message}`); } ``` ## KVManager 分布式键值数据库管理实例，用于获取分布式键值数据库的相关信息。在调用KVManager的方法前，需要先通过[createKVManager](#distributedkvstorecreatekvmanager)构建一个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](#constants)。 | | options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | | callback | AsyncCallback<T> | 是 | 回调函数。返回创建的分布式键值数据库实例（根据kvStoreType的不同，可以创建SingleKVStore实例和DeviceKVStore实例）。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | ------------------------------------------- | | 15100002 | Open existed database with changed options. | | 15100003 | Database corrupted. | **示例：** ```js 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](#constants)。 | | options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | **返回值：** | 类型 | 说明 | | ---------------- | ------------------------------------------------------------ | | Promise<T> | Promise对象。返回创建的分布式键值数据库实例（根据kvStoreType的不同，可以创建SingleKVStore实例和DeviceKVStore实例。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | ------------------------------------------- | | 15100002 | Open existed database with changed options. | | 15100003 | Database corrupted. | **示例：** ```js 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](#constants)。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **示例：** ```js let kvStore; let kvManager; const options = { createIfMissing: true, encrypt: false, backup: false, autoSync: true, kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, schema: '', 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](#constants)。 | **返回值：** | 类型 | 说明 | | -------------- | ------------------------- | | Promise\ | 无返回结果的Promise对象。 | **示例：** ```js let kvManager; let kvStore; const options = { createIfMissing: true, encrypt: false, backup: false, autoSync: true, kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, schema: '', 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](#constants)。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | ------------ | | 15100004 | Not found. | **示例：** ```js let kvManager; let kvStore; const options = { createIfMissing: true, encrypt: false, backup: false, autoSync: true, kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, schema: '', 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](#constants)。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | ------------ | | 15100004 | Not found. | **示例：** ```js let kvManager; let kvStore; const options = { createIfMissing: true, encrypt: false, backup: false, autoSync: true, kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, schema: '', 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](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------- | ---- | --------------------------------------------------- | | appId | string | 是 | 所调用数据库方的包名。 | | callback | AsyncCallback<string[]> | 是 | 回调函数。返回所有创建的分布式键值数据库的storeId。 | **示例：** ```js 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](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------- | ---- | ---------------------- | | appId | string | 是 | 所调用数据库方的包名。 | **返回值：** | 类型 | 说明 | | ----------------------- | ------------------------------------------------------ | | Promise<string[]> | Promise对象。返回所有创建的分布式键值数据库的storeId。 | **示例：** ```js 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> | 是 | 回调函数。 | **示例：** ```js 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> | 否 | 回调函数。 | **示例：** ```js 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](#getkvstore)构建一个KvStore(SingleKVStore或者DeviceKVStore)实例。 ### getCount getCount(): number 获取结果集中的总行数。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **返回值：** | 类型 | 说明 | | ------ | ------------------ | | number | 返回数据的总行数。 | **示例：** ```js 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 | 返回当前读取位置。 | **示例：** ```js 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则表示操作失败。 | **示例：** ```js 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则表示操作失败。 | **示例：** ```js 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则表示操作失败。 | **示例：** ```js 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则表示操作失败。 | **示例：** ```js 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则表示操作失败。 | **示例：** ```js 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则表示操作失败。 | **示例** ```js 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表示读取位置不是第一行。 | **示例：** ```js 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表示读取位置不是最后一行。 | **示例：** ```js 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表示读取位置不在第一行之前。 | **示例：** ```js 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表示读取位置不在最后一行之后。 | **示例：** ```js 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](#entry) | 返回键值对。 | **示例：** ```js 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) | 返回重置的Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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](query) | 返回查询对象。 | **示例：** ```js 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](query) | 返回查询对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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) | 返回Query对象。 | **示例：** ```js 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 | 返回一个字段列中包含对应子串的结果。 | **示例：** ```js 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](#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](#constants)。 | | value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | | callback | AsyncCallback<void> | 是 |回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | | value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#entry)[] | 是 | 表示要批量插入的键值对。 | | callback | Asyncallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#entry)[] | 是 | 表示要批量插入的键值对。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](js-apis-data-ValuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | | callback | Asyncallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](js-apis-data-ValuesBucket.md#valuesbucket)> | 是 | 表示要插入的数据。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 五返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`) } ``` ### removeDeviceData removeDeviceData(deviceId: string): Promise<void> 删除指定设备的数据，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | ---- | ---------------------- | | deviceId | string | 是 | 表示要删除设备的名称。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`) } ``` ### get get(key: string, callback: AsyncCallback): void 获取指定键的值，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ----- | ------ | ---- | ----------------------- | | key |string | 是 |要查询数据的key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | | callback |AsyncCallback<boolean \| string \| number \| Uint8Array>) | 是 |回调函数。返回获取查询的值。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | **返回值：** | 类型 | 说明 | | ------ | ------- | |Promise<Uint8Array \| string \| boolean \| number> |Promise对象。返回获取查询的值。| **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#entry)[]> | 是 | 回调函数。返回匹配指定前缀的键值对列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#entry)[]> | Promise对象。返回匹配指定前缀的键值对列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](query) | 是 | 表示要匹配的键前缀。 | | callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定Query对象匹配的键值对列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](query) | 是 | 表示查询对象。 | **返回值：** | 类型 | 说明 | | -------------------------------- | -------------------------------------------------- | | Promise<[Entry](#entry)[]> | Promise对象。返回与指定Query对象匹配的键值对列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#kvstoreresultset)> | 是 | 回调函数。返回具有指定前缀的结果集。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### getResultSet getResultSet(keyPrefix: string): Promise<KVStoreResultSet> 从SingleKVStore数据库中获取具有指定前缀的结果集，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | -------- | ---- | -------------------- | | keyPrefix | string | 是 | 表示要匹配的键前缀。 | **返回值：** | 类型 | 说明 | | ---------------------------------------------------- | --------------------------------------- | | Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回具有指定前缀的结果集。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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](#kvstoreresultset)> | 是 | 回调函数，获取与指定Query对象匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### getResultSet getResultSet(query: Query): Promise<KVStoreResultSet> 获取与指定Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------- | ---- | -------------- | | query | [Query](query) | 是 | 表示查询对象。 | **返回值：** | 类型 | 说明 | | ---------------------------------------------------- | ------------------------------------------------------------ | | Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。获取与指定Query对象匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | | callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.code}`); } ``` ### getResultSet getResultSet(predicates: dataSharePredicates.DataSharePredicates): Promise<KVStoreResultSet> 获取与指定Predicate对象匹配的KVStoreResultSet对象，使用Promise异步回调。 **系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------------------------------------------------------------ | ---- | ----------------------------------------------- | | predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | **返回值：** | 类型 | 说明 | | ---------------------------------------------------- | ------------------------- | | Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.code}`); } ``` ### closeResultSet closeResultSet(resultSet: KVStoreResultSet, callback: AsyncCallback<void>): void 关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------------- | ---- | ---------------------------------- | | resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | | callback | AsyncCallback<void> | 是 | 回调函数。 | **示例：** ```js 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 occured.code is ${e.code},message is ${e.code}`); } ``` ### closeResultSet closeResultSet(resultSet: KVStoreResultSet): Promise<void> 关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------------- | ---- | ---------------------------------- | | resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** ```js 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 occured.code is ${e.code},message is ${e.code}`); } ``` ### getResultSize getResultSize(query: Query, callback: AsyncCallback<number>): void 获取与指定Query对象匹配的结果数，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------------- | ---- | ------------------------------------------- | | query | [Query](query) | 是 | 表示查询对象。 | | callback | AsyncCallback<number> | 是 | 回调函数。返回与指定Query对象匹配的结果数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.code}`); } ``` ### getResultSize getResultSize(query: Query): Promise<number> 获取与指定Query对象匹配的结果数，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | ------ | -------------- | ---- | -------------- | | query | [Query](query) | 是 | 表示查询对象。 | **返回值：** | 类型 | 说明 | | --------------------- | ----------------------------------------------- | | Promise<number> | Promise对象。获取与指定QuerV9对象匹配的结果数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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](#constants)。 | | callback | AsyncCallback<void> | 是 | 回调函数。当以指定名称备份数据库成功，err为undefined，否则为错误对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | | callback | AsyncCallback<void> | 是 | 回调函数。当从指定的数据库文件恢复数据库成功，err为undefined，否则为错误对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#constants)。 | | callback | AsyncCallback<Array<[string, number]>> | 是 | 回调函数，返回删除备份的文件名及其处理结果。 | **示例：** ```js 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](#constants)。 | **返回值：** | 类型 | 说明 | | -------------------------------------------- | ----------------------------------------------- | | Promise<Array<[string, number]>> | Promise对象，返回删除备份的文件名及其处理结果。 | **示例：** ```js 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> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### commit commit(): Promise<void> 提交SingleKVStore数据库中的事务，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.ode is ${e.code},message is ${e.message}`); } ``` ### rollback rollback(callback: AsyncCallback<void>): void 在SingleKVStore数据库中回滚事务，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | ------------------------- | ---- | ---------- | | callback | AsyncCallback<void> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### rollback rollback(): Promise<void> 在SingleKVStore数据库中回滚事务，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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> | 是 | 回调函数。 | **示例：** ```js 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 occured.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对象。 | **示例：** ```js 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 occured.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> | 是 | 回调函数。 | **示例：** ```js 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 occured.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对象。 | **示例：** ```js 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 occured.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> | 是 | 回调函数。 | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### setSyncParam setSyncParam(defaultAllowedDelayMs: number): Promise<void> 设置数据库同步允许的默认延迟，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------------------- | -------- | ---- | -------------------------------------------- | | defaultAllowedDelayMs | number | 是 | 表示数据库同步允许的默认延迟，以毫秒为单位。 | **返回值：** | 类型 | 说明 | | ------------------- | ------------------------- | | Promise<void> | 无返回结果的Promise对象。 | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### sync sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void 在手动同步方式下，触发数据库同步。关于分布式数据服务的同步方式说明，请见[分布式数据服务概述](../../database/database-mdds-overview.md)。 **需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------- | ---- | ---------------------------------------------- | | deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的deviceId列表。 | | mode | [SyncMode](#syncmode) | 是 | 同步模式。 | | delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒）。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | ------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | **示例：** ```js let kvStore; try { kvStore.sync('deviceIds', distributedKVStore.SyncMode.PULL_ONLY, 1000); } catch (err) { console.error(`Fail to syn.code is ${err.code},message is ${err.message}`); } ``` ### sync sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void 在手动同步方式下，触发数据库同步，此方法为同步方法。关于分布式数据服务的同步方式说明，请见[分布式数据服务概述](../../database/database-mdds-overview.md)。 **需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | --------------------- | ---- | ---------------------------------------------- | | deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的deviceId列表。 | | mode | [SyncMode](#syncmode) | 是 | 同步模式。 | | query | [Query](query) | 是 | 表示数据库的查询谓词条件 | | delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒）。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | ------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | **示例：** ```js let kvStore; const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; try { kvStore.on('syncComplete', function (data) { console.log('Sync dataChange'); }); kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, function (err, data) { if (err != undefined) { console.error(`Fail to sync.code is ${err.code},message is ${err.message}`); return; } console.log('Succeeded in putting data'); const devices = ['deviceList']; const mode = distributedKVStore.SyncMode.PULL_ONLY; const query = new distributedKVStore.Query(); query.prefixKey("batch_test"); query.deviceId('localDeviceId'); kvStore.sync(devices, 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](#subscribetype) | 是 | 表示订阅的类型。 | | listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100001 | Over max subscribe limits. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | **示例：** ```js 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](#changenotification)> | 否 | 回调函数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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]>> | 否 | 回调函数。用于向调用方发送同步结果的回调。 | **示例：** ```js 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](#securitylevel)> | 是 | 回调函数。返回数据库的安全级别。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ### getSecurityLevel getSecurityLevel(): Promise<SecurityLevel> 获取数据库的安全级别，使用Promise异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.Core **返回值：** | 类型 | 说明 | | ---------------------------------------------- | ----------------------------------- | | Promise<[SecurityLevel](#securitylevel)> | Promise对象。返回数据库的安全级别。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.code is ${e.code},message is ${e.message}`); } ``` ## DeviceKVStore 设备协同数据库，继承自SingleKVStore，提供查询数据和同步数据的方法。设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。在调用DeviceKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个DeviceKVStore实例。 ### 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> | 是 |回调函数，返回匹配给定条件的字符串值。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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对象。返回匹配给定条件的字符串值。| **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100004 | Not found. | | 15100006 | Database or result set already closed. | **示例：** ```js 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(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void 获取与指定设备ID和key前缀匹配的所有键值对，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | -------------------------------------- | ---- | ---------------------------------------------- | | deviceId | string | 是 | 标识要查询其数据的设备。 | | keyPrefix | string | 是 | 表示要匹配的键前缀。 | | callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数，返回满足给定条件的所有键值对的列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#entry)[]> | Promise对象。返回匹配给定条件的所有键值对的列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void 获取与指定设备ID和Query对象匹配的键值对列表，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore **参数：** | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------------------------- | ---- | ------------------------------------------------------- | | deviceId | string | 是 | 键值对所属的设备ID。 | | query | [Query](query) | 是 | 表示查询对象。 | | callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的键值对列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](query) | 是 | 表示查询对象。 | **返回值：** | 类型 | 说明 | | -------------------------------- | ---------------------------------------------------------- | | Promise<[Entry](#entry)[]> | Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100005 | Not support the operation. | | 15100006 | Database or result set already closed. | **示例：** ```js 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(deviceId: string, keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 获取与指定设备ID和key前缀匹配的KVStoreResultSet对象，使用callback异步回调。 **系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore **参数：** | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | deviceId | string | 是 | 标识要查询其数据的设备。 | | keyPrefix | string | 是 | 表示要匹配的键前缀。 | | callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)[]> | 是 | 回调函数。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](#kvstoreresultset)[]> | Promise对象。返回与指定设备ID和key前缀匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](query) | 是 | 表示查询对象。 | | callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)[]> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](query) | 是 | 表示查询对象。 | **返回值：** | 类型 | 说明 | | ------------------------------------------------------ | ------------------------------------------------------------ | | Promise<[KVStoreResultSet](#kvstoreresultset)[]> | Promise对象。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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(deviceId: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<KVStoreResultSet>): void 获取与指定Predicate对象匹配的KVStoreResultSet对象，使用callback异步回调。 **系统接口：** 此接口为系统接口。 **系统能力：** SystemCapability.DistributedDataManager.DataShare.Provider **参数：** | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | | deviceId | string | 是 | 标识要查询其数据的设备。 | | predicates | [DataSharePredicates](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | | callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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](js-apis-data-dataSharePredicates.md#datasharepredicates) | 是 | 指示筛选条件,当此参数为null时，应定义处理逻辑。 | **返回值：** | 类型 | 说明 | | ---------------------------------------------------- | ------------------------- | | Promise<[KVStoreResultSet](#kvstoreresultset)> | 无返回结果的Promise对象。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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 occured.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](query) | 是 | 表示查询对象。 | | callback | AsyncCallback<number> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的结果数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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](query) | 是 | 表示查询对象。 | **返回值：** | 类型 | 说明 | | --------------------- | ------------------------------------------------------ | | Promise<number> | Promise对象。返回与指定设备ID和Query对象匹配的结果数。 | **错误码：** 以下错误码的详细介绍请参见[分布式键值数据库错误码](../errorcodes/errorcode-distributedKVStore.md)。 | **错误码ID** | **错误信息** | | ------------ | -------------------------------------- | | 15100003 | Database corrupted. | | 15100006 | Database or result set already closed. | **示例：** ```js 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}`); } ```