1# @ohos.data.distributedKVStore (分布式键值数据库) 2<!--Kit: ArkData--> 3<!--Subsystem: DistributedDataManager--> 4<!--Owner: @ding_dong_dong--> 5<!--Designer: @dboy190; @houpengtao1--> 6<!--Tester: @logic42--> 7<!--Adviser: @ge-yafang--> 8 9分布式键值数据库为应用程序提供不同设备间数据库的分布式协同能力。通过调用分布式键值数据库各个接口，应用程序可将数据保存到分布式键值数据库中，并可对分布式键值数据库中的数据进行增加、删除、修改、查询、端端同步等操作。 10 11该模块提供以下常用功能： 12 13- [KVManager](#kvmanager)：分布式键值数据库管理实例，用于获取数据库的相关信息。 14- [KVStoreResultSet](#kvstoreresultset)：提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。 15- [Query](#query)：使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。 16- [SingleKVStore](#singlekvstore)：单版本分布式键值数据库，不对数据所属设备进行区分，提供查询数据和端端同步数据的方法。 17- [DeviceKVStore](#devicekvstore)：设备协同数据库，继承自[SingleKVStore](#singlekvstore)，以设备维度对数据进行区分，提供查询数据和端端同步数据的方法。 18 19> **说明：** 20> 21> 本模块首批接口从API version 9开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 22 23## 导入模块 24 25```ts 26import { distributedKVStore } from '@kit.ArkData'; 27``` 28 29## KVManagerConfig 30 31提供KVManager实例的配置信息，包括调用方的包名和应用的上下文。 32 33**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 34 35| 名称 | 类型 | 只读 | 可选 | 说明 | 36| ---------- | ---------------|----- | ---- | ------------------------------------------------------------ | 37| context | BaseContext | 否 | 否 |应用的上下文。 <br>FA模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-app-context.md)。<br>Stage模型的应用Context定义见[Context](../apis-ability-kit/js-apis-inner-application-uiAbilityContext.md)。<br>从API version 10开始，context的参数类型为[BaseContext](../apis-ability-kit/js-apis-inner-application-baseContext.md)。 | 38| bundleName | string | 否 | 否 | 调用方的包名。 | 39 40## Constants 41 42分布式键值数据库常量。 43 44**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 45 46| 名称 | 类型 | 只读 | 可选 | 说明 | 47| --------------------- | ------ | ---- | ---- | ---------------------------------------------------------- | 48| MAX_KEY_LENGTH | number | 是 | 否 | 值为1024，表示数据库中Key允许的最大长度，单位字节。 | 49| MAX_VALUE_LENGTH | number | 是 | 否 | 值为4194303，表示数据库中Value允许的最大长度，单位字节。 | 50| MAX_KEY_LENGTH_DEVICE | number | 是 | 否 | 值为896，表示设备协同数据库中Key允许的最大长度，单位字节。 | 51| MAX_STORE_ID_LENGTH | number | 是 | 否 | 值为128，表示数据库标识符允许的最大长度，单位字节。 | 52| MAX_QUERY_LENGTH | number | 是 | 否 | 值为512000，表示最大查询长度，单位字节。 | 53| MAX_BATCH_SIZE | number | 是 | 否 | 值为128，表示最大批处理操作数量。 | 54 55## ValueType 56 57数据类型枚举。 58 59**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 60 61| 名称 | 值 | 说明 | 62| ---------- | - | -------------------- | 63| STRING | 0 | 表示值类型为字符串。 | 64| INTEGER | 1 | 表示值类型为整数。 | 65| FLOAT | 2 | 表示值类型为浮点数。 | 66| BYTE_ARRAY | 3 | 表示值类型为字节数组。 | 67| BOOLEAN | 4 | 表示值类型为布尔值。 | 68| DOUBLE | 5 | 表示值类型为双浮点数。 | 69 70## Value 71 72存储在数据库中的值对象。 73 74**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 75 76| 名称 | 类型 | 只读 | 可选 | 说明 | 77| ----- | -------|-----|-----|------------------------ | 78| type | [ValueType](#valuetype) | 否 | 否 |值类型。 | 79| value | Uint8Array \| string \| number \| boolean| 否 | 否 |值。 | 80 81## Entry 82 83存储在数据库中的键值对。 84 85**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 86 87| 名称 | 类型 | 只读 | 可选 | 说明 | 88| ----- | ---------- |-- | ---- | -------- | 89| key | string | 否 | 否 | 键值。 | 90| value | [Value](#value) | 否 | 否 | 值对象。 | 91 92## ChangeNotification 93 94数据变更时通知的对象，包括数据插入的数据、更新的数据、删除的数据和设备ID。 95 96**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 97 98| 名称 | 类型 | 只读 | 可选 | 说明 | 99| ------------- | ----------------- |---- | ---- | ------------------------ | 100| insertEntries | [Entry](#entry)[] | 否 | 否 | 数据添加记录。 | 101| updateEntries | [Entry](#entry)[] | 否 | 否 | 数据更新记录。 | 102| deleteEntries | [Entry](#entry)[] | 否 | 否 | 数据删除记录。 | 103| deviceId | string | 否 | 否 | 设备ID，此处为设备UUID。 | 104 105## SyncMode 106 107同步模式枚举。 108 109**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 110 111| 名称 | 值 | 说明 | 112| --------- | - | ---------------------------------------------- | 113| PULL_ONLY | 0 | 表示只能从远端拉取数据到本端。 | 114| PUSH_ONLY | 1 | 表示只能从本端推送数据到远端。 | 115| PUSH_PULL | 2 | 表示从本端推送数据到远端，然后从远端拉取数据到本端。| 116 117## SubscribeType 118 119订阅类型枚举。 120 121**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 122 123| 名称 | 值 | 说明 | 124| --------------------- | - | ---------------------------- | 125| SUBSCRIBE_TYPE_LOCAL | 0 | 表示订阅本地数据变更。 | 126| SUBSCRIBE_TYPE_REMOTE | 1 | 表示订阅远端数据变更。 | 127| SUBSCRIBE_TYPE_ALL | 2 | 表示订阅远端和本地数据变更。 | 128 129## KVStoreType 130 131分布式键值数据库类型枚举。 132 133| 名称 | 值 | 说明 | 134| -------------------- | - | ------------------------------------------------------------ | 135| DEVICE_COLLABORATION | 0 | 表示多设备协同数据库。<br>**数据库特点：** 数据以设备的维度管理，不存在冲突；支持按照设备的维度查询数据。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 136| SINGLE_VERSION | 1 | 表示单版本数据库。<br>**数据库特点：** 数据不分设备，设备之间修改相同的Key会覆盖。 <br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 137 138## SecurityLevel 139 140数据库的安全级别枚举。 141> **说明**： 142> 143> 在单设备使用场景下，KV数据库支持修改securityLevel参数进行安全等级升级。升级操作需要注意以下几点： 144> * 该操作不支持跨设备同步的数据库。不同安全等级的数据库之间不能进行数据同步。若需升级数据库的安全等级，建议重新创建更高安全等级的数据库。 145> * 关闭当前数据库后，修改securityLevel参数以重新设置数据库的安全等级，然后重新打开数据库。 146> * 该操作仅支持升级，例如从S2到S3，不支持降级，例如从S3到S2。 147 148**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 149 150| 名称 | 值 | 说明 | 151| -------: | - | ------------------------------------------------------------ | 152| S1 | 2 | 表示数据库的安全级别为低级别，数据的泄露、篡改、破坏、销毁可能会给个人或组织导致有限的不利影响。<br>例如，性别、国籍，用户申请记录等。 | 153| S2 | 3 | 表示数据库的安全级别为中级别，数据的泄露、篡改、破坏、销毁可能会给个人或组织导致严重的不利影响。<br>例如，个人详细通信地址，姓名昵称等。 | 154| S3 | 5 | 表示数据库的安全级别为高级别，数据的泄露、篡改、破坏、销毁可能会给个人或组织导致严峻的不利影响。<br>例如，个人实时精确定位信息、运动轨迹等。 | 155| S4 | 6 | 表示数据库的安全级别为关键级别，业界法律法规中定义的特殊数据类型，涉及个人的最私密领域的信息或者一旦泄露、篡改、破坏、销毁可能会给个人或组织造成重大的不利影响数据。<br>例如，政治观点、宗教、和哲学信仰、工会成员资格、基因数据、生物信息、健康和性生活状况、性取向等或设备认证鉴权、个人的信用卡等财务信息。 | 156 157## Options 158 159用于提供创建数据库的配置信息。 160 161| 名称 | 类型 | 只读 | 可选 | 说明 | 162| --------------- | -------------- | ---- | ----| -------------------------| 163| createIfMissing | boolean | 否 | 是 | 当数据库文件不存在时是否创建数据库，true为创建，false为不创建，默认为true。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 164| encrypt | boolean | 否 | 是 | 设置数据库文件是否加密，true为加密，false为不加密，默认为false。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 165| backup | boolean | 否 | 是 | 设置数据库文件是否备份，true为备份，false为不备份，默认为true。 <br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 166| autoSync | boolean | 否 | 是 | 设置数据库是否支持跨设备自动同步。默认为false，即只支持手动同步。配置为true，<!--RP1-->即只支持在[跨设备Call调用实现的多端协同](../../application-models/hop-multi-device-collaboration.md#通过跨设备call调用实现多端协同)中生效，其他场景无法生效。<!--RP1End--><br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core<br>**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC | 167| kvStoreType | [KVStoreType](#kvstoretype) | 否 | 是 | 设置要创建的数据库类型，默认为DEVICE_COLLABORATION，即多设备协同数据库。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 168| securityLevel | [SecurityLevel](#securitylevel) | 否 | 否 | 设置数据库安全级别。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core | 169| schema | [Schema](#schema) | 否 | 是 | 设置定义存储在数据库中的值，默认为undefined，即不使用Schema。<br>**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore | 170 171## Schema 172 173表示数据库模式，可以在创建或打开数据库时创建Schema对象并将它们放入[Options](#options)中。 174 175**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 176 177| 名称 | 类型 | 只读 | 可选 | 说明 | 178| ------- | ----------------------- | ---- | ---- | -------------------------- | 179| root | [FieldNode](#fieldnode) | 否 | 否 | 存放了Value中所有字段的定义。 | 180| indexes | Array\<string> | 否 | 否 | 索引字段定义，只有通过此字段指定的FieldNode才会创建索引，格式为：`'$.field1'`, `'$.field2'`。| 181| mode | number | 否 | 否 | Schema的模式，可以取值0或1，0表示COMPATIBLE模式，1表示STRICT模式。| 182| skip | number | 否 | 否 | 支持在检查Value时，跳过skip指定的字节数，且取值范围为[0, 4 * 1024 * 1024 - 2]字节。| 183 184STRICT：STRICT模式要求用户插入的值必须与Schema定义严格匹配，字段数量和格式都不能有差异。如果不匹配，数据库将在插入数据时返回错误。 185 186COMPATIBLE：选择为COMPATIBLE模式时，数据库在检查Value格式时较为宽松，只要Value具有Schema描述的特征即可，允许存在额外字段。例如，定义了id、name字段时，可以插入id、name、age等多个字段。 187 188### constructor 189 190constructor() 191 192用于创建Schema实例的构造函数。 193 194**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 195 196**示例：** 197 198```ts 199 200let child1 = new distributedKVStore.FieldNode('id'); 201child1.type = distributedKVStore.ValueType.INTEGER; 202child1.nullable = false; 203child1.default = '1'; 204let child2 = new distributedKVStore.FieldNode('name'); 205child2.type = distributedKVStore.ValueType.STRING; 206child2.nullable = false; 207child2.default = 'zhangsan'; 208 209let schema = new distributedKVStore.Schema(); 210schema.root.appendChild(child1); 211schema.root.appendChild(child2); 212schema.indexes = ['$.id', '$.name']; 213schema.mode = 1; 214schema.skip = 0; 215``` 216 217## FieldNode 218 219表示 Schema 实例的节点，提供定义存储在数据库中的值的方法。 220 221**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 222 223| 名称 | 类型 | 只读 | 可选 | 说明 | 224| -------- | ------- | ---- | ---- | ------------------------------------------------------------ | 225| nullable | boolean | 否 | 否 | 表示数据库字段是否可以为空。true表示此节点数据可以为空，false表示此节点数据不能为空。 | 226| default | string | 否 | 否 | 表示FieldNode的默认值。 | 227| type | number | 否 | 否 | 表示指定节点对应的数据类型，取值为[ValueType](#valuetype)对应的枚举值。暂不支持BYTE_ARRAY，使用此类型会导致[getKVStore](#getkvstore)失败。 | 228 229### constructor 230 231constructor(name: string) 232 233用于创建带有string字段FieldNode实例的构造函数。 234 235**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 236 237**参数：** 238 239| 参数名 | 类型 | 必填 | 说明 | 240| ------ | -------- | ---- | --------------- | 241| name | string | 是 | FieldNode的值，不能为空，且不大于64个字符。| 242 243**错误码：** 244 245以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 246 247| **错误码ID** | **错误信息** | 248| ------------ | ------------------------------------------- | 249| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 250 251### appendChild 252 253appendChild(child: FieldNode): boolean 254 255在当前 FieldNode 中添加一个子节点。 256 257**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 258 259**参数：** 260 261| 参数名 | 类型 | 必填 | 说明 | 262| ------ | ----------------------- | ---- | ---------------- | 263| child | [FieldNode](#fieldnode) | 是 | 要附加的域节点。 | 264 265**返回值：** 266 267| 类型 | 说明 | 268| ------- | ------------------------------------------------------------ | 269| boolean | 返回true表示子节点成功添加到FieldNode；返回false则表示操作失败。 | 270 271**错误码：** 272 273以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 274 275| **错误码ID** | **错误信息** | 276| ------------ | ------------------------------------------- | 277| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 278 279**示例：** 280 281```ts 282 283try { 284 let node: distributedKVStore.FieldNode | null = new distributedKVStore.FieldNode("root"); 285 let child1: distributedKVStore.FieldNode | null = new distributedKVStore.FieldNode("child1"); 286 let child2: distributedKVStore.FieldNode | null = new distributedKVStore.FieldNode("child2"); 287 let child3: distributedKVStore.FieldNode | null = new distributedKVStore.FieldNode("child3"); 288 node.appendChild(child1); 289 node.appendChild(child2); 290 node.appendChild(child3); 291 console.info("appendNode " + JSON.stringify(node)); 292 child1 = null; 293 child2 = null; 294 child3 = null; 295 node = null; 296} catch (e) { 297 console.error("AppendChild " + e); 298} 299``` 300 301## distributedKVStore.createKVManager 302 303createKVManager(config: KVManagerConfig): KVManager 304 305创建一个KVManager对象实例，用于管理数据库对象。 306 307**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 308 309**参数：** 310 311| 参数名 | 类型 | 必填 | 说明 | 312| ------ | ----------------------------- | ---- | --------------------------------------------------------- | 313| config | [KVManagerConfig](#kvmanagerconfig) | 是 | 提供KVManager实例的配置信息，包括调用方的包名（不能为空）和用户信息。 | 314 315**返回值：** 316 317| 类型 | 说明 | 318| -------------------------------------- | ------------------------------------------ | 319| [KVManager](#kvmanager) | 返回创建的KVManager对象实例。 | 320 321**错误码：** 322 323以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 324 325| **错误码ID** | **错误信息** | 326| ------------ | ------------------------------------------- | 327| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 328 329**示例：** 330 331Stage模型下的示例： 332 333```ts 334import { UIAbility } from '@kit.AbilityKit'; 335import { BusinessError } from '@kit.BasicServicesKit'; 336 337let kvManager: distributedKVStore.KVManager; 338let appId: string = 'com.example.datamanagertest'; 339 340export default class EntryAbility extends UIAbility { 341 onCreate() { 342 console.info("MyAbilityStage onCreate"); 343 let context = this.context; 344 const kvManagerConfig: distributedKVStore.KVManagerConfig = { 345 context: context, 346 bundleName: appId 347 } 348 try { 349 kvManager = distributedKVStore.createKVManager(kvManagerConfig); 350 console.info("Succeeded in creating KVManager"); 351 } catch (e) { 352 let error = e as BusinessError; 353 console.error(`Failed to create KVManager.code is ${error.code},message is ${error.message}`); 354 } 355 if (kvManager !== undefined) { 356 // 进行后续创建数据库等相关操作 357 // ... 358 } 359 } 360} 361``` 362 363FA模型下的示例： 364 365<!--code_no_check_fa--> 366```ts 367import { featureAbility } from '@kit.AbilityKit'; 368import { BusinessError } from '@kit.BasicServicesKit'; 369 370let kvManager: distributedKVStore.KVManager; 371let appId: string = 'com.example.datamanagertest'; 372let context = featureAbility.getContext(); 373const kvManagerConfig: distributedKVStore.KVManagerConfig = { 374 context: context, 375 bundleName: appId 376} 377try { 378 kvManager = distributedKVStore.createKVManager(kvManagerConfig); 379 console.info("Succeeded in creating KVManager"); 380} catch (e) { 381 let error = e as BusinessError; 382 console.error(`Failed to create KVManager.code is ${error.code},message is ${error.message}`); 383} 384if (kvManager !== undefined) { 385 kvManager = kvManager as distributedKVStore.KVManager; 386 // 进行后续创建数据库等相关操作 387 // ... 388} 389``` 390 391## KVManager 392 393分布式键值数据库管理实例，用于获取分布式键值数据库的相关信息。在调用KVManager的方法前，需要先通过[createKVManager](#distributedkvstorecreatekvmanager)构建一个KVManager实例。 394 395### getKVStore 396 397getKVStore<T>(storeId: string, options: Options, callback: AsyncCallback<T>): void 398 399通过指定options和storeId，创建并获取分布式键值数据库，使用callback异步回调。 400 401> 注意： 402> 403> 在获取已有的分布式键值数据库时，如果数据库文件无法打开（例如文件头损坏），将触发自动重建逻辑，并返回新创建的分布式键值数据库实例。建议对重要且无法重新生成的数据使用备份恢复功能，以防止数据丢失。有关备份恢复的使用方法，请参阅[数据库备份与恢复](../../database/data-backup-and-restore.md)。 404 405**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 406 407**参数：** 408 409| 参数名 | 类型 | 必填 | 说明 | 410| -------- | ---------------------- | ---- | ------------------------------------------------------------ | 411| storeId | string | 是 | 数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)，且只能包含字母数字或下划线_。| 412| options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | 413| callback | AsyncCallback<T> | 是 | 回调函数。返回创建的分布式键值数据库实例（根据kvStoreType的不同，可以创建SingleKVStore实例和DeviceKVStore实例）。 | 414 415**错误码：** 416 417以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 418 419| **错误码ID** | **错误信息** | 420| ------------ | ------------------------------------------- | 421| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 422| 15100002 | Open existed database with changed options. | 423| 15100003 | Database corrupted. | 424 425**示例：** 426 427```ts 428import { BusinessError } from '@kit.BasicServicesKit'; 429 430let kvStore: distributedKVStore.SingleKVStore | null = null; 431try { 432 const options: distributedKVStore.Options = { 433 createIfMissing: true, 434 encrypt: false, 435 backup: false, 436 autoSync: false, 437 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 438 securityLevel: distributedKVStore.SecurityLevel.S3 439 }; 440 kvManager.getKVStore('storeId', options, (err: BusinessError, store: distributedKVStore.SingleKVStore) => { 441 if (err) { 442 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 443 return; 444 } 445 console.info("Succeeded in getting KVStore"); 446 kvStore = store; 447 if (kvStore !== null) { 448 // 进行后续相关数据操作，包括数据的增、删、改、查、订阅数据变化等操作 449 // ... 450 } 451 }); 452} catch (e) { 453 let error = e as BusinessError; 454 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 455} 456``` 457 458### getKVStore 459 460getKVStore<T>(storeId: string, options: Options): Promise<T> 461 462指定options和storeId，创建并获取分布式键值数据库，使用Promise回调。 463 464> 注意： 465> 466> 获取已有的分布式键值数据库时，如果数据库文件无法打开（如文件头损坏），将触发自动重建逻辑，并返回新创建的分布式键值数据库实例。建议对重要且无法重新生成的数据使用备份恢复功能，防止数据丢失。备份恢复的使用方法详见[数据库备份与恢复](../../database/data-backup-and-restore.md)。 467 468**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 469 470**参数：** 471 472| 参数名 | 类型 | 必填 | 说明 | 473| ------- | ------------------- | ---- | ------------------------------------------------------------ | 474| storeId | string | 是 | 数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)，且只能包含字母数字或下划线_。| 475| options | [Options](#options) | 是 | 创建分布式键值实例的配置信息。 | 476 477**返回值：** 478 479| 类型 | 说明 | 480| ---------------- | ------------------------------------------------------------ | 481| Promise<T> | Promise对象。返回创建的分布式键值数据库实例（根据kvStoreType的不同，可以创建SingleKVStore实例和DeviceKVStore实例）。 | 482 483**错误码：** 484 485以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 486 487| **错误码ID** | **错误信息** | 488| ------------ | ------------------------------------------- | 489| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.| 490| 15100002 | Open existed database with changed options. | 491| 15100003 | Database corrupted. | 492 493**示例：** 494 495```ts 496import { BusinessError } from '@kit.BasicServicesKit'; 497 498let kvStore: distributedKVStore.SingleKVStore | null = null; 499try { 500 const options: distributedKVStore.Options = { 501 createIfMissing: true, 502 encrypt: false, 503 backup: false, 504 autoSync: false, 505 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 506 securityLevel: distributedKVStore.SecurityLevel.S3 507 }; 508 kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options).then((store: distributedKVStore.SingleKVStore) => { 509 console.info("Succeeded in getting KVStore"); 510 kvStore = store; 511 }).catch((err: BusinessError) => { 512 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 513 }); 514} catch (e) { 515 let error = e as BusinessError; 516 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 517} 518``` 519 520### closeKVStore 521 522closeKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void 523 524通过storeId的值关闭指定的分布式键值数据库，使用callback异步回调。 525 526**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 527 528**参数：** 529 530| 参数名 | 类型 | 必填 | 说明 | 531| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 532| appId | string | 是 | 应用的BundleName，不可为空且长度不大于256。 | 533| storeId | string | 是 | 要关闭的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)，且只能包含字母数字或下划线_。 | 534| callback | AsyncCallback<void> | 是 | 回调函数。当要关闭的数据库成功关闭，err为undefined，否则为错误对象。 | 535 536**错误码：** 537 538以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 539 540| **错误码ID** | **错误信息** | 541| ------------ | ------------------------------------------- | 542| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed.| 543 544**示例：** 545 546```ts 547import { BusinessError } from '@kit.BasicServicesKit'; 548 549let kvStore: distributedKVStore.SingleKVStore | null = null; 550const options: distributedKVStore.Options = { 551 createIfMissing: true, 552 encrypt: false, 553 backup: false, 554 autoSync: false, 555 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 556 schema: undefined, 557 securityLevel: distributedKVStore.SecurityLevel.S3 558} 559try { 560 kvManager.getKVStore('storeId', options, async (err: BusinessError, store: distributedKVStore.SingleKVStore | null) => { 561 if (err != undefined) { 562 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 563 return; 564 } 565 console.info('Succeeded in getting KVStore'); 566 kvStore = store; 567 kvStore = null; 568 store = null; 569 if (kvManager != undefined) { 570 // appId为createKVManager中的appId 571 kvManager.closeKVStore(appId, 'storeId', (err: BusinessError)=> { 572 if (err != undefined) { 573 console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`); 574 return; 575 } 576 console.info('Succeeded in closing KVStore'); 577 }); 578 } 579 }); 580} catch (e) { 581 let error = e as BusinessError; 582 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 583} 584``` 585 586### closeKVStore 587 588closeKVStore(appId: string, storeId: string): Promise<void> 589 590通过storeId的值关闭指定的分布式键值数据库，使用Promise异步回调。 591 592**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 593 594**参数：** 595 596| 参数名 | 类型 | 必填 | 说明 | 597| ------- | -------- | ---- | ------------------------------------------------------------ | 598| appId | string | 是 | 应用的BundleName，不可为空且长度不大于256。 | 599| storeId | string | 是 | 要关闭的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)，且只能包含字母数字或下划线_。 | 600 601**返回值：** 602 603| 类型 | 说明 | 604| -------------- | ------------------------- | 605| Promise\<void> | 无返回结果的Promise对象。 | 606 607**错误码：** 608 609以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 610 611| **错误码ID** | **错误信息** | 612| ------------ | ------------------------------------------- | 613| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed.| 614 615**示例：** 616 617```ts 618import { BusinessError } from '@kit.BasicServicesKit'; 619 620let kvStore: distributedKVStore.SingleKVStore | null = null; 621 622const options: distributedKVStore.Options = { 623 createIfMissing: true, 624 encrypt: false, 625 backup: false, 626 autoSync: false, 627 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 628 schema: undefined, 629 securityLevel: distributedKVStore.SecurityLevel.S3 630} 631try { 632 kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options).then(async (store: distributedKVStore.SingleKVStore | null) => { 633 console.info('Succeeded in getting KVStore'); 634 kvStore = store; 635 kvStore = null; 636 store = null; 637 if (kvManager != undefined) { 638 // appId为createKVManager中的appId 639 kvManager.closeKVStore(appId, 'storeId').then(() => { 640 console.info('Succeeded in closing KVStore'); 641 }).catch((err: BusinessError) => { 642 console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`); 643 }); 644 } 645 }).catch((err: BusinessError) => { 646 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 647 }); 648} catch (e) { 649 let error = e as BusinessError; 650 console.error(`Failed to close KVStore.code is ${error.code},message is ${error.message}`); 651} 652``` 653 654### deleteKVStore 655 656deleteKVStore(appId: string, storeId: string, callback: AsyncCallback<void>): void 657 658通过storeId的值删除指定的分布式键值数据库，使用callback异步回调。 659 660**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 661 662**参数：** 663 664| 参数名 | 类型 | 必填 | 说明 | 665| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 666| appId | string | 是 | 应用的BundleName，不可为空且长度不大于256。 | 667| storeId | string | 是 | 要删除的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)，且只能包含字母数字或下划线_。 | 668| callback | AsyncCallback<void> | 是 | 回调函数。当要删除的数据库成功删除，err为undefined，否则为错误对象。 | 669 670**错误码：** 671 672以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 673 674| **错误码ID** | **错误信息** | 675| ------------ | ------------ | 676| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed.| 677| 15100004 | Not found. | 678 679**示例：** 680 681```ts 682import { BusinessError } from '@kit.BasicServicesKit'; 683 684let kvStore: distributedKVStore.SingleKVStore | null = null; 685 686const options: distributedKVStore.Options = { 687 createIfMissing: true, 688 encrypt: false, 689 backup: false, 690 autoSync: false, 691 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 692 schema: undefined, 693 securityLevel: distributedKVStore.SecurityLevel.S3 694} 695try { 696 kvManager.getKVStore('storeId', options, async (err: BusinessError, store: distributedKVStore.SingleKVStore | null) => { 697 if (err != undefined) { 698 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 699 return; 700 } 701 console.info('Succeeded in getting KVStore'); 702 kvStore = store; 703 kvStore = null; 704 store = null; 705 if (kvManager != undefined) { 706 // appId为createKVManager中的appId 707 kvManager.deleteKVStore(appId, 'storeId', (err: BusinessError) => { 708 if (err != undefined) { 709 console.error(`Failed to delete KVStore.code is ${err.code},message is ${err.message}`); 710 return; 711 } 712 console.info(`Succeeded in deleting KVStore`); 713 }); 714 } 715 }); 716} catch (e) { 717 let error = e as BusinessError; 718 console.error(`Failed to delete KVStore.code is ${error.code},message is ${error.message}`); 719} 720``` 721 722### deleteKVStore 723 724deleteKVStore(appId: string, storeId: string): Promise<void> 725 726通过storeId的值删除指定的分布式键值数据库，使用Promise异步回调。 727 728**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 729 730**参数：** 731 732| 参数名 | 类型 | 必填 | 说明 | 733| ------- | -------- | ---- | ------------------------------------------------------------ | 734| appId | string | 是 | 应用的BundleName，不可为空且长度不大于256。 | 735| storeId | string | 是 | 要删除的数据库唯一标识符，长度不大于[MAX_STORE_ID_LENGTH](#constants)，且只能包含字母数字或下划线_。 | 736 737**返回值：** 738 739| 类型 | 说明 | 740| ------------------- | ------------------------- | 741| Promise<void> | 无返回结果的Promise对象。 | 742 743**错误码：** 744 745以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 746 747| **错误码ID** | **错误信息** | 748| ------------ | ------------ | 749| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed.| 750| 15100004 | Not found. | 751 752**示例：** 753 754```ts 755import { BusinessError } from '@kit.BasicServicesKit'; 756 757let kvStore: distributedKVStore.SingleKVStore | null = null; 758 759const options: distributedKVStore.Options = { 760 createIfMissing: true, 761 encrypt: false, 762 backup: false, 763 autoSync: false, 764 kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, 765 schema: undefined, 766 securityLevel: distributedKVStore.SecurityLevel.S3 767} 768try { 769 kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options).then(async (store: distributedKVStore.SingleKVStore | null) => { 770 console.info('Succeeded in getting KVStore'); 771 kvStore = store; 772 kvStore = null; 773 store = null; 774 if (kvManager != undefined) { 775 // appId为createKVManager中的appId 776 kvManager.deleteKVStore(appId, 'storeId').then(() => { 777 console.info('Succeeded in deleting KVStore'); 778 }).catch((err: BusinessError) => { 779 console.error(`Failed to delete KVStore.code is ${err.code},message is ${err.message}`); 780 }); 781 } 782 }).catch((err: BusinessError) => { 783 console.error(`Failed to get KVStore.code is ${err.code},message is ${err.message}`); 784 }); 785} catch (e) { 786 let error = e as BusinessError; 787 console.error(`Failed to delete KVStore.code is ${error.code},message is ${error.message}`); 788} 789``` 790 791### getAllKVStoreId 792 793getAllKVStoreId(appId: string, callback: AsyncCallback<string[]>): void 794 795获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId，使用callback异步回调。 796 797**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 798 799**参数：** 800 801| 参数名 | 类型 | 必填 | 说明 | 802| -------- | ----------------------------- | ---- | --------------------------------------------------- | 803| appId | string | 是 | 应用的BundleName，不可为空且长度不大于256。 | 804| callback | AsyncCallback<string[]> | 是 | 回调函数。返回所有创建的分布式键值数据库的storeId。 | 805 806**错误码：** 807 808以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 809 810| **错误码ID** | **错误信息** | 811| ------------ | ------------ | 812| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed.| 813 814**示例：** 815 816```ts 817import { BusinessError } from '@kit.BasicServicesKit'; 818 819try { 820 // appId为createKVManager中的appId 821 kvManager.getAllKVStoreId(appId, (err: BusinessError, data: string[]) => { 822 if (err != undefined) { 823 console.error(`Failed to get AllKVStoreId.code is ${err.code},message is ${err.message}`); 824 return; 825 } 826 console.info('Succeeded in getting AllKVStoreId'); 827 console.info(`GetAllKVStoreId size = ${data.length}`); 828 }); 829} catch (e) { 830 let error = e as BusinessError; 831 console.error(`Failed to get AllKVStoreId.code is ${error.code},message is ${error.message}`); 832} 833``` 834 835### getAllKVStoreId 836 837getAllKVStoreId(appId: string): Promise<string[]> 838 839获取所有通过[getKVStore](#getkvstore)方法创建的且没有调用[deleteKVStore](#deletekvstore)方法删除的分布式键值数据库的storeId，使用Promise异步回调。 840 841**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 842 843**参数：** 844 845| 参数名 | 类型 | 必填 | 说明 | 846| ------ | -------- | ---- | ---------------------- | 847| appId | string | 是 | 应用的BundleName，不可为空且长度不大于256。 | 848 849**返回值：** 850 851| 类型 | 说明 | 852| ----------------------- | ------------------------------------------------------ | 853| Promise<string[]> | Promise对象。返回所有创建的分布式键值数据库的storeId。 | 854 855**错误码：** 856 857以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 858 859| **错误码ID** | **错误信息** | 860| ------------ | ------------ | 861| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed.| 862 863**示例：** 864 865```ts 866import { BusinessError } from '@kit.BasicServicesKit'; 867 868try { 869 // appId为createKVManager中的appId 870 console.info('GetAllKVStoreId'); 871 kvManager.getAllKVStoreId(appId).then((data: string[]) => { 872 console.info('Succeeded in getting AllKVStoreId'); 873 console.info(`GetAllKVStoreId size = ${data.length}`); 874 }).catch((err: BusinessError) => { 875 console.error(`Failed to get AllKVStoreId.code is ${err.code},message is ${err.message}`); 876 }); 877} catch (e) { 878 let error = e as BusinessError; 879 console.error(`Failed to get AllKVStoreId.code is ${error.code},message is ${error.message}`); 880} 881``` 882 883### on('distributedDataServiceDie') 884 885on(event: 'distributedDataServiceDie', deathCallback: Callback<void>): void 886 887订阅服务状态变更通知。如果服务终止，需要重新注册数据变更通知和端端同步完成事件回调通知，并且端端同步操作会返回失败。 888 889**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 890 891**参数：** 892 893| 参数名 | 类型 | 必填 | 说明 | 894| ------------- | -------------------- | ---- | ------------------------------------------------------------ | 895| event | string | 是 | 订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。 | 896| deathCallback | Callback<void> | 是 | 回调函数。订阅成功，err为undefined，否则为错误对象。 | 897 898**错误码：** 899 900以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 901 902| **错误码ID** | **错误信息** | 903| ------------ | ------------ | 904| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed.| 905 906**示例：** 907 908```ts 909import { BusinessError } from '@kit.BasicServicesKit'; 910 911try { 912 console.info('KVManagerOn'); 913 const deathCallback = () => { 914 console.info('death callback call'); 915 } 916 kvManager.on('distributedDataServiceDie', deathCallback); 917} catch (e) { 918 let error = e as BusinessError; 919 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 920} 921``` 922 923### off('distributedDataServiceDie') 924 925off(event: 'distributedDataServiceDie', deathCallback?: Callback<void>): void 926 927取消订阅服务状态变更通知。参数中的deathCallback必须是已经订阅过的deathCallback，否则会取消订阅失败。 928 929**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 930 931**参数：** 932 933| 参数名 | 类型 | 必填 | 说明 | 934| ------------- | -------------------- | ---- | ------------------------------------------------------------ | 935| event | string | 是 | 取消订阅的事件名，固定为'distributedDataServiceDie'，即服务状态变更事件。 | 936| deathCallback | Callback<void> | 否 | 回调函数。如果该参数不填，那么会将之前订阅过的所有的deathCallback取消订阅。 | 937 938**错误码：** 939 940以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 941 942| **错误码ID** | **错误信息** | 943| ------------ | ------------ | 944| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 945 946**示例：** 947 948```ts 949import { BusinessError } from '@kit.BasicServicesKit'; 950 951try { 952 console.info('KVManagerOff'); 953 const deathCallback = () => { 954 console.info('death callback call'); 955 } 956 kvManager.off('distributedDataServiceDie', deathCallback); 957} catch (e) { 958 let error = e as BusinessError; 959 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 960} 961``` 962 963## KVStoreResultSet 964 965提供获取数据库结果集的相关方法，包括查询和移动数据读取位置等。同时允许打开的结果集的最大数量为8个。 966 967在调用KVStoreResultSet的方法前，需要先通过[getKVStore](#getkvstore)构建一个SingleKVStore或者DeviceKVStore实例。 968 969> **说明：** 970> 971> KVStoreResultSet的游标起始位置为-1。 972 973### getCount 974 975getCount(): number 976 977获取结果集中的总行数。 978 979**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 980 981**返回值：** 982 983| 类型 | 说明 | 984| ------ | ------------------ | 985| number | 返回数据的总行数。 | 986 987**示例：** 988 989```ts 990import { BusinessError } from '@kit.BasicServicesKit'; 991 992try { 993 let resultSet: distributedKVStore.KVStoreResultSet; 994 let count: number; 995 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 996 console.info('getResultSet succeed.'); 997 resultSet = result; 998 count = resultSet.getCount(); 999 console.info("getCount succeed:" + count); 1000 }).catch((err: BusinessError) => { 1001 console.error('getResultSet failed: ' + err); 1002 }); 1003} catch (e) { 1004 console.error("getCount failed: " + e); 1005} 1006``` 1007 1008### getPosition 1009 1010getPosition(): number 1011 1012获取结果集中当前的读取位置。读取位置会因[moveToFirst](#movetofirst)、[moveToLast](#movetolast)等操作而发生变化。 1013 1014**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1015 1016**返回值：** 1017 1018| 类型 | 说明 | 1019| ------ | ------------------ | 1020| number | 返回当前读取位置。取值范围>= -1，值为 -1 时表示还未开始读取，值为 0 时表示第一行。 | 1021 1022**示例：** 1023 1024```ts 1025import { BusinessError } from '@kit.BasicServicesKit'; 1026 1027try { 1028 let resultSet: distributedKVStore.KVStoreResultSet; 1029 let position: number; 1030 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1031 console.info('getResultSet succeeded.'); 1032 resultSet = result; 1033 position = resultSet.getPosition(); 1034 console.info("getPosition succeed:" + position); 1035 }).catch((err: BusinessError) => { 1036 console.error('getResultSet failed: ' + err); 1037 }); 1038} catch (e) { 1039 console.error("getPosition failed: " + e); 1040} 1041``` 1042 1043### moveToFirst 1044 1045moveToFirst(): boolean 1046 1047将读取位置移动到第一行。如果结果集为空，则返回false。 1048 1049**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1050 1051**返回值：** 1052 1053| 类型 | 说明 | 1054| ------- | ----------------------------------------------- | 1055| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1056 1057**示例：** 1058 1059```ts 1060import { BusinessError } from '@kit.BasicServicesKit'; 1061 1062try { 1063 let resultSet: distributedKVStore.KVStoreResultSet; 1064 let moved: boolean; 1065 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1066 console.info('getResultSet succeed.'); 1067 resultSet = result; 1068 moved = resultSet.moveToFirst(); 1069 console.info("moveToFirst succeed: " + moved); 1070 }).catch((err: BusinessError) => { 1071 console.error('getResultSet failed: ' + err); 1072 }); 1073} catch (e) { 1074 console.error("moveToFirst failed " + e); 1075} 1076``` 1077 1078### moveToLast 1079 1080moveToLast(): boolean 1081 1082将读取位置移动到最后一行。如果结果集为空，则返回false。 1083 1084**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1085 1086**返回值：** 1087 1088| 类型 | 说明 | 1089| ------- | ----------------------------------------------- | 1090| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1091 1092**示例：** 1093 1094```ts 1095import { BusinessError } from '@kit.BasicServicesKit'; 1096 1097try { 1098 let resultSet: distributedKVStore.KVStoreResultSet; 1099 let moved: boolean; 1100 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1101 console.info('getResultSet succeed.'); 1102 resultSet = result; 1103 moved = resultSet.moveToLast(); 1104 console.info("moveToLast succeed:" + moved); 1105 }).catch((err: BusinessError) => { 1106 console.error('getResultSet failed: ' + err); 1107 }); 1108} catch (e) { 1109 console.error("moveToLast failed: " + e); 1110} 1111``` 1112 1113### moveToNext 1114 1115moveToNext(): boolean 1116 1117将读取位置移动到下一行。如果结果集为空，则返回false。适用于全量获取数据库结果集的场景。 1118 1119**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1120 1121**返回值：** 1122 1123| 类型 | 说明 | 1124| ------- | ----------------------------------------------- | 1125| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1126 1127**示例：** 1128 1129```ts 1130import { BusinessError } from '@kit.BasicServicesKit'; 1131 1132try { 1133 let resultSet: distributedKVStore.KVStoreResultSet; 1134 let moved: boolean; 1135 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1136 console.info('getResultSet succeed.'); 1137 resultSet = result; 1138 do { 1139 moved = resultSet.moveToNext(); 1140 console.info("moveToNext succeed: " + moved); 1141 } while (moved) 1142 }).catch((err: BusinessError) => { 1143 console.error('getResultSet failed: ' + err); 1144 }); 1145} catch (e) { 1146 console.error("moveToNext failed: " + e); 1147} 1148``` 1149 1150### moveToPrevious 1151 1152moveToPrevious(): boolean 1153 1154将读取位置移动到上一行。如果结果集为空，则返回false。适用于全量获取数据库结果集的场景。 1155 1156**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1157 1158**返回值：** 1159 1160| 类型 | 说明 | 1161| ------- | ----------------------------------------------- | 1162| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1163 1164**示例：** 1165 1166```ts 1167import { BusinessError } from '@kit.BasicServicesKit'; 1168 1169try { 1170 let resultSet: distributedKVStore.KVStoreResultSet; 1171 let moved: boolean; 1172 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1173 console.info('getResultSet succeed.'); 1174 resultSet = result; 1175 moved = resultSet.moveToLast(); 1176 moved = resultSet.moveToPrevious(); 1177 console.info("moveToPrevious succeed:" + moved); 1178 }).catch((err: BusinessError) => { 1179 console.error('getResultSet failed: ' + err); 1180 }); 1181} catch (e) { 1182 console.error("moveToPrevious failed: " + e); 1183} 1184``` 1185 1186### move 1187 1188move(offset: number): boolean 1189 1190将读取位置移动到当前位置的相对偏移量。即当前游标位置向下偏移 offset 行。 1191 1192**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1193 1194**参数：** 1195 1196| 参数名 | 类型 | 必填 | 说明 | 1197| ------ | -------- | ---- | ------------------------------------------------------------ | 1198| offset | number | 是 | 表示与当前位置的相对偏移量，正偏移表示向前移动，负偏移表示向后移动。当游标超出结果集最前或者最后的位置时，接口返回false。| 1199 1200**返回值：** 1201 1202| 类型 | 说明 | 1203| ------- | ----------------------------------------------- | 1204| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1205 1206**错误码：** 1207 1208以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1209 1210| **错误码ID** | **错误信息** | 1211| ------------ | ------------ | 1212| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1213 1214**示例：** 1215 1216```ts 1217import { BusinessError } from '@kit.BasicServicesKit'; 1218 1219try { 1220 let resultSet: distributedKVStore.KVStoreResultSet; 1221 let moved: boolean; 1222 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1223 console.info('Succeeded in getting resultSet'); 1224 resultSet = result; 1225 moved = resultSet.move(2); //若当前位置为0，将读取位置从绝对位置为0的位置移动2行，即移动到绝对位置为2，行数为3的位置 1226 console.info(`Succeeded in moving.moved = ${moved}`); 1227 }).catch((err: BusinessError) => { 1228 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 1229 }); 1230} catch (e) { 1231 let error = e as BusinessError; 1232 console.error(`Failed to move.code is ${error.code},message is ${error.message}`); 1233} 1234``` 1235 1236### moveToPosition 1237 1238moveToPosition(position: number): boolean 1239 1240将读取位置从 0 移动到绝对位置。 1241 1242**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1243 1244**参数：** 1245 1246| 参数名 | 类型 | 必填 | 说明 | 1247| -------- | -------- | ---- | -------------- | 1248| position | number | 是 | 表示绝对位置。当绝对位置超出结果集最前或者最后的位置时，接口返回false。| 1249 1250**返回值：** 1251 1252| 类型 | 说明 | 1253| ------- | ----------------------------------------------- | 1254| boolean | 返回true表示操作成功；返回false则表示操作失败。 | 1255 1256**错误码：** 1257 1258以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1259 1260| **错误码ID** | **错误信息** | 1261| ------------ | ------------ | 1262| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 1263 1264**示例** 1265 1266```ts 1267import { BusinessError } from '@kit.BasicServicesKit'; 1268 1269try { 1270 let resultSet: distributedKVStore.KVStoreResultSet; 1271 let moved: boolean; 1272 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1273 console.info('Succeeded in getting resultSet'); 1274 resultSet = result; 1275 moved = resultSet.moveToPosition(1); 1276 console.info(`Succeeded in moving to position.moved=${moved}`); 1277 }).catch((err: BusinessError) => { 1278 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 1279 }); 1280} catch (e) { 1281 let error = e as BusinessError; 1282 console.error(`Failed to move to position.code is ${error.code},message is ${error.message}`); 1283} 1284``` 1285 1286### isFirst 1287 1288isFirst(): boolean 1289 1290检查读取位置是否为第一行。 1291 1292**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1293 1294**返回值：** 1295 1296| 类型 | 说明 | 1297| ------- | ------------------------------------------------------------ | 1298| boolean | 返回true表示读取位置为第一行；返回false表示读取位置不是第一行。 | 1299 1300**示例：** 1301 1302```ts 1303import { BusinessError } from '@kit.BasicServicesKit'; 1304 1305try { 1306 let resultSet: distributedKVStore.KVStoreResultSet; 1307 let isfirst: boolean; 1308 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1309 console.info('getResultSet succeed.'); 1310 resultSet = result; 1311 isfirst = resultSet.isFirst(); 1312 console.info("Check isFirst succeed:" + isfirst); 1313 }).catch((err: BusinessError) => { 1314 console.error('getResultSet failed: ' + err); 1315 }); 1316} catch (e) { 1317 console.error("Check isFirst failed: " + e); 1318} 1319``` 1320 1321### isLast 1322 1323isLast(): boolean 1324 1325检查读取位置是否为最后一行。 1326 1327**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1328 1329**返回值：** 1330 1331| 类型 | 说明 | 1332| ------- | ------------------------------------------------------------ | 1333| boolean | 返回true表示读取位置为最后一行；返回false表示读取位置不是最后一行。 | 1334 1335**示例：** 1336 1337```ts 1338import { BusinessError } from '@kit.BasicServicesKit'; 1339 1340try { 1341 let resultSet: distributedKVStore.KVStoreResultSet; 1342 let islast: boolean; 1343 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1344 console.info('getResultSet succeed.'); 1345 resultSet = result; 1346 islast = resultSet.isLast(); 1347 console.info("Check isLast succeed: " + islast); 1348 }).catch((err: BusinessError) => { 1349 console.error('getResultSet failed: ' + err); 1350 }); 1351} catch (e) { 1352 console.error("Check isLast failed: " + e); 1353} 1354``` 1355 1356### isBeforeFirst 1357 1358isBeforeFirst(): boolean 1359 1360检查读取位置是否在第一行之前。 1361 1362**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1363 1364**返回值：** 1365 1366| 类型 | 说明 | 1367| ------- | ------------------------------------------------------------ | 1368| boolean | 返回true表示读取位置在第一行之前；返回false表示读取位置不在第一行之前。 | 1369 1370**示例：** 1371 1372```ts 1373import { BusinessError } from '@kit.BasicServicesKit'; 1374 1375try { 1376 let resultSet: distributedKVStore.KVStoreResultSet; 1377 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1378 console.info('getResultSet succeed.'); 1379 resultSet = result; 1380 let isbeforefirst = resultSet.isBeforeFirst(); 1381 console.info("Check isBeforeFirst succeed: " + isbeforefirst); 1382 }).catch((err: BusinessError) => { 1383 console.error('getResultSet failed: ' + err); 1384 }); 1385} catch (e) { 1386 console.error("Check isBeforeFirst failed: " + e); 1387} 1388``` 1389 1390### isAfterLast 1391 1392isAfterLast(): boolean 1393 1394检查读取位置是否在最后一行之后。 1395 1396**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1397 1398**返回值：** 1399 1400| 类型 | 说明 | 1401| ------- | ------------------------------------------------------------ | 1402| boolean | 返回true表示读取位置在最后一行之后；返回false表示读取位置不在最后一行之后。 | 1403 1404**示例：** 1405 1406```ts 1407import { BusinessError } from '@kit.BasicServicesKit'; 1408 1409try { 1410 let resultSet: distributedKVStore.KVStoreResultSet; 1411 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1412 console.info('getResultSet succeed.'); 1413 resultSet = result; 1414 let isafterlast = resultSet.isAfterLast(); 1415 console.info("Check isAfterLast succeed:" + isafterlast); 1416 }).catch((err: BusinessError) => { 1417 console.error('getResultSet failed: ' + err); 1418 }); 1419} catch (e) { 1420 console.error("Check isAfterLast failed: " + e); 1421} 1422``` 1423 1424### getEntry 1425 1426getEntry(): Entry 1427 1428从当前位置获取对应的键值对。 1429 1430**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1431 1432**返回值：** 1433 1434| 类型 | 说明 | 1435| --------------- | ------------ | 1436| [Entry](#entry) | 返回键值对。 | 1437 1438**示例：** 1439 1440```ts 1441import { BusinessError } from '@kit.BasicServicesKit'; 1442 1443try { 1444 let resultSet: distributedKVStore.KVStoreResultSet; 1445 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 1446 console.info('getResultSet succeed.'); 1447 resultSet = result; 1448 let entry = resultSet.getEntry(); 1449 console.info("getEntry succeed:" + JSON.stringify(entry)); 1450 }).catch((err: BusinessError) => { 1451 console.error('getResultSet failed: ' + err); 1452 }); 1453} catch (e) { 1454 console.error("getEntry failed: " + e); 1455} 1456``` 1457 1458## Query 1459 1460使用谓词表示数据库查询，提供创建Query实例、查询数据库中的数据和添加谓词的方法。一个Query对象中谓词数量上限为256个。 1461 1462**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1463 1464### constructor 1465 1466constructor() 1467 1468用于创建Query实例的构造函数。 1469 1470**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1471 1472### reset 1473 1474reset(): Query 1475 1476重置Query对象。 1477 1478**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1479 1480**返回值：** 1481 1482| 类型 | 说明 | 1483| -------------- | --------------------- | 1484| [Query](#query) | 返回重置的Query对象。 | 1485 1486**示例：** 1487 1488```ts 1489import { BusinessError } from '@kit.BasicServicesKit'; 1490 1491try { 1492 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1493 if (query != null) { 1494 query.equalTo("key", "value"); 1495 console.info("query is " + query.getSqlLike()); 1496 query.reset(); 1497 console.info("query is " + query.getSqlLike()); 1498 } 1499 query = null; 1500} catch (e) { 1501 console.error("simply calls should be ok :" + e); 1502} 1503``` 1504 1505### equalTo 1506 1507equalTo(field: string, value: number|string|boolean): Query 1508 1509构造一个Query对象来查询具有指定字段的条目，其值等于指定的值。 1510 1511**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1512 1513**参数：** 1514 1515| 参数名 | 类型 | 必填 | 说明 | 1516| ----- | ------ | ---- | ----------------------- | 1517| field | string | 是 |表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1518| value | number\|string\|boolean | 是 | 表示指定的值。| 1519 1520**返回值：** 1521 1522| 类型 | 说明 | 1523| -------------- | --------------- | 1524| [Query](#query) | 返回Query对象。 | 1525 1526**错误码：** 1527 1528以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1529 1530| **错误码ID** | **错误信息** | 1531| ------------ | ------------ | 1532| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1533 1534**示例：** 1535 1536```ts 1537import { BusinessError } from '@kit.BasicServicesKit'; 1538 1539try { 1540 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1541 if (query != null) { 1542 query.equalTo("field", "value"); 1543 console.info(`query is ${query.getSqlLike()}`); 1544 } 1545 query = null; 1546} catch (e) { 1547 let error = e as BusinessError; 1548 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1549} 1550``` 1551 1552### notEqualTo 1553 1554notEqualTo(field: string, value: number|string|boolean): Query 1555 1556构造一个Query对象以查询具有指定字段且值不等于指定值的条目。 1557 1558**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1559 1560**参数：** 1561 1562| 参数名 | 类型 | 必填 | 说明 | 1563| ----- | ------ | ---- | ----------------------- | 1564| field | string | 是 |表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1565| value | number\|string\|boolean | 是 | 表示指定的值。| 1566 1567**返回值：** 1568 1569| 类型 | 说明 | 1570| -------------- | --------------- | 1571| [Query](#query) | 返回Query对象。 | 1572 1573**错误码：** 1574 1575以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1576 1577| **错误码ID** | **错误信息** | 1578| ------------ | ------------ | 1579| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1580 1581**示例：** 1582 1583```ts 1584import { BusinessError } from '@kit.BasicServicesKit'; 1585 1586try { 1587 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1588 if (query != null) { 1589 query.notEqualTo("field", "value"); 1590 console.info(`query is ${query.getSqlLike()}`); 1591 } 1592 query = null; 1593} catch (e) { 1594 let error = e as BusinessError; 1595 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1596} 1597``` 1598 1599### greaterThan 1600 1601greaterThan(field: string, value: number|string|boolean): Query 1602 1603构造一个Query对象以查询具有大于指定值的指定字段的条目。 1604 1605**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1606 1607**参数：** 1608| 参数名 | 类型 | 必填 | 说明 | 1609| ----- | ------ | ---- | ----------------------- | 1610| field | string | 是 |表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1611| value | number\|string\|boolean | 是 | 表示指定的值。| 1612 1613**返回值：** 1614 1615| 类型 | 说明 | 1616| -------------- | --------------- | 1617| [Query](#query) | 返回Query对象。 | 1618 1619**错误码：** 1620 1621以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1622 1623| **错误码ID** | **错误信息** | 1624| ------------ | ------------ | 1625| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1626 1627**示例：** 1628 1629```ts 1630import { BusinessError } from '@kit.BasicServicesKit'; 1631 1632try { 1633 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1634 if (query != null) { 1635 query.greaterThan("field", "value"); 1636 console.info(`query is ${query.getSqlLike()}`); 1637 } 1638 query = null; 1639} catch (e) { 1640 let error = e as BusinessError; 1641 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1642} 1643``` 1644 1645### lessThan 1646 1647lessThan(field: string, value: number|string): Query 1648 1649构造一个Query对象以查询具有小于指定值的指定字段的条目。 1650 1651**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1652 1653**参数：** 1654 1655 1656| 参数名 | 类型 | 必填 | 说明 | 1657| ----- | ------ | ---- | ----------------------- | 1658| field | string | 是 |表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1659| value | number\|string | 是 | 表示指定的值。| 1660 1661**返回值：** 1662 1663| 类型 | 说明 | 1664| -------------- | --------------- | 1665| [Query](#query) | 返回Query对象。 | 1666 1667**错误码：** 1668 1669以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1670 1671| **错误码ID** | **错误信息** | 1672| ------------ | ------------ | 1673| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1674 1675**示例：** 1676 1677```ts 1678import { BusinessError } from '@kit.BasicServicesKit'; 1679 1680try { 1681 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1682 if (query != null) { 1683 query.lessThan("field", "value"); 1684 console.info(`query is ${query.getSqlLike()}`); 1685 } 1686 query = null; 1687} catch (e) { 1688 let error = e as BusinessError; 1689 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1690} 1691``` 1692 1693### greaterThanOrEqualTo 1694 1695greaterThanOrEqualTo(field: string, value: number|string): Query 1696 1697构造一个Query对象以查询具有指定字段且值大于或等于指定值的条目。 1698 1699**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1700 1701**参数：** 1702 1703 1704| 参数名 | 类型 | 必填 | 说明 | 1705| ----- | ------ | ---- | ----------------------- | 1706| field | string | 是 |表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1707| value | number\|string | 是 | 表示指定的值。| 1708 1709**返回值：** 1710 1711| 类型 | 说明 | 1712| -------------- | --------------- | 1713| [Query](#query) | 返回Query对象。 | 1714 1715**错误码：** 1716 1717以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1718 1719| **错误码ID** | **错误信息** | 1720| ------------ | ------------ | 1721| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1722 1723**示例：** 1724 1725```ts 1726import { BusinessError } from '@kit.BasicServicesKit'; 1727 1728try { 1729 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1730 if (query != null) { 1731 query.greaterThanOrEqualTo("field", "value"); 1732 console.info(`query is ${query.getSqlLike()}`); 1733 } 1734 query = null; 1735} catch (e) { 1736 let error = e as BusinessError; 1737 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1738} 1739``` 1740 1741### lessThanOrEqualTo 1742 1743lessThanOrEqualTo(field: string, value: number|string): Query 1744 1745构造一个Query对象以查询具有指定字段且值小于或等于指定值的条目。 1746 1747**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1748 1749**参数：** 1750 1751 1752| 参数名 | 类型 | 必填 | 说明 | 1753| ----- | ------ | ---- | ----------------------- | 1754| field | string | 是 |表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1755| value | number\|string | 是 | 表示指定的值。| 1756 1757**返回值：** 1758 1759| 类型 | 说明 | 1760| -------------- | --------------- | 1761| [Query](#query) | 返回Query对象。 | 1762 1763**错误码：** 1764 1765以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1766 1767| **错误码ID** | **错误信息** | 1768| ------------ | ------------ | 1769| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1770 1771**示例：** 1772 1773```ts 1774import { BusinessError } from '@kit.BasicServicesKit'; 1775 1776try { 1777 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1778 if (query != null) { 1779 query.lessThanOrEqualTo("field", "value"); 1780 console.info(`query is ${query.getSqlLike()}`); 1781 } 1782 query = null; 1783} catch (e) { 1784 let error = e as BusinessError; 1785 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1786} 1787``` 1788 1789### isNull 1790 1791isNull(field: string): Query 1792 1793构造一个Query对象以查询具有值为null的指定字段的条目。 1794 1795**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1796 1797**参数：** 1798 1799| 参数名 | 类型 | 必填 | 说明 | 1800| ------ | -------- | ---- | ----------------------------- | 1801| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1802 1803**返回值：** 1804 1805| 类型 | 说明 | 1806| -------------- | --------------- | 1807| [Query](#query) | 返回Query对象。 | 1808 1809**错误码：** 1810 1811以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1812 1813| **错误码ID** | **错误信息** | 1814| ------------ | ------------ | 1815| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1816 1817**示例：** 1818 1819```ts 1820import { BusinessError } from '@kit.BasicServicesKit'; 1821 1822try { 1823 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1824 if (query != null) { 1825 query.isNull("field"); 1826 console.info(`query is ${query.getSqlLike()}`); 1827 } 1828 query = null; 1829} catch (e) { 1830 let error = e as BusinessError; 1831 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1832} 1833``` 1834 1835### inNumber 1836 1837inNumber(field: string, valueList: number[]): Query 1838 1839构造一个Query对象以查询具有指定字段的条目，其值在指定的值列表中。 1840 1841**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1842 1843**参数：** 1844 1845| 参数名 | 类型 | 必填 | 说明 | 1846| --------- | -------- | ---- | ----------------------------- | 1847| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1848| valueList | number[] | 是 | 表示指定的值列表。 | 1849 1850**返回值：** 1851 1852| 类型 | 说明 | 1853| -------------- | --------------- | 1854| [Query](#query) | 返回Query对象。 | 1855 1856**错误码：** 1857 1858以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1859 1860| **错误码ID** | **错误信息** | 1861| ------------ | ------------ | 1862| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1863 1864**示例：** 1865 1866```ts 1867import { BusinessError } from '@kit.BasicServicesKit'; 1868 1869try { 1870 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1871 if (query != null) { 1872 query.inNumber("field", [0, 1]); 1873 console.info(`query is ${query.getSqlLike()}`); 1874 } 1875 query = null; 1876} catch (e) { 1877 let error = e as BusinessError; 1878 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1879} 1880``` 1881 1882### inString 1883 1884inString(field: string, valueList: string[]): Query 1885 1886构造一个Query对象以查询具有指定字段的条目，其值在指定的字符串值列表中。 1887 1888**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1889 1890**参数：** 1891 1892| 参数名 | 类型 | 必填 | 说明 | 1893| --------- | -------- | ---- | ----------------------------- | 1894| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1895| valueList | string[] | 是 | 表示指定的字符串值列表。 | 1896 1897**返回值：** 1898 1899| 类型 | 说明 | 1900| -------------- | --------------- | 1901| [Query](#query) | 返回Query对象。 | 1902 1903**错误码：** 1904 1905以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1906 1907| **错误码ID** | **错误信息** | 1908| ------------ | ------------ | 1909| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1910 1911**示例：** 1912 1913```ts 1914import { BusinessError } from '@kit.BasicServicesKit'; 1915 1916try { 1917 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1918 if (query != null) { 1919 query.inString("field", ['test1', 'test2']); 1920 console.info(`query is ${query.getSqlLike()}`); 1921 } 1922 query = null; 1923} catch (e) { 1924 let error = e as BusinessError; 1925 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1926} 1927``` 1928 1929### notInNumber 1930 1931notInNumber(field: string, valueList: number[]): Query 1932 1933构造一个Query对象以查询具有指定字段的条目，该字段的值不在指定的值列表中。 1934 1935**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1936 1937**参数：** 1938 1939| 参数名 | 类型 | 必填 | 说明 | 1940| --------- | -------- | ---- | ----------------------------- | 1941| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1942| valueList | number[] | 是 | 表示指定的值列表。 | 1943 1944**返回值：** 1945 1946| 类型 | 说明 | 1947| -------------- | --------------- | 1948| [Query](#query) | 返回Query对象。 | 1949 1950**错误码：** 1951 1952以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 1953 1954| **错误码ID** | **错误信息** | 1955| ------------ | ------------ | 1956| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 1957 1958**示例：** 1959 1960```ts 1961import { BusinessError } from '@kit.BasicServicesKit'; 1962 1963try { 1964 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 1965 if (query != null) { 1966 query.notInNumber("field", [0, 1]); 1967 console.info(`query is ${query.getSqlLike()}`); 1968 } 1969 query = null; 1970} catch (e) { 1971 let error = e as BusinessError; 1972 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 1973} 1974``` 1975 1976### notInString 1977 1978notInString(field: string, valueList: string[]): Query 1979 1980构造一个Query对象以查询具有指定字段且值不在指定字符串值列表中的条目。 1981 1982**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 1983 1984**参数：** 1985 1986| 参数名 | 类型 | 必填 | 说明 | 1987| --------- | -------- | ---- | ----------------------------- | 1988| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 1989| valueList | string[] | 是 | 表示指定的字符串值列表。 | 1990 1991**返回值：** 1992 1993| 类型 | 说明 | 1994| -------------- | --------------- | 1995| [Query](#query) | 返回Query对象。 | 1996 1997**错误码：** 1998 1999以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2000 2001| **错误码ID** | **错误信息** | 2002| ------------ | ------------ | 2003| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2004 2005**示例：** 2006 2007```ts 2008import { BusinessError } from '@kit.BasicServicesKit'; 2009 2010try { 2011 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2012 if (query != null) { 2013 query.notInString("field", ['test1', 'test2']); 2014 console.info(`query is ${query.getSqlLike()}`); 2015 } 2016 query = null; 2017} catch (e) { 2018 let error = e as BusinessError; 2019 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2020} 2021``` 2022 2023### like 2024 2025like(field: string, value: string): Query 2026 2027构造一个Query对象以查询具有与指定字符串值相似的指定字段的条目。 2028 2029**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2030 2031**参数：** 2032 2033| 参数名 | 类型 | 必填 | 说明 | 2034| ------ | -------- | ---- | ----------------------------- | 2035| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2036| value | string | 是 | 表示指定的字符串值。 | 2037 2038**返回值：** 2039 2040| 类型 | 说明 | 2041| -------------- | --------------- | 2042| [Query](#query) | 返回Query对象。 | 2043 2044**错误码：** 2045 2046以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2047 2048| **错误码ID** | **错误信息** | 2049| ------------ | ------------ | 2050| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2051 2052**示例：** 2053 2054```ts 2055import { BusinessError } from '@kit.BasicServicesKit'; 2056 2057try { 2058 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2059 if (query != null) { 2060 query.like("field", "value"); 2061 console.info(`query is ${query.getSqlLike()}`); 2062 } 2063 query = null; 2064} catch (e) { 2065 let error = e as BusinessError; 2066 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2067} 2068``` 2069 2070### unlike 2071 2072unlike(field: string, value: string): Query 2073 2074构造一个Query对象以查询具有与指定字符串值不相似的指定字段的条目。 2075 2076**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2077 2078**参数：** 2079 2080| 参数名 | 类型 | 必填 | 说明 | 2081| ------ | -------- | ---- | ----------------------------- | 2082| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2083| value | string | 是 | 表示指定的字符串值。 | 2084 2085**返回值：** 2086 2087| 类型 | 说明 | 2088| -------------- | --------------- | 2089| [Query](#query) | 返回Query对象。 | 2090 2091**错误码：** 2092 2093以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2094 2095| **错误码ID** | **错误信息** | 2096| ------------ | ------------ | 2097| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2098 2099**示例：** 2100 2101```ts 2102import { BusinessError } from '@kit.BasicServicesKit'; 2103 2104try { 2105 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2106 if (query != null) { 2107 query.unlike("field", "value"); 2108 console.info(`query is ${query.getSqlLike()}`); 2109 } 2110 query = null; 2111} catch (e) { 2112 let error = e as BusinessError; 2113 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2114} 2115``` 2116 2117### and 2118 2119and(): Query 2120 2121构造一个带有与条件的查询对象。 2122 2123**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2124 2125**返回值：** 2126 2127| 类型 | 说明 | 2128| -------------- | -------------- | 2129| [Query](#query) | 返回查询对象。 | 2130 2131**示例：** 2132 2133```ts 2134import { BusinessError } from '@kit.BasicServicesKit'; 2135 2136try { 2137 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2138 if (query != null) { 2139 query.notEqualTo("field", "value1"); 2140 query.and(); 2141 query.notEqualTo("field", "value2"); 2142 console.info("query is " + query.getSqlLike()); 2143 } 2144 query = null; 2145} catch (e) { 2146 console.error("duplicated calls should be ok :" + e); 2147} 2148``` 2149 2150### or 2151 2152or(): Query 2153 2154构造一个带有或条件的Query对象。 2155 2156**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2157 2158**返回值：** 2159 2160| 类型 | 说明 | 2161| -------------- | -------------- | 2162| [Query](#query) | 返回查询对象。 | 2163 2164**示例：** 2165 2166```ts 2167import { BusinessError } from '@kit.BasicServicesKit'; 2168 2169try { 2170 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2171 if (query != null) { 2172 query.notEqualTo("field", "value1"); 2173 query.or(); 2174 query.notEqualTo("field", "value2"); 2175 console.info("query is " + query.getSqlLike()); 2176 } 2177 query = null; 2178} catch (e) { 2179 console.error("duplicated calls should be ok :" + e); 2180} 2181``` 2182 2183### orderByAsc 2184 2185orderByAsc(field: string): Query 2186 2187构造一个Query对象，将查询结果按升序排序。 2188 2189**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2190 2191**参数：** 2192 2193| 参数名 | 类型 | 必填 | 说明 | 2194| ------ | -------- | ---- | ----------------------------- | 2195| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2196 2197**返回值：** 2198 2199| 类型 | 说明 | 2200| -------------- | --------------- | 2201| [Query](#query) | 返回Query对象。 | 2202 2203**错误码：** 2204 2205以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2206 2207| **错误码ID** | **错误信息** | 2208| ------------ | ------------ | 2209| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2210 2211**示例：** 2212 2213```ts 2214import { BusinessError } from '@kit.BasicServicesKit'; 2215 2216try { 2217 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2218 if (query != null) { 2219 query.notEqualTo("field", "value"); 2220 query.orderByAsc("field"); 2221 console.info(`query is ${query.getSqlLike()}`); 2222 } 2223 query = null; 2224} catch (e) { 2225 let error = e as BusinessError; 2226 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2227} 2228``` 2229 2230### orderByDesc 2231 2232orderByDesc(field: string): Query 2233 2234构造一个Query对象，将查询结果按降序排序。 2235 2236**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2237 2238**参数：** 2239 2240| 参数名 | 类型 | 必填 | 说明 | 2241| ------ | -------- | ---- | ----------------------------- | 2242| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2243 2244**返回值：** 2245 2246| 类型 | 说明 | 2247| -------------- | --------------- | 2248| [Query](#query) | 返回Query对象。 | 2249 2250**错误码：** 2251 2252以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2253 2254| **错误码ID** | **错误信息** | 2255| ------------ | ------------ | 2256| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2257 2258**示例：** 2259 2260```ts 2261import { BusinessError } from '@kit.BasicServicesKit'; 2262 2263try { 2264 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2265 if (query != null) { 2266 query.notEqualTo("field", "value"); 2267 query.orderByDesc("field"); 2268 console.info(`query is ${query.getSqlLike()}`); 2269 } 2270 query = null; 2271} catch (e) { 2272 let error = e as BusinessError; 2273 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2274} 2275``` 2276 2277### limit 2278 2279limit(total: number, offset: number): Query 2280 2281构造一个Query对象来指定结果的数量和开始位置。该接口必须要在Query对象查询和升降序等操作之后调用，调用limit接口后，不可再对Query对象进行查询和升降序等操作。 2282 2283**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2284 2285**参数：** 2286 2287| 参数名 | 类型 | 必填 | 说明 | 2288| ------ | -------- | ---- | ------------------ | 2289| total | number | 是 | 表示最大数据记录数，取值应为非负整数。<br/>当total为负数时，表示查询整个结果集。| 2290| offset | number | 是 | 指定查询结果的起始位置，取值应为非负整数。<br/>当offset为负数时，表示查询整个结果集。<br/>当offset超出结果集最后位置时，查询结果为空。| 2291 2292**返回值：** 2293 2294| 类型 | 说明 | 2295| -------------- | --------------- | 2296| [Query](#query) | 返回Query对象。 | 2297 2298**错误码：** 2299 2300以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2301 2302| **错误码ID** | **错误信息** | 2303| ------------ | ------------ | 2304| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 2305 2306**示例：** 2307 2308```ts 2309import { BusinessError } from '@kit.BasicServicesKit'; 2310 2311let total = 10; 2312let offset = 1; 2313try { 2314 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2315 if (query != null) { 2316 query.notEqualTo("field", "value"); 2317 query.limit(total, offset); 2318 console.info(`query is ${query.getSqlLike()}`); 2319 } 2320 query = null; 2321} catch (e) { 2322 let error = e as BusinessError; 2323 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2324} 2325``` 2326 2327### isNotNull 2328 2329isNotNull(field: string): Query 2330 2331构造一个Query对象以查询具有值不为null的指定字段的条目。 2332 2333**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2334 2335**参数：** 2336 2337| 参数名 | 类型 | 必填 | 说明 | 2338| ------ | -------- | ---- | ----------------------------- | 2339| field | string | 是 | 表示指定字段，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2340 2341**返回值：** 2342 2343| 类型 | 说明 | 2344| -------------- | --------------- | 2345| [Query](#query) | 返回Query对象。 | 2346 2347**错误码：** 2348 2349以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2350 2351| **错误码ID** | **错误信息** | 2352| ------------ | ------------ | 2353| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2354 2355**示例：** 2356 2357```ts 2358import { BusinessError } from '@kit.BasicServicesKit'; 2359 2360try { 2361 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2362 if (query != null) { 2363 query.isNotNull("field"); 2364 console.info(`query is ${query.getSqlLike()}`); 2365 } 2366 query = null; 2367} catch (e) { 2368 let error = e as BusinessError; 2369 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2370} 2371``` 2372 2373### beginGroup 2374 2375beginGroup(): Query 2376 2377创建一个带有左括号的查询条件组。 2378 2379**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2380 2381**返回值：** 2382 2383| 类型 | 说明 | 2384| -------------- | --------------- | 2385| [Query](#query) | 返回Query对象。 | 2386 2387**示例：** 2388 2389```ts 2390import { BusinessError } from '@kit.BasicServicesKit'; 2391 2392try { 2393 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2394 if (query != null) { 2395 query.beginGroup(); 2396 query.isNotNull("field"); 2397 query.endGroup(); 2398 console.info("query is " + query.getSqlLike()); 2399 } 2400 query = null; 2401} catch (e) { 2402 console.error("duplicated calls should be ok :" + e); 2403} 2404``` 2405 2406### endGroup 2407 2408endGroup(): Query 2409 2410创建一个带有右括号的查询条件组。 2411 2412**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2413 2414**返回值：** 2415 2416| 类型 | 说明 | 2417| -------------- | --------------- | 2418| [Query](#query) | 返回Query对象。 | 2419 2420**示例：** 2421 2422```ts 2423import { BusinessError } from '@kit.BasicServicesKit'; 2424 2425try { 2426 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2427 if (query != null) { 2428 query.beginGroup(); 2429 query.isNotNull("field"); 2430 query.endGroup(); 2431 console.info("query is " + query.getSqlLike()); 2432 } 2433 query = null; 2434} catch (e) { 2435 console.error("duplicated calls should be ok :" + e); 2436} 2437``` 2438 2439### prefixKey 2440 2441prefixKey(prefix: string): Query 2442 2443创建具有指定键前缀的查询条件。 2444 2445**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2446 2447**参数：** 2448 2449| 参数名 | 类型 | 必填 | 说明 | 2450| ------ | -------- | ---- | ------------------ | 2451| prefix | string | 是 | 表示指定的键前缀，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2452 2453**返回值：** 2454 2455| 类型 | 说明 | 2456| -------------- | --------------- | 2457| [Query](#query) | 返回Query对象。 | 2458 2459**错误码：** 2460 2461以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2462 2463| **错误码ID** | **错误信息** | 2464| ------------ | ------------ | 2465| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 2466 2467**示例：** 2468 2469```ts 2470import { BusinessError } from '@kit.BasicServicesKit'; 2471 2472try { 2473 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2474 if (query != null) { 2475 query.prefixKey("$.name"); 2476 query.prefixKey("0"); 2477 console.info(`query is ${query.getSqlLike()}`); 2478 } 2479 query = null; 2480} catch (e) { 2481 let error = e as BusinessError; 2482 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2483} 2484``` 2485 2486### setSuggestIndex 2487 2488setSuggestIndex(index: string): Query 2489 2490设置一个指定的索引，将优先用于查询。 2491 2492**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2493 2494**参数：** 2495 2496| 参数名 | 类型 | 必填 | 说明 | 2497| ------ | -------- | ---- | ------------------ | 2498| index | string | 是 | 指示要设置的索引，不能包含'^'。包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 2499 2500**返回值：** 2501 2502| 类型 | 说明 | 2503| -------------- | --------------- | 2504| [Query](#query) | 返回Query对象。 | 2505 2506**错误码：** 2507 2508以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2509 2510| **错误码ID** | **错误信息** | 2511| ------------ | ------------ | 2512| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 2513 2514**示例：** 2515 2516```ts 2517import { BusinessError } from '@kit.BasicServicesKit'; 2518 2519try { 2520 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2521 if (query != null) { 2522 query.setSuggestIndex("$.name"); 2523 query.setSuggestIndex("0"); 2524 console.info(`query is ${query.getSqlLike()}`); 2525 } 2526 query = null; 2527} catch (e) { 2528 let error = e as BusinessError; 2529 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2530} 2531``` 2532 2533### deviceId 2534 2535deviceId(deviceId:string):Query 2536 2537添加设备ID作为Key的前缀。 2538> **说明：** 2539> 2540> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 2541> deviceId具体获取方式请参考[sync接口示例](#sync)。 2542 2543**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2544 2545**参数：** 2546 2547| 参数名 | 类型 | 必填 | 说明 | 2548| -------- | -------- | ---- | ------------------ | 2549| deviceId | string | 是 | 指示查询的设备ID，不能为空。 | 2550 2551**返回值：** 2552 2553| 类型 | 说明 | 2554| -------------- | --------------- | 2555| [Query](#query) | 返回Query对象。 | 2556 2557**错误码：** 2558 2559以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 2560 2561| **错误码ID** | **错误信息** | 2562| ------------ | ------------ | 2563| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2564 2565**示例：** 2566 2567```ts 2568import { BusinessError } from '@kit.BasicServicesKit'; 2569 2570try { 2571 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2572 if (query != null) { 2573 query.deviceId("deviceId"); 2574 console.info(`query is ${query.getSqlLike()}`); 2575 } 2576} catch (e) { 2577 let error = e as BusinessError; 2578 console.error(`duplicated calls should be ok.code is ${error.code},message is ${error.message}`); 2579} 2580``` 2581 2582### getSqlLike 2583 2584getSqlLike():string 2585 2586获取Query对象的查询语句。 2587 2588**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2589 2590**返回值：** 2591 2592| 类型 | 说明 | 2593| ------ | ------------------------------------ | 2594| string | 返回一个字段列中包含对应子串的结果。 | 2595 2596**示例：** 2597 2598```ts 2599import { BusinessError } from '@kit.BasicServicesKit'; 2600 2601try { 2602 let query: distributedKVStore.Query | null = new distributedKVStore.Query(); 2603 if (query != null) { 2604 let sql1 = query.getSqlLike(); 2605 console.info(`GetSqlLike sql= ${sql1}`); 2606 } 2607} catch (e) { 2608 console.error("duplicated calls should be ok : " + e); 2609} 2610``` 2611 2612## SingleKVStore 2613 2614SingleKVStore数据库实例，提供增加数据、删除数据和订阅数据变更、订阅数据端端同步完成的方法。 2615 2616在调用SingleKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个SingleKVStore实例。 2617 2618### put 2619 2620put(key: string, value: Uint8Array | string | number | boolean, callback: AsyncCallback<void>): void 2621 2622添加指定类型键值对到数据库，使用callback异步回调。 2623 2624**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2625 2626**参数：** 2627 2628| 参数名 | 类型 | 必填 | 说明 | 2629| ----- | ------ | ---- | ----------------------- | 2630| key | string | 是 |要添加数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2631| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | 2632| callback | AsyncCallback<void> | 是 |回调函数。数据添加成功，err为undefined，否则为错误对象。 | 2633 2634**错误码：** 2635 2636以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 2637 2638| **错误码ID** | **错误信息** | 2639| ------------ | ---------------------------------------- | 2640| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2641| 15100003 | Database corrupted. | 2642| 15100005 | Database or result set already closed. | 2643 2644以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 2645 2646| **错误码ID** | **错误信息** | 2647| ------------ | -------------------------------------------- | 2648| 14800047 | The WAL file size exceeds the default limit. | 2649 2650**示例：** 2651 2652```ts 2653import { BusinessError } from '@kit.BasicServicesKit'; 2654 2655const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2656const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2657try { 2658 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err: BusinessError) => { 2659 if (err != undefined) { 2660 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2661 return; 2662 } 2663 console.info("Succeeded in putting"); 2664 }); 2665} catch (e) { 2666 let error = e as BusinessError; 2667 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 2668} 2669``` 2670 2671### put 2672 2673put(key: string, value: Uint8Array | string | number | boolean): Promise<void> 2674 2675添加指定类型键值对到数据库，使用Promise异步回调。 2676 2677**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2678 2679**参数：** 2680 2681| 参数名 | 类型 | 必填 | 说明 | 2682| ----- | ------ | ---- | ----------------------- | 2683| key | string | 是 |要添加数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2684| value | Uint8Array \| string \| number \| boolean | 是 |要添加数据的value，支持Uint8Array、number 、 string 、boolean，Uint8Array、string 的长度不大于[MAX_VALUE_LENGTH](#constants)。 | 2685 2686**返回值：** 2687 2688| 类型 | 说明 | 2689| ------------------- | ------------------------- | 2690| Promise<void> | 无返回结果的Promise对象。 | 2691 2692**错误码：** 2693 2694以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 2695 2696| **错误码ID** | **错误信息** | 2697| ------------ | ---------------------------------------- | 2698| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2699| 15100003 | Database corrupted. | 2700| 15100005 | Database or result set already closed. | 2701 2702以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 2703 2704| **错误码ID** | **错误信息** | 2705| ------------ | -------------------------------------------- | 2706| 14800047 | The WAL file size exceeds the default limit. | 2707 2708**示例：** 2709 2710```ts 2711import { BusinessError } from '@kit.BasicServicesKit'; 2712 2713const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2714const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2715try { 2716 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 2717 console.info(`Succeeded in putting data`); 2718 }).catch((err: BusinessError) => { 2719 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2720 }); 2721} catch (e) { 2722 let error = e as BusinessError; 2723 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 2724} 2725``` 2726 2727### putBatch 2728 2729putBatch(entries: Entry[], callback: AsyncCallback<void>): void 2730 2731批量插入键值对到SingleKVStore数据库中，使用callback异步回调。 2732 2733**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2734 2735**参数：** 2736 2737| 参数名 | 类型 | 必填 | 说明 | 2738| -------- | ------------------------ | ---- | ------------------------ | 2739| entries | [Entry](#entry)[] | 是 | 表示要批量插入的键值对。一个entries对象中允许的最大数据量为512M。 | 2740| callback | AsyncCallback<void> | 是 | 回调函数。数据批量插入成功，err为undefined，否则为错误对象。 | 2741 2742**错误码：** 2743 2744以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 2745 2746| **错误码ID** | **错误信息** | 2747| ------------ | ---------------------------------------- | 2748| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 2749| 15100003 | Database corrupted. | 2750| 15100005 | Database or result set already closed. | 2751 2752以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 2753 2754| **错误码ID** | **错误信息** | 2755| ------------ | -------------------------------------------- | 2756| 14800047 | The WAL file size exceeds the default limit. | 2757 2758**示例：** 2759 2760```ts 2761import { BusinessError } from '@kit.BasicServicesKit'; 2762 2763try { 2764 let entries: distributedKVStore.Entry[] = []; 2765 for (let i = 0; i < 10; i++) { 2766 let key = 'batch_test_string_key'; 2767 let entry: distributedKVStore.Entry = { 2768 key: key + i, 2769 value: { 2770 type: distributedKVStore.ValueType.STRING, 2771 value: 'batch_test_string_value' 2772 } 2773 } 2774 entries.push(entry); 2775 } 2776 console.info(`entries: ${entries}`); 2777 kvStore.putBatch(entries, async (err: BusinessError) => { 2778 if (err != undefined) { 2779 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 2780 return; 2781 } 2782 console.info('Succeeded in putting Batch'); 2783 if (kvStore != null) { 2784 kvStore.getEntries('batch_test_string_key', (err: BusinessError, entries: distributedKVStore.Entry[]) => { 2785 if (err != undefined) { 2786 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 2787 } 2788 console.info('Succeeded in getting Entries'); 2789 console.info(`entries.length: ${entries.length}`); 2790 console.info(`entries[0]: ${entries[0]}`); 2791 }); 2792 } else { 2793 console.error('KvStore is null'); //后续示例代码与此处保持一致 2794 } 2795 }); 2796} catch (e) { 2797 let error = e as BusinessError; 2798 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message} `); 2799} 2800``` 2801 2802### putBatch 2803 2804putBatch(entries: Entry[]): Promise<void> 2805 2806批量插入键值对到SingleKVStore数据库中，使用Promise异步回调。 2807 2808**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2809 2810**参数：** 2811 2812| 参数名 | 类型 | 必填 | 说明 | 2813| ------- | ----------------- | ---- | ------------------------ | 2814| entries | [Entry](#entry)[] | 是 | 表示要批量插入的键值对。一个entries对象中允许的最大数据量为512M。 | 2815 2816**返回值：** 2817 2818| 类型 | 说明 | 2819| ------------------- | ------------------------- | 2820| Promise<void> | 无返回结果的Promise对象。 | 2821 2822**错误码：** 2823 2824以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 2825 2826| **错误码ID** | **错误信息** | 2827| ------------ | ---------------------------------------- | 2828| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 2829| 15100003 | Database corrupted. | 2830| 15100005 | Database or result set already closed. | 2831 2832以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 2833 2834| **错误码ID** | **错误信息** | 2835| ------------ | -------------------------------------------- | 2836| 14800047 | The WAL file size exceeds the default limit. | 2837 2838**示例：** 2839 2840```ts 2841import { BusinessError } from '@kit.BasicServicesKit'; 2842 2843try { 2844 let entries: distributedKVStore.Entry[] = []; 2845 for (let i = 0; i < 10; i++) { 2846 let key = 'batch_test_string_key'; 2847 let entry: distributedKVStore.Entry = { 2848 key: key + i, 2849 value: { 2850 type: distributedKVStore.ValueType.STRING, 2851 value: 'batch_test_string_value' 2852 } 2853 } 2854 entries.push(entry); 2855 } 2856 console.info(`entries: ${entries}`); 2857 kvStore.putBatch(entries).then(async () => { 2858 console.info('Succeeded in putting Batch'); 2859 if (kvStore != null) { 2860 kvStore.getEntries('batch_test_string_key').then((entries: distributedKVStore.Entry[]) => { 2861 console.info('Succeeded in getting Entries'); 2862 console.info(`PutBatch ${entries}`); 2863 }).catch((err: BusinessError) => { 2864 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 2865 }); 2866 } 2867 }).catch((err: BusinessError) => { 2868 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 2869 }); 2870} catch (e) { 2871 let error = e as BusinessError; 2872 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message} `); 2873} 2874``` 2875 2876### delete 2877 2878delete(key: string, callback: AsyncCallback<void>): void 2879 2880从数据库中删除指定键值的数据，使用callback异步回调。 2881 2882**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2883 2884**参数：** 2885 2886| 参数名 | 类型 | 必填 | 说明 | 2887| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 2888| key | string | 是 | 要删除数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2889| callback | AsyncCallback<void> | 是 | 回调函数。删除指定的数据成功，err为undefined，否则为错误对象。 | 2890 2891**错误码：** 2892 2893以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 2894 2895| **错误码ID** | **错误信息** | 2896| ------------ | -------------------------------------- | 2897| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2898| 15100003 | Database corrupted. | 2899| 15100005 | Database or result set already closed. | 2900 2901以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 2902 2903| **错误码ID** | **错误信息** | 2904| ------------ | -------------------------------------------- | 2905| 14800047 | The WAL file size exceeds the default limit. | 2906 2907**示例：** 2908 2909```ts 2910import { BusinessError } from '@kit.BasicServicesKit'; 2911 2912const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2913const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2914try { 2915 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err: BusinessError) => { 2916 if (err != undefined) { 2917 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2918 return; 2919 } 2920 console.info('Succeeded in putting'); 2921 if (kvStore != null) { 2922 kvStore.delete(KEY_TEST_STRING_ELEMENT, (err: BusinessError) => { 2923 if (err != undefined) { 2924 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 2925 return; 2926 } 2927 console.info('Succeeded in deleting'); 2928 }); 2929 } 2930 }); 2931} catch (e) { 2932 let error = e as BusinessError; 2933 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 2934} 2935``` 2936 2937### delete 2938 2939delete(key: string): Promise<void> 2940 2941从数据库中删除指定键值的数据，使用Promise异步回调。 2942 2943**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 2944 2945**参数：** 2946 2947| 参数名 | 类型 | 必填 | 说明 | 2948| ------ | -------- | ---- | ------------------------------------------------------------ | 2949| key | string | 是 | 要删除数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 2950 2951**返回值：** 2952 2953| 类型 | 说明 | 2954| ------------------- | ------------------------- | 2955| Promise<void> | 无返回结果的Promise对象。 | 2956 2957**错误码：** 2958 2959以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 2960 2961| **错误码ID** | **错误信息** | 2962| ------------ | ---------------------------------------- | 2963| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 2964| 15100003 | Database corrupted. | 2965| 15100005 | Database or result set already closed. | 2966 2967以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 2968 2969| **错误码ID** | **错误信息** | 2970| ------------ | -------------------------------------------- | 2971| 14800047 | The WAL file size exceeds the default limit. | 2972 2973**示例：** 2974 2975```ts 2976import { BusinessError } from '@kit.BasicServicesKit'; 2977 2978const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 2979const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 2980try { 2981 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 2982 console.info(`Succeeded in putting data`); 2983 if (kvStore != null) { 2984 kvStore.delete(KEY_TEST_STRING_ELEMENT).then(() => { 2985 console.info('Succeeded in deleting'); 2986 }).catch((err: BusinessError) => { 2987 console.error(`Failed to delete.code is ${err.code},message is ${err.message}`); 2988 }); 2989 } 2990 }).catch((err: BusinessError) => { 2991 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 2992 }); 2993} catch (e) { 2994 let error = e as BusinessError; 2995 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 2996} 2997``` 2998 2999### deleteBatch 3000 3001deleteBatch(keys: string[], callback: AsyncCallback<void>): void 3002 3003批量删除SingleKVStore数据库中的键值对，使用callback异步回调。 3004 3005**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3006 3007**参数：** 3008 3009| 参数名 | 类型 | 必填 | 说明 | 3010| -------- | ------------------------- | ---- | ------------------------ | 3011| keys | string[] | 是 | 表示要批量删除的键值对，不能为空。 | 3012| callback | AsyncCallback<void> | 是 | 回调函数。批量删除指定的数据成功，err为undefined，否则为错误对象。 | 3013 3014**错误码：** 3015 3016以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3017 3018| **错误码ID** | **错误信息** | 3019| ------------ | ---------------------------------------- | 3020| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 3021| 15100003 | Database corrupted. | 3022| 15100005 | Database or result set already closed. | 3023 3024以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 3025 3026| **错误码ID** | **错误信息** | 3027| ------------ | -------------------------------------------- | 3028| 14800047 | The WAL file size exceeds the default limit. | 3029 3030**示例：** 3031 3032```ts 3033import { BusinessError } from '@kit.BasicServicesKit'; 3034 3035try { 3036 let entries: distributedKVStore.Entry[] = []; 3037 let keys: string[] = []; 3038 for (let i = 0; i < 5; i++) { 3039 let key = 'batch_test_string_key'; 3040 let entry: distributedKVStore.Entry = { 3041 key: key + i, 3042 value: { 3043 type: distributedKVStore.ValueType.STRING, 3044 value: 'batch_test_string_value' 3045 } 3046 } 3047 entries.push(entry); 3048 keys.push(key + i); 3049 } 3050 console.info(`entries: ${entries}`); 3051 kvStore.putBatch(entries, async (err: BusinessError) => { 3052 if (err != undefined) { 3053 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 3054 return; 3055 } 3056 console.info('Succeeded in putting Batch'); 3057 if (kvStore != null) { 3058 kvStore.deleteBatch(keys, async (err: BusinessError) => { 3059 if (err != undefined) { 3060 console.error(`Failed to delete Batch.code is ${err.code},message is ${err.message}`); 3061 return; 3062 } 3063 console.info('Succeeded in deleting Batch'); 3064 }); 3065 } 3066 }); 3067} catch (e) { 3068 let error = e as BusinessError; 3069 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 3070} 3071``` 3072 3073### deleteBatch 3074 3075deleteBatch(keys: string[]): Promise<void> 3076 3077批量删除SingleKVStore数据库中的键值对，使用Promise异步回调。 3078 3079**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3080 3081**参数：** 3082 3083| 参数名 | 类型 | 必填 | 说明 | 3084| ------ | -------- | ---- | ------------------------ | 3085| keys | string[] | 是 | 表示要批量删除的键值对，不能为空。 | 3086 3087**返回值：** 3088 3089| 类型 | 说明 | 3090| ------------------- | ------------------------- | 3091| Promise<void> | 无返回结果的Promise对象。 | 3092 3093**错误码：** 3094 3095以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3096 3097| **错误码ID** | **错误信息** | 3098| ------------ | ---------------------------------------- | 3099| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 3100| 15100003 | Database corrupted. | 3101| 15100005 | Database or result set already closed. | 3102 3103以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 3104 3105| **错误码ID** | **错误信息** | 3106| ------------ | -------------------------------------------- | 3107| 14800047 | The WAL file size exceeds the default limit. | 3108 3109**示例：** 3110 3111```ts 3112import { BusinessError } from '@kit.BasicServicesKit'; 3113 3114try { 3115 let entries: distributedKVStore.Entry[] = []; 3116 let keys: string[] = []; 3117 for (let i = 0; i < 5; i++) { 3118 let key = 'batch_test_string_key'; 3119 let entry: distributedKVStore.Entry = { 3120 key: key + i, 3121 value: { 3122 type: distributedKVStore.ValueType.STRING, 3123 value: 'batch_test_string_value' 3124 } 3125 } 3126 entries.push(entry); 3127 keys.push(key + i); 3128 } 3129 console.info(`entries: ${entries}`); 3130 kvStore.putBatch(entries).then(async () => { 3131 console.info('Succeeded in putting Batch'); 3132 if (kvStore != null) { 3133 kvStore.deleteBatch(keys).then(() => { 3134 console.info('Succeeded in deleting Batch'); 3135 }).catch((err: BusinessError) => { 3136 console.error(`Failed to delete Batch.code is ${err.code},message is ${err.message}`); 3137 }); 3138 } 3139 }).catch((err: BusinessError) => { 3140 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 3141 }); 3142} catch (e) { 3143 let error = e as BusinessError; 3144 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 3145} 3146``` 3147 3148### removeDeviceData 3149 3150removeDeviceData(deviceId: string, callback: AsyncCallback<void>): void 3151 3152删除指定设备的数据，使用callback异步回调。 3153> **说明：** 3154> 3155> 其中deviceId为[DeviceBasicInfo](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#devicebasicinfo)中的networkId，通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 3156> deviceId具体获取方式请参考[sync接口示例](#sync) 3157 3158**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 3159 3160**参数：** 3161 3162| 参数名 | 类型 | 必填 | 说明 | 3163| -------- | ------------------------- | ---- | ---------------------- | 3164| deviceId | string | 是 | 表示要删除设备的networkId。 | 3165| callback | AsyncCallback<void> | 是 | 回调函数。删除指定设备的数据成功，err为undefined，否则为错误对象。 | 3166 3167**错误码：** 3168 3169以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3170 3171| **错误码ID** | **错误信息** | 3172| ------------ | -------------------------------------- | 3173| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 3174| 15100005 | Database or result set already closed. | 3175 3176**示例：** 3177 3178```ts 3179import { BusinessError } from '@kit.BasicServicesKit'; 3180 3181const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 3182const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 3183try { 3184 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async (err: BusinessError) => { 3185 console.info('Succeeded in putting data'); 3186 const deviceid = 'no_exist_device_id'; 3187 if (kvStore != null) { 3188 kvStore.removeDeviceData(deviceid, async (err: BusinessError) => { 3189 if (err == undefined) { 3190 console.info('succeeded in removing device data'); 3191 } else { 3192 console.error(`Failed to remove device data.code is ${err.code},message is ${err.message} `); 3193 if (kvStore != null) { 3194 kvStore.get(KEY_TEST_STRING_ELEMENT, async (err: BusinessError, data: boolean | string | number | Uint8Array) => { 3195 console.info('Succeeded in getting data'); 3196 }); 3197 } 3198 } 3199 }); 3200 } 3201 }); 3202} catch (e) { 3203 let error = e as BusinessError; 3204 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`) 3205} 3206``` 3207 3208### removeDeviceData 3209 3210removeDeviceData(deviceId: string): Promise<void> 3211 3212删除指定设备的数据，使用Promise异步回调。 3213> **说明：** 3214> 3215> 其中deviceId为[DeviceBasicInfo](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#devicebasicinfo)中的networkId，通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 3216> deviceId具体获取方式请参考[sync接口示例](#sync) 3217 3218**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 3219 3220**参数：** 3221 3222| 参数名 | 类型 | 必填 | 说明 | 3223| -------- | -------- | ---- | ---------------------- | 3224| deviceId | string | 是 | 表示要删除设备的networkId。 | 3225 3226**返回值：** 3227 3228| 类型 | 说明 | 3229| ------------------- | ------------------------- | 3230| Promise<void> | 无返回结果的Promise对象。 | 3231 3232**错误码：** 3233 3234以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3235 3236| **错误码ID** | **错误信息** | 3237| ------------ | -------------------------------------- | 3238| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 3239| 15100005 | Database or result set already closed. | 3240 3241**示例：** 3242 3243```ts 3244import { BusinessError } from '@kit.BasicServicesKit'; 3245 3246const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 3247const VALUE_TEST_STRING_ELEMENT = 'value-string-001'; 3248try { 3249 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 3250 console.info('Succeeded in putting data'); 3251 }).catch((err: BusinessError) => { 3252 console.error(`Failed to put data.code is ${err.code},message is ${err.message} `); 3253 }); 3254 const deviceid = 'no_exist_device_id'; 3255 kvStore.removeDeviceData(deviceid).then(() => { 3256 console.info('succeeded in removing device data'); 3257 }).catch((err: BusinessError) => { 3258 console.error(`Failed to remove device data.code is ${err.code},message is ${err.message} `); 3259 }); 3260 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data: boolean | string | number | Uint8Array) => { 3261 console.info('Succeeded in getting data'); 3262 }).catch((err: BusinessError) => { 3263 console.error(`Failed to get data.code is ${err.code},message is ${err.message} `); 3264 }); 3265} catch (e) { 3266 let error = e as BusinessError; 3267 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`) 3268} 3269``` 3270 3271### get 3272 3273get(key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void 3274 3275获取指定键的值，使用callback异步回调。 3276 3277**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3278 3279**参数：** 3280 3281| 参数名 | 类型 | 必填 | 说明 | 3282| ----- | ------ | ---- | ----------------------- | 3283| key |string | 是 |要查询数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3284| callback |AsyncCallback<boolean \| string \| number \| Uint8Array> | 是 |回调函数。返回获取查询的值。 | 3285 3286**错误码：** 3287 3288以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3289 3290| **错误码ID** | **错误信息** | 3291| ------------ | -------------------------------------- | 3292| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 3293| 15100003 | Database corrupted. | 3294| 15100004 | Not found. | 3295| 15100005 | Database or result set already closed. | 3296 3297**示例：** 3298 3299```ts 3300import { BusinessError } from '@kit.BasicServicesKit'; 3301 3302 3303const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 3304const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 3305try { 3306 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err: BusinessError) => { 3307 if (err != undefined) { 3308 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 3309 return; 3310 } 3311 console.info("Succeeded in putting"); 3312 if (kvStore != null) { 3313 kvStore.get(KEY_TEST_STRING_ELEMENT, (err: BusinessError, data: boolean | string | number | Uint8Array) => { 3314 if (err != undefined) { 3315 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 3316 return; 3317 } 3318 console.info(`Succeeded in getting data.data=${data}`); 3319 }); 3320 } 3321 }); 3322} catch (e) { 3323 let error = e as BusinessError; 3324 console.error(`Failed to get.code is ${error.code},message is ${error.message}`); 3325} 3326``` 3327 3328### get 3329 3330get(key: string): Promise<boolean | string | number | Uint8Array> 3331 3332获取指定键的值，使用Promise异步回调。 3333 3334**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3335 3336**参数：** 3337 3338| 参数名 | 类型 | 必填 | 说明 | 3339| ------ | -------- | ---- | ------------------------------------------------------------ | 3340| key | string | 是 | 要查询数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 3341 3342**返回值：** 3343 3344| 类型 | 说明 | 3345| ------ | ------- | 3346|Promise<boolean \| string \| number \| Uint8Array> |Promise对象。返回获取查询的值。| 3347 3348**错误码：** 3349 3350以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3351 3352| **错误码ID** | **错误信息** | 3353| ------------ | -------------------------------------- | 3354| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 3355| 15100003 | Database corrupted. | 3356| 15100004 | Not found. | 3357| 15100005 | Database or result set already closed. | 3358 3359**示例：** 3360 3361```ts 3362import { BusinessError } from '@kit.BasicServicesKit'; 3363 3364 3365const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 3366const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 3367try { 3368 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 3369 console.info(`Succeeded in putting data`); 3370 if (kvStore != null) { 3371 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data: boolean | string | number | Uint8Array) => { 3372 console.info(`Succeeded in getting data.data=${data}`); 3373 }).catch((err: BusinessError) => { 3374 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 3375 }); 3376 } 3377 }).catch((err: BusinessError) => { 3378 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 3379 }); 3380} catch (e) { 3381 let error = e as BusinessError; 3382 console.error(`Failed to get.code is ${error.code},message is ${error.message}`); 3383} 3384``` 3385 3386### getEntries 3387 3388getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void 3389 3390获取匹配指定键前缀的所有键值对，使用callback异步回调。 3391 3392**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3393 3394**参数：** 3395 3396| 参数名 | 类型 | 必填 | 说明 | 3397| --------- | -------------------------------------- | ---- | ---------------------------------------- | 3398| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 3399| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回匹配指定前缀的键值对列表。 | 3400 3401**错误码：** 3402 3403以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3404 3405| **错误码ID** | **错误信息** | 3406| ------------ | -------------------------------------- | 3407| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3408| 15100003 | Database corrupted. | 3409| 15100005 | Database or result set already closed. | 3410 3411**示例：** 3412 3413```ts 3414import { BusinessError } from '@kit.BasicServicesKit'; 3415 3416try { 3417 let entries: distributedKVStore.Entry[] = []; 3418 for (let i = 0; i < 10; i++) { 3419 let key = 'batch_test_string_key'; 3420 let entry: distributedKVStore.Entry = { 3421 key: key + i, 3422 value: { 3423 type: distributedKVStore.ValueType.STRING, 3424 value: 'batch_test_string_value' 3425 } 3426 } 3427 entries.push(entry); 3428 } 3429 console.info(`entries: ${entries}`); 3430 kvStore.putBatch(entries, async (err: BusinessError) => { 3431 if (err != undefined) { 3432 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 3433 return; 3434 } 3435 console.info('Succeeded in putting Batch'); 3436 if (kvStore != null) { 3437 kvStore.getEntries('batch_test_string_key', (err: BusinessError, entries: distributedKVStore.Entry[]) => { 3438 if (err != undefined) { 3439 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3440 return; 3441 } 3442 console.info('Succeeded in getting Entries'); 3443 console.info(`entries.length: ${entries.length}`); 3444 console.info(`entries[0]: ${entries[0]}`); 3445 }); 3446 } 3447 }); 3448} catch (e) { 3449 let error = e as BusinessError; 3450 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message} `); 3451} 3452``` 3453 3454### getEntries 3455 3456getEntries(keyPrefix: string): Promise<Entry[]> 3457 3458获取匹配指定键前缀的所有键值对，使用Promise异步回调。 3459 3460**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3461 3462**参数：** 3463 3464| 参数名 | 类型 | 必填 | 说明 | 3465| --------- | -------- | ---- | -------------------- | 3466| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 3467 3468**返回值：** 3469 3470| 类型 | 说明 | 3471| -------------------------------- | ------------------------------------------- | 3472| Promise<[Entry](#entry)[]> | Promise对象。返回匹配指定前缀的键值对列表。 | 3473 3474**错误码：** 3475 3476以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3477 3478| **错误码ID** | **错误信息** | 3479| ------------ | -------------------------------------- | 3480| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3481| 15100003 | Database corrupted. | 3482| 15100005 | Database or result set already closed. | 3483 3484**示例：** 3485 3486```ts 3487import { BusinessError } from '@kit.BasicServicesKit'; 3488 3489 3490try { 3491 let entries: distributedKVStore.Entry[] = []; 3492 for (let i = 0; i < 10; i++) { 3493 let key = 'batch_test_string_key'; 3494 let entry: distributedKVStore.Entry = { 3495 key: key + i, 3496 value: { 3497 type: distributedKVStore.ValueType.STRING, 3498 value: 'batch_test_string_value' 3499 } 3500 } 3501 entries.push(entry); 3502 } 3503 console.info(`entries: ${entries}`); 3504 kvStore.putBatch(entries).then(async () => { 3505 console.info('Succeeded in putting Batch'); 3506 if (kvStore != null) { 3507 kvStore.getEntries('batch_test_string_key').then((entries: distributedKVStore.Entry[]) => { 3508 console.info('Succeeded in getting Entries'); 3509 console.info(`PutBatch ${entries}`); 3510 }).catch((err: BusinessError) => { 3511 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3512 }); 3513 } 3514 }).catch((err: BusinessError) => { 3515 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 3516 }); 3517} catch (e) { 3518 let error = e as BusinessError; 3519 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message} `); 3520} 3521``` 3522 3523### getEntries 3524 3525getEntries(query: Query, callback: AsyncCallback<Entry[]>): void 3526 3527获取与指定Query对象匹配的键值对列表，使用callback异步回调。 3528 3529**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3530 3531**参数：** 3532 3533| 参数名 | 类型 | 必填 | 说明 | 3534| -------- | -------------------------------------- | ---- | ----------------------------------------------- | 3535| query | [Query](#query) | 是 | 表示要匹配的键前缀。 | 3536| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定Query对象匹配的键值对列表。 | 3537 3538**错误码：** 3539 3540以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3541 3542| **错误码ID** | **错误信息** | 3543| ------------ | -------------------------------------- | 3544| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3545| 15100003 | Database corrupted. | 3546| 15100005 | Database or result set already closed. | 3547 3548**示例：** 3549 3550```ts 3551import { BusinessError } from '@kit.BasicServicesKit'; 3552 3553try { 3554 let arr = new Uint8Array([21, 31]); 3555 let entries: distributedKVStore.Entry[] = []; 3556 for (let i = 0; i < 10; i++) { 3557 let key = 'batch_test_bool_key'; 3558 let entry: distributedKVStore.Entry = { 3559 key: key + i, 3560 value: { 3561 type: distributedKVStore.ValueType.BYTE_ARRAY, 3562 value: arr 3563 } 3564 } 3565 entries.push(entry); 3566 } 3567 console.info(`entries: {entries}`); 3568 kvStore.putBatch(entries, async (err: BusinessError) => { 3569 console.info('Succeeded in putting Batch'); 3570 const query = new distributedKVStore.Query(); 3571 query.prefixKey("batch_test"); 3572 if (kvStore != null) { 3573 kvStore.getEntries(query, (err: BusinessError, entries: distributedKVStore.Entry[]) => { 3574 if (err != undefined) { 3575 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3576 return; 3577 } 3578 console.info('Succeeded in getting Entries'); 3579 console.info(`entries.length: ${entries.length}`); 3580 console.info(`entries[0]: ${entries[0]}`); 3581 }); 3582 } 3583 }); 3584} catch (e) { 3585 let error = e as BusinessError; 3586 console.error(`Failed to get Entries.code is ${error.code},message is ${error.message}`); 3587} 3588``` 3589 3590### getEntries 3591 3592getEntries(query: Query): Promise<Entry[]> 3593 3594获取与指定Query对象匹配的键值对列表，使用Promise异步回调。 3595 3596**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3597 3598**参数：** 3599 3600| 参数名 | 类型 | 必填 | 说明 | 3601| ------ | -------------- | ---- | -------------- | 3602| query | [Query](#query) | 是 | 表示查询对象。 | 3603 3604**返回值：** 3605 3606| 类型 | 说明 | 3607| -------------------------------- | -------------------------------------------------- | 3608| Promise<[Entry](#entry)[]> | Promise对象。返回与指定Query对象匹配的键值对列表。 | 3609 3610**错误码：** 3611 3612以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3613 3614| **错误码ID** | **错误信息** | 3615| ------------ | -------------------------------------- | 3616| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3617| 15100003 | Database corrupted. | 3618| 15100005 | Database or result set already closed. | 3619 3620**示例：** 3621 3622```ts 3623import { BusinessError } from '@kit.BasicServicesKit'; 3624 3625try { 3626 let arr = new Uint8Array([21, 31]); 3627 let entries: distributedKVStore.Entry[] = []; 3628 for (let i = 0; i < 10; i++) { 3629 let key = 'batch_test_bool_key'; 3630 let entry: distributedKVStore.Entry = { 3631 key: key + i, 3632 value: { 3633 type: distributedKVStore.ValueType.BYTE_ARRAY, 3634 value: arr 3635 } 3636 } 3637 entries.push(entry); 3638 } 3639 console.info(`entries: {entries}`); 3640 kvStore.putBatch(entries).then(async () => { 3641 console.info('Succeeded in putting Batch'); 3642 const query = new distributedKVStore.Query(); 3643 query.prefixKey("batch_test"); 3644 if (kvStore != null) { 3645 kvStore.getEntries(query).then((entries: distributedKVStore.Entry[]) => { 3646 console.info('Succeeded in getting Entries'); 3647 }).catch((err: BusinessError) => { 3648 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 3649 }); 3650 } 3651 }).catch((err: BusinessError) => { 3652 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`) 3653 }); 3654 console.info('Succeeded in getting Entries'); 3655} catch (e) { 3656 let error = e as BusinessError; 3657 console.error(`Failed to get Entries.code is ${error.code},message is ${error.message}`); 3658} 3659``` 3660 3661### getResultSet 3662 3663getResultSet(keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 3664 3665从SingleKVStore数据库中获取具有指定前缀的结果集，使用callback异步回调。 3666 3667**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3668 3669**参数：** 3670 3671| 参数名 | 类型 | 必填 | 说明 | 3672| --------- | ---------------------------------------------------------- | ---- | ------------------------------------ | 3673| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 3674| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回具有指定前缀的结果集。 | 3675 3676**错误码：** 3677 3678以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3679 3680| **错误码ID** | **错误信息** | 3681| ------------ | -------------------------------------- | 3682| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 3683| 15100001 | Over max limits. | 3684| 15100003 | Database corrupted. | 3685| 15100005 | Database or result set already closed. | 3686 3687 3688**示例：** 3689 3690```ts 3691import { BusinessError } from '@kit.BasicServicesKit'; 3692 3693try { 3694 let resultSet: distributedKVStore.KVStoreResultSet; 3695 let entries: distributedKVStore.Entry[] = []; 3696 for (let i = 0; i < 10; i++) { 3697 let key = 'batch_test_string_key'; 3698 let entry: distributedKVStore.Entry = { 3699 key: key + i, 3700 value: { 3701 type: distributedKVStore.ValueType.STRING, 3702 value: 'batch_test_string_value' 3703 } 3704 } 3705 entries.push(entry); 3706 } 3707 kvStore.putBatch(entries, async (err: BusinessError) => { 3708 if (err != undefined) { 3709 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3710 return; 3711 } 3712 console.info('Succeeded in putting batch'); 3713 if (kvStore != null) { 3714 kvStore.getResultSet('batch_test_string_key', async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 3715 if (err != undefined) { 3716 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3717 return; 3718 } 3719 console.info('Succeeded in getting result set'); 3720 resultSet = result; 3721 if (kvStore != null) { 3722 kvStore.closeResultSet(resultSet, (err :BusinessError) => { 3723 if (err != undefined) { 3724 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3725 return; 3726 } 3727 console.info('Succeeded in closing result set'); 3728 }); 3729 } 3730 }); 3731 } 3732 }); 3733} catch (e) { 3734 let error = e as BusinessError; 3735 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 3736} 3737``` 3738 3739### getResultSet 3740 3741getResultSet(keyPrefix: string): Promise<KVStoreResultSet> 3742 3743从SingleKVStore数据库中获取具有指定前缀的结果集，使用Promise异步回调。 3744 3745**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3746 3747**参数：** 3748 3749| 参数名 | 类型 | 必填 | 说明 | 3750| --------- | -------- | ---- | -------------------- | 3751| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 3752 3753**返回值：** 3754 3755| 类型 | 说明 | 3756| ---------------------------------------------------- | --------------------------------------- | 3757| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回具有指定前缀的结果集。 | 3758 3759**错误码：** 3760 3761以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3762 3763| **错误码ID** | **错误信息** | 3764| ------------ | -------------------------------------- | 3765| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3766| 15100001 | Over max limits. | 3767| 15100003 | Database corrupted. | 3768| 15100005 | Database or result set already closed. | 3769 3770**示例：** 3771 3772```ts 3773import { BusinessError } from '@kit.BasicServicesKit'; 3774 3775try { 3776 let resultSet: distributedKVStore.KVStoreResultSet; 3777 let entries: distributedKVStore.Entry[] = []; 3778 for (let i = 0; i < 10; i++) { 3779 let key = 'batch_test_string_key'; 3780 let entry: distributedKVStore.Entry = { 3781 key: key + i, 3782 value: { 3783 type: distributedKVStore.ValueType.STRING, 3784 value: 'batch_test_string_value' 3785 } 3786 } 3787 entries.push(entry); 3788 } 3789 kvStore.putBatch(entries).then(async () => { 3790 console.info('Succeeded in putting batch'); 3791 }).catch((err: BusinessError) => { 3792 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3793 }); 3794 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 3795 console.info('Succeeded in getting result set'); 3796 resultSet = result; 3797 if (kvStore != null) { 3798 kvStore.closeResultSet(resultSet).then(() => { 3799 console.info('Succeeded in closing result set'); 3800 }).catch((err: BusinessError) => { 3801 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3802 }); 3803 } 3804 }).catch((err: BusinessError) => { 3805 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3806 }); 3807} catch (e) { 3808 let error = e as BusinessError; 3809 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 3810} 3811``` 3812 3813### getResultSet 3814 3815getResultSet(query: Query, callback: AsyncCallback<KVStoreResultSet>): void 3816 3817获取与指定Query对象匹配的KVStoreResultSet对象，使用callback异步回调。 3818 3819**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3820 3821**参数：** 3822 3823| 参数名 | 类型 | 必填 | 说明 | 3824| -------- | ---------------------------------------------------------- | ---- | --------------------------------------------------------- | 3825| query | Query | 是 | 表示查询对象。 | 3826| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Query对象匹配的KVStoreResultSet对象。 | 3827 3828**错误码：** 3829 3830以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3831 3832| **错误码ID** | **错误信息** | 3833| ------------ | -------------------------------------- | 3834| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3835| 15100001 | Over max limits. | 3836| 15100003 | Database corrupted. | 3837| 15100005 | Database or result set already closed. | 3838 3839**示例：** 3840 3841```ts 3842import { BusinessError } from '@kit.BasicServicesKit'; 3843 3844try { 3845 let resultSet: distributedKVStore.KVStoreResultSet; 3846 let entries: distributedKVStore.Entry[] = []; 3847 for (let i = 0; i < 10; i++) { 3848 let key = 'batch_test_string_key'; 3849 let entry: distributedKVStore.Entry = { 3850 key: key + i, 3851 value: { 3852 type: distributedKVStore.ValueType.STRING, 3853 value: 'batch_test_string_value' 3854 } 3855 } 3856 entries.push(entry); 3857 } 3858 kvStore.putBatch(entries, async (err: BusinessError) => { 3859 if (err != undefined) { 3860 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3861 return; 3862 } 3863 console.info('Succeeded in putting batch'); 3864 const query = new distributedKVStore.Query(); 3865 query.prefixKey("batch_test"); 3866 if (kvStore != null) { 3867 kvStore.getResultSet(query, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 3868 if (err != undefined) { 3869 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3870 return; 3871 } 3872 console.info('Succeeded in getting result set'); 3873 }); 3874 } 3875 }); 3876} catch (e) { 3877 let error = e as BusinessError; 3878 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 3879} 3880``` 3881 3882### getResultSet 3883 3884getResultSet(query: Query): Promise<KVStoreResultSet> 3885 3886获取与指定Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 3887 3888**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3889 3890**参数：** 3891 3892| 参数名 | 类型 | 必填 | 说明 | 3893| ------ | -------------- | ---- | -------------- | 3894| query | [Query](#query) | 是 | 表示查询对象。 | 3895 3896**返回值：** 3897 3898| 类型 | 说明 | 3899| ---------------------------------------------------- | ------------------------------------------------------------ | 3900| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。获取与指定Query对象匹配的KVStoreResultSet对象。 | 3901 3902**错误码：** 3903 3904以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 3905 3906| **错误码ID** | **错误信息** | 3907| ------------ | -------------------------------------- | 3908| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3909| 15100001 | Over max limits. | 3910| 15100003 | Database corrupted. | 3911| 15100005 | Database or result set already closed. | 3912 3913**示例：** 3914 3915```ts 3916import { BusinessError } from '@kit.BasicServicesKit'; 3917 3918try { 3919 let resultSet: distributedKVStore.KVStoreResultSet; 3920 let entries: distributedKVStore.Entry[] = []; 3921 for (let i = 0; i < 10; i++) { 3922 let key = 'batch_test_string_key'; 3923 let entry: distributedKVStore.Entry = { 3924 key: key + i, 3925 value: { 3926 type: distributedKVStore.ValueType.STRING, 3927 value: 'batch_test_string_value' 3928 } 3929 } 3930 entries.push(entry); 3931 } 3932 kvStore.putBatch(entries).then(async () => { 3933 console.info('Succeeded in putting batch'); 3934 }).catch((err: BusinessError) => { 3935 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 3936 }); 3937 const query = new distributedKVStore.Query(); 3938 query.prefixKey("batch_test"); 3939 kvStore.getResultSet(query).then((result: distributedKVStore.KVStoreResultSet) => { 3940 console.info('Succeeded in getting result set'); 3941 resultSet = result; 3942 }).catch((err: BusinessError) => { 3943 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3944 }); 3945} catch (e) { 3946 let error = e as BusinessError; 3947 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 3948} 3949``` 3950 3951### closeResultSet 3952 3953closeResultSet(resultSet: KVStoreResultSet, callback: AsyncCallback<void>): void 3954 3955关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象，使用callback异步回调。 3956 3957**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 3958 3959**参数：** 3960 3961| 参数名 | 类型 | 必填 | 说明 | 3962| --------- | ------------------------------------- | ---- | ---------------------------------- | 3963| resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | 3964| callback | AsyncCallback<void> | 是 | 回调函数。关闭KVStoreResultSet对象成功，err为undefined，否则为错误对象。 | 3965 3966**错误码：** 3967 3968以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 3969 3970| **错误码ID** | **错误信息** | 3971| ------------ | -------------------------------------- | 3972| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 3973 3974**示例：** 3975 3976```ts 3977import { BusinessError } from '@kit.BasicServicesKit'; 3978 3979let resultSet: distributedKVStore.KVStoreResultSet; 3980try { 3981 kvStore.getResultSet('batch_test_string_key', async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 3982 if (err != undefined) { 3983 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 3984 return; 3985 } 3986 console.info('Succeeded in getting result set'); 3987 resultSet = result; 3988 if (kvStore != null) { 3989 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 3990 if (err != undefined) { 3991 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 3992 return; 3993 } 3994 console.info('Succeeded in closing result set'); 3995 }) 3996 } 3997 }); 3998} catch (e) { 3999 let error = e as BusinessError; 4000 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4001} 4002 4003``` 4004 4005### closeResultSet 4006 4007closeResultSet(resultSet: KVStoreResultSet): Promise<void> 4008 4009关闭由[SingleKvStore.getResultSet](#getresultset-1)返回的KVStoreResultSet对象，使用Promise异步回调。 4010 4011**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4012 4013**参数：** 4014 4015| 参数名 | 类型 | 必填 | 说明 | 4016| --------- | ------------------------------------- | ---- | ---------------------------------- | 4017| resultSet | [KVStoreResultSet](#kvstoreresultset) | 是 | 表示要关闭的KVStoreResultSet对象。 | 4018 4019**返回值：** 4020 4021| 类型 | 说明 | 4022| ------------------- | ------------------------- | 4023| Promise<void> | 无返回结果的Promise对象。 | 4024 4025**错误码：** 4026 4027以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4028 4029| **错误码ID** | **错误信息** | 4030| ------------ | -------------------------------------- | 4031| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 4032 4033**示例：** 4034 4035```ts 4036import { BusinessError } from '@kit.BasicServicesKit'; 4037 4038let resultSet: distributedKVStore.KVStoreResultSet; 4039try { 4040 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 4041 console.info('Succeeded in getting result set'); 4042 resultSet = result; 4043 if (kvStore != null) { 4044 kvStore.closeResultSet(resultSet).then(() => { 4045 console.info('Succeeded in closing result set'); 4046 }).catch((err: BusinessError) => { 4047 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 4048 }); 4049 } 4050 }).catch((err: BusinessError) => { 4051 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 4052 }); 4053 4054} catch (e) { 4055 let error = e as BusinessError; 4056 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4057} 4058``` 4059 4060### getResultSize 4061 4062getResultSize(query: Query, callback: AsyncCallback<number>): void 4063 4064获取与指定Query对象匹配的结果数，使用callback异步回调。 4065 4066**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4067 4068**参数：** 4069 4070| 参数名 | 类型 | 必填 | 说明 | 4071| -------- | --------------------------- | ---- | ------------------------------------------- | 4072| query | [Query](#query) | 是 | 表示查询对象。 | 4073| callback | AsyncCallback<number> | 是 | 回调函数。返回与指定Query对象匹配的结果数。 | 4074 4075**错误码：** 4076 4077以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 4078 4079| **错误码ID** | **错误信息** | 4080| ------------ | -------------------------------------- | 4081| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 4082| 15100003 | Database corrupted. | 4083| 15100005 | Database or result set already closed. | 4084 4085**示例：** 4086 4087```ts 4088import { BusinessError } from '@kit.BasicServicesKit'; 4089 4090try { 4091 let entries: distributedKVStore.Entry[] = []; 4092 for (let i = 0; i < 10; i++) { 4093 let key = 'batch_test_string_key'; 4094 let entry: distributedKVStore.Entry = { 4095 key: key + i, 4096 value: { 4097 type: distributedKVStore.ValueType.STRING, 4098 value: 'batch_test_string_value' 4099 } 4100 } 4101 entries.push(entry); 4102 } 4103 kvStore.putBatch(entries, (err: BusinessError) => { 4104 console.info('Succeeded in putting batch'); 4105 const query = new distributedKVStore.Query(); 4106 query.prefixKey("batch_test"); 4107 if (kvStore != null) { 4108 kvStore.getResultSize(query, (err: BusinessError, resultSize: number) => { 4109 if (err != undefined) { 4110 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 4111 return; 4112 } 4113 console.info('Succeeded in getting result set size'); 4114 }); 4115 } 4116 }); 4117} catch (e) { 4118 let error = e as BusinessError; 4119 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4120} 4121``` 4122 4123### getResultSize 4124 4125getResultSize(query: Query): Promise<number> 4126 4127获取与指定Query对象匹配的结果数，使用Promise异步回调。 4128 4129**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4130 4131**参数：** 4132 4133| 参数名 | 类型 | 必填 | 说明 | 4134| ------ | -------------- | ---- | -------------- | 4135| query | [Query](#query) | 是 | 表示查询对象。 | 4136 4137**返回值：** 4138 4139| 类型 | 说明 | 4140| --------------------- | ----------------------------------------------- | 4141| Promise<number> | Promise对象。获取与指定Query对象匹配的结果数。 | 4142 4143**错误码：** 4144 4145以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 4146 4147| **错误码ID** | **错误信息** | 4148| ------------ | -------------------------------------- | 4149| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 4150| 15100003 | Database corrupted. | 4151| 15100005 | Database or result set already closed. | 4152 4153**示例：** 4154 4155```ts 4156import { BusinessError } from '@kit.BasicServicesKit'; 4157 4158try { 4159 let entries: distributedKVStore.Entry[] = []; 4160 for (let i = 0; i < 10; i++) { 4161 let key = 'batch_test_string_key'; 4162 let entry: distributedKVStore.Entry = { 4163 key: key + i, 4164 value: { 4165 type: distributedKVStore.ValueType.STRING, 4166 value: 'batch_test_string_value' 4167 } 4168 } 4169 entries.push(entry); 4170 } 4171 kvStore.putBatch(entries).then(async () => { 4172 console.info('Succeeded in putting batch'); 4173 }).catch((err: BusinessError) => { 4174 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 4175 }); 4176 const query = new distributedKVStore.Query(); 4177 query.prefixKey("batch_test"); 4178 kvStore.getResultSize(query).then((resultSize: number) => { 4179 console.info('Succeeded in getting result set size'); 4180 }).catch((err: BusinessError) => { 4181 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 4182 }); 4183} catch (e) { 4184 let error = e as BusinessError; 4185 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4186} 4187``` 4188 4189### backup 4190 4191backup(file:string, callback: AsyncCallback<void>):void 4192 4193以指定名称备份数据库，使用callback异步回调。 4194 4195**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4196 4197**参数：** 4198 4199| 参数名 | 类型 | 必填 | 说明 | 4200| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 4201| file | string | 是 | 备份数据库的指定名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4202| callback | AsyncCallback<void> | 是 | 回调函数。当以指定名称备份数据库成功，err为undefined，否则为错误对象。 | 4203 4204**错误码：** 4205 4206以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 4207 4208| **错误码ID** | **错误信息** | 4209| ------------ | -------------------------------------- | 4210| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 4211| 15100005 | Database or result set already closed. | 4212 4213**示例：** 4214 4215```ts 4216import { BusinessError } from '@kit.BasicServicesKit'; 4217 4218let backupFile = "BK001"; 4219try { 4220 kvStore.backup(backupFile, (err: BusinessError) => { 4221 if (err) { 4222 console.error(`Failed to backup.code is ${err.code},message is ${err.message} `); 4223 } else { 4224 console.info(`Succeeded in backupping data`); 4225 } 4226 }); 4227} catch (e) { 4228 let error = e as BusinessError; 4229 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4230} 4231``` 4232 4233### backup 4234 4235backup(file:string): Promise<void> 4236 4237以指定名称备份数据库，使用Promise异步回调。 4238 4239**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4240 4241**参数：** 4242 4243| 参数名 | 类型 | 必填 | 说明 | 4244| ------ | -------- | ---- | ------------------------------------------------------------ | 4245| file | string | 是 | 备份数据库的指定名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4246 4247**返回值：** 4248 4249| 类型 | 说明 | 4250| ------------------- | ------------------------- | 4251| Promise<void> | 无返回结果的Promise对象。 | 4252 4253**错误码：** 4254 4255以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 4256 4257| **错误码ID** | **错误信息** | 4258| ------------ | -------------------------------------- | 4259| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 4260| 15100005 | Database or result set already closed. | 4261 4262**示例：** 4263 4264```ts 4265import { BusinessError } from '@kit.BasicServicesKit'; 4266 4267let backupFile = "BK001"; 4268try { 4269 kvStore.backup(backupFile).then(() => { 4270 console.info(`Succeeded in backupping data`); 4271 }).catch((err: BusinessError) => { 4272 console.error(`Failed to backup.code is ${err.code},message is ${err.message}`); 4273 }); 4274} catch (e) { 4275 let error = e as BusinessError; 4276 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4277} 4278``` 4279 4280### restore 4281 4282restore(file:string, callback: AsyncCallback<void>):void 4283 4284从指定的数据库文件恢复数据库，使用callback异步回调。 4285 4286**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4287 4288**参数：** 4289 4290| 参数名 | 类型 | 必填 | 说明 | 4291| -------- | ------------------------- | ---- | ------------------------------------------------------------ | 4292| file | string | 是 | 指定的数据库文件名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4293| callback | AsyncCallback<void> | 是 | 回调函数。当从指定的数据库文件恢复数据库成功，err为undefined，否则为错误对象。 | 4294 4295**错误码：** 4296 4297以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 4298 4299| **错误码ID** | **错误信息** | 4300| ------------ | -------------------------------------- | 4301| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 4302| 15100005 | Database or result set already closed. | 4303 4304**示例：** 4305 4306```ts 4307import { BusinessError } from '@kit.BasicServicesKit'; 4308 4309let backupFile = "BK001"; 4310try { 4311 kvStore.restore(backupFile, (err: BusinessError) => { 4312 if (err) { 4313 console.error(`Failed to restore.code is ${err.code},message is ${err.message}`); 4314 } else { 4315 console.info(`Succeeded in restoring data`); 4316 } 4317 }); 4318} catch (e) { 4319 let error = e as BusinessError; 4320 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4321} 4322``` 4323 4324### restore 4325 4326restore(file:string): Promise<void> 4327 4328从指定的数据库文件恢复数据库，使用Promise异步回调。 4329 4330**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4331 4332**参数：** 4333 4334| 参数名 | 类型 | 必填 | 说明 | 4335| ------ | -------- | ---- | ------------------------------------------------------------ | 4336| file | string | 是 | 指定的数据库文件名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4337 4338**返回值：** 4339 4340| 类型 | 说明 | 4341| ------------------- | ------------------------- | 4342| Promise<void> | 无返回结果的Promise对象。 | 4343 4344**错误码：** 4345 4346以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 4347 4348| **错误码ID** | **错误信息** | 4349| ------------ | -------------------------------------- | 4350| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 4351| 15100005 | Database or result set already closed. | 4352 4353**示例：** 4354 4355```ts 4356import { BusinessError } from '@kit.BasicServicesKit'; 4357 4358let backupFile = "BK001"; 4359try { 4360 kvStore.restore(backupFile).then(() => { 4361 console.info(`Succeeded in restoring data`); 4362 }).catch((err: BusinessError) => { 4363 console.error(`Failed to restore.code is ${err.code},message is ${err.message}`); 4364 }); 4365} catch (e) { 4366 let error = e as BusinessError; 4367 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4368} 4369``` 4370 4371### deleteBackup 4372 4373deleteBackup(files:Array<string>, callback: AsyncCallback<Array<[string, number]>>):void 4374 4375根据指定名称删除备份文件，使用callback异步回调。 4376 4377**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4378 4379**参数：** 4380 4381| 参数名 | 类型 | 必填 | 说明 | 4382| -------- | -------------------------------------------------- | ---- | ------------------------------------------------------------ | 4383| files | Array<string> | 是 | 删除备份文件所指定的名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4384| callback | AsyncCallback<Array<[string, number]>> | 是 | 回调函数，返回删除备份的文件名及其处理结果。 | 4385 4386**错误码：** 4387 4388以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4389 4390| **错误码ID** | **错误信息** | 4391| ------------ | -------------------------------------- | 4392| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 4393 4394**示例：** 4395 4396```ts 4397import { BusinessError } from '@kit.BasicServicesKit'; 4398 4399let files = ["BK001", "BK002"]; 4400try { 4401 kvStore.deleteBackup(files, (err: BusinessError, data: [string, number][]) => { 4402 if (err) { 4403 console.error(`Failed to delete Backup.code is ${err.code},message is ${err.message}`); 4404 } else { 4405 console.info(`Succeed in deleting Backup.data=${data}`); 4406 } 4407 }); 4408} catch (e) { 4409 let error = e as BusinessError; 4410 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4411} 4412``` 4413 4414### deleteBackup 4415 4416deleteBackup(files:Array<string>): Promise<Array<[string, number]>> 4417 4418根据指定名称删除备份文件，使用Promise异步回调。 4419 4420**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4421 4422**参数：** 4423 4424| 参数名 | 类型 | 必填 | 说明 | 4425| ------ | ------------------- | ---- | ------------------------------------------------------------ | 4426| files | Array<string> | 是 | 删除备份文件所指定的名称，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 4427 4428**返回值：** 4429 4430| 类型 | 说明 | 4431| -------------------------------------------- | ----------------------------------------------- | 4432| Promise<Array<[string, number]>> | Promise对象，返回删除备份的文件名及其处理结果。 | 4433 4434**错误码：** 4435 4436以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4437 4438| **错误码ID** | **错误信息** | 4439| ------------ | -------------------------------------- | 4440| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Parameter verification failed. | 4441 4442**示例：** 4443 4444```ts 4445import { BusinessError } from '@kit.BasicServicesKit'; 4446 4447let files = ["BK001", "BK002"]; 4448try { 4449 kvStore.deleteBackup(files).then((data: [string, number][]) => { 4450 console.info(`Succeed in deleting Backup.data=${data}`); 4451 }).catch((err: BusinessError) => { 4452 console.error(`Failed to delete Backup.code is ${err.code},message is ${err.message}`); 4453 }) 4454} catch (e) { 4455 let error = e as BusinessError; 4456 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4457} 4458``` 4459 4460### startTransaction 4461 4462startTransaction(callback: AsyncCallback<void>): void 4463 4464启动SingleKVStore数据库中的事务，使用callback异步回调。 4465 4466**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4467 4468**参数：** 4469 4470| 参数名 | 类型 | 必填 | 说明 | 4471| -------- | ------------------------- | ---- | ---------- | 4472| callback | AsyncCallback<void> | 是 | 回调函数。启动SingleKVStore数据库中的事务成功，err为undefined，否则为错误对象。 | 4473 4474**错误码：** 4475 4476以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 4477 4478| **错误码ID** | **错误信息** | 4479| ------------ | ---------------------------------------- | 4480| 15100005 | Database or result set already closed. | 4481 4482以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 4483 4484| **错误码ID** | **错误信息** | 4485| ------------ | -------------------------------------------- | 4486| 14800047 | The WAL file size exceeds the default limit. | 4487 4488**示例：** 4489 4490```ts 4491import { BusinessError } from '@kit.BasicServicesKit'; 4492 4493function putBatchString(len: number, prefix: string) { 4494 let entries: distributedKVStore.Entry[] = []; 4495 for (let i = 0; i < len; i++) { 4496 let entry: distributedKVStore.Entry = { 4497 key: prefix + i, 4498 value: { 4499 type: distributedKVStore.ValueType.STRING, 4500 value: 'batch_test_string_value' 4501 } 4502 } 4503 entries.push(entry); 4504 } 4505 return entries; 4506} //自定义函数，放置在作用域最外侧，防止语法检查报错 4507 4508try { 4509 let count = 0; 4510 kvStore.on('dataChange', 0, (data: distributedKVStore.ChangeNotification) => { 4511 console.info(`startTransaction 0 ${data}`); 4512 count++; 4513 }); 4514 kvStore.startTransaction(async (err: BusinessError) => { 4515 if (err != undefined) { 4516 console.error(`Failed to start Transaction.code is ${err.code},message is ${err.message}`); 4517 return; 4518 } 4519 console.info('Succeeded in starting Transaction'); 4520 let entries = putBatchString(10, 'batch_test_string_key'); 4521 console.info(`entries: ${entries}`); 4522 if (kvStore != null) { 4523 kvStore.putBatch(entries, async (err: BusinessError) => { 4524 if (err != undefined) { 4525 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 4526 return; 4527 } 4528 console.info('Succeeded in putting Batch'); 4529 }); 4530 } 4531 }); 4532} catch (e) { 4533 let error = e as BusinessError; 4534 console.error(`Failed to start Transaction.code is ${error.code},message is ${error.message}`); 4535} 4536``` 4537 4538### startTransaction 4539 4540startTransaction(): Promise<void> 4541 4542启动SingleKVStore数据库中的事务，使用Promise异步回调。 4543 4544**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4545 4546**返回值：** 4547 4548| 类型 | 说明 | 4549| ------------------- | ------------------------- | 4550| Promise<void> | 无返回结果的Promise对象。 | 4551 4552**错误码：** 4553 4554以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 4555 4556| **错误码ID** | **错误信息** | 4557| ------------ | ---------------------------------------- | 4558| 15100005 | Database or result set already closed. | 4559 4560以下错误码的详细介绍请参见[关系型数据库错误码](errorcode-data-rdb.md)。 4561 4562| **错误码ID** | **错误信息** | 4563| ------------ | -------------------------------------------- | 4564| 14800047 | The WAL file size exceeds the default limit. | 4565 4566**示例：** 4567 4568```ts 4569import { BusinessError } from '@kit.BasicServicesKit'; 4570 4571try { 4572 let count = 0; 4573 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_ALL, (data: distributedKVStore.ChangeNotification) => { 4574 console.info(`startTransaction 0 ${data}`); 4575 count++; 4576 }); 4577 kvStore.startTransaction().then(async () => { 4578 console.info('Succeeded in starting Transaction'); 4579 }).catch((err: BusinessError) => { 4580 console.error(`Failed to start Transaction.code is ${err.code},message is ${err.message}`); 4581 }); 4582} catch (e) { 4583 let error = e as BusinessError; 4584 console.error(`Failed to start Transaction.code is ${error.code},message is ${error.message}`); 4585} 4586``` 4587 4588### commit 4589 4590commit(callback: AsyncCallback<void>): void 4591 4592提交SingleKVStore数据库中的事务，使用callback异步回调。 4593 4594**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4595 4596**参数：** 4597 4598| 参数名 | 类型 | 必填 | 说明 | 4599| -------- | ------------------------- | ---- | ---------- | 4600| callback | AsyncCallback<void> | 是 | 回调函数。提交SingleKVStore数据库中的事务成功，err为undefined，否则为错误对象。 | 4601 4602**错误码：** 4603 4604以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 4605 4606| **错误码ID** | **错误信息** | 4607| ------------ | -------------------------------------- | 4608| 15100005 | Database or result set already closed. | 4609 4610**示例：** 4611 4612```ts 4613import { BusinessError } from '@kit.BasicServicesKit'; 4614 4615try { 4616 kvStore.commit((err: BusinessError) => { 4617 if (err == undefined) { 4618 console.info('Succeeded in committing'); 4619 } else { 4620 console.error(`Failed to commit.code is ${err.code},message is ${err.message}`); 4621 } 4622 }); 4623} catch (e) { 4624 let error = e as BusinessError; 4625 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4626} 4627``` 4628 4629### commit 4630 4631commit(): Promise<void> 4632 4633提交SingleKVStore数据库中的事务，使用Promise异步回调。 4634 4635**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4636 4637**返回值：** 4638 4639| 类型 | 说明 | 4640| ------------------- | ------------------------- | 4641| Promise<void> | 无返回结果的Promise对象。 | 4642 4643**错误码：** 4644 4645以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 4646 4647| **错误码ID** | **错误信息** | 4648| ------------ | -------------------------------------- | 4649| 15100005 | Database or result set already closed. | 4650 4651**示例：** 4652 4653```ts 4654import { BusinessError } from '@kit.BasicServicesKit'; 4655 4656try { 4657 kvStore.commit().then(async () => { 4658 console.info('Succeeded in committing'); 4659 }).catch((err: BusinessError) => { 4660 console.error(`Failed to commit.code is ${err.code},message is ${err.message}`); 4661 }); 4662} catch (e) { 4663 let error = e as BusinessError; 4664 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4665} 4666``` 4667 4668### rollback 4669 4670rollback(callback: AsyncCallback<void>): void 4671 4672在SingleKVStore数据库中回滚事务，使用callback异步回调。 4673 4674**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4675 4676**参数：** 4677 4678| 参数名 | 类型 | 必填 | 说明 | 4679| -------- | ------------------------- | ---- | ---------- | 4680| callback | AsyncCallback<void> | 是 | 回调函数。SingleKVStore数据库中回滚事务成功，err为undefined，否则为错误对象。 | 4681 4682**错误码：** 4683 4684以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 4685 4686| **错误码ID** | **错误信息** | 4687| ------------ | -------------------------------------- | 4688| 15100005 | Database or result set already closed. | 4689 4690**示例：** 4691 4692```ts 4693import { BusinessError } from '@kit.BasicServicesKit'; 4694 4695try { 4696 kvStore.rollback((err: BusinessError) => { 4697 if (err == undefined) { 4698 console.info('Succeeded in rolling back'); 4699 } else { 4700 console.error(`Failed to rollback.code is ${err.code},message is ${err.message}`); 4701 } 4702 }); 4703} catch (e) { 4704 let error = e as BusinessError; 4705 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4706} 4707``` 4708 4709### rollback 4710 4711rollback(): Promise<void> 4712 4713在SingleKVStore数据库中回滚事务，使用Promise异步回调。 4714 4715**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4716 4717**返回值：** 4718 4719| 类型 | 说明 | 4720| ------------------- | ------------------------- | 4721| Promise<void> | 无返回结果的Promise对象。 | 4722 4723**错误码：** 4724 4725以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 4726 4727| **错误码ID** | **错误信息** | 4728| ------------ | -------------------------------------- | 4729| 15100005 | Database or result set already closed. | 4730 4731**示例：** 4732 4733```ts 4734import { BusinessError } from '@kit.BasicServicesKit'; 4735 4736try { 4737 kvStore.rollback().then(async () => { 4738 console.info('Succeeded in rolling back'); 4739 }).catch((err: BusinessError) => { 4740 console.error(`Failed to rollback.code is ${err.code},message is ${err.message}`); 4741 }); 4742} catch (e) { 4743 let error = e as BusinessError; 4744 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4745} 4746``` 4747 4748### enableSync 4749 4750enableSync(enabled: boolean, callback: AsyncCallback<void>): void 4751 4752设定是否开启端端同步，使用callback异步回调。 4753 4754**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4755 4756**参数：** 4757 4758| 参数名 | 类型 | 必填 | 说明 | 4759| -------- | ------------------------- | ---- | --------------------------------------------------------- | 4760| enabled | boolean | 是 | 设定是否开启端端同步，true表示开启端端同步，false表示不启用端端同步。 | 4761| callback | AsyncCallback<void> | 是 | 回调函数。设定成功，err为undefined，否则为错误对象。 | 4762 4763**错误码：** 4764 4765以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4766 4767| **错误码ID** | **错误信息** | 4768| ------------ | -------------------------------------- | 4769| 401 | Parameter error.Possible causes: 1.Mandatory parameters are left unspecified; 2.Incorrect parameters types. | 4770 4771**示例：** 4772 4773```ts 4774import { BusinessError } from '@kit.BasicServicesKit'; 4775 4776try { 4777 kvStore.enableSync(true, (err: BusinessError) => { 4778 if (err == undefined) { 4779 console.info('Succeeded in enabling sync'); 4780 } else { 4781 console.error(`Failed to enable sync.code is ${err.code},message is ${err.message}`); 4782 } 4783 }); 4784} catch (e) { 4785 let error = e as BusinessError; 4786 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4787} 4788``` 4789 4790### enableSync 4791 4792enableSync(enabled: boolean): Promise<void> 4793 4794设定是否开启端端同步，使用Promise异步回调。 4795 4796**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4797 4798**参数：** 4799 4800| 参数名 | 类型 | 必填 | 说明 | 4801| ------- | -------- | ---- | --------------------------------------------------------- | 4802| enabled | boolean | 是 | 设定是否开启端端同步，true表示开启端端同步，false表示不启用端端同步。 | 4803 4804**返回值：** 4805 4806| 类型 | 说明 | 4807| ------------------- | ------------------------- | 4808| Promise<void> | 无返回结果的Promise对象。 | 4809 4810**错误码：** 4811 4812以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4813 4814| **错误码ID** | **错误信息** | 4815| ------------ | -------------------------------------- | 4816| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 4817 4818**示例：** 4819 4820```ts 4821import { BusinessError } from '@kit.BasicServicesKit'; 4822 4823try { 4824 kvStore.enableSync(true).then(() => { 4825 console.info('Succeeded in enabling sync'); 4826 }).catch((err: BusinessError) => { 4827 console.error(`Failed to enable sync.code is ${err.code},message is ${err.message}`); 4828 }); 4829} catch (e) { 4830 let error = e as BusinessError; 4831 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4832} 4833``` 4834 4835### setSyncRange 4836 4837setSyncRange(localLabels: string[], remoteSupportLabels: string[], callback: AsyncCallback<void>): void 4838 4839设置同步范围标签，使用callback异步回调。 4840 4841**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4842 4843**参数：** 4844 4845| 参数名 | 类型 | 必填 | 说明 | 4846| ------------------- | ------------------------- | ---- | -------------------------------- | 4847| localLabels | string[] | 是 | 表示本地设备的同步标签。 | 4848| remoteSupportLabels | string[] | 是 | 表示要同步数据的设备的同步标签。 | 4849| callback | AsyncCallback<void> | 是 | 回调函数。设置成功，err为undefined，否则为错误对象。| 4850 4851**错误码：** 4852 4853以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4854 4855| **错误码ID** | **错误信息** | 4856| ------------ | ------------ | 4857| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 4858 4859**示例：** 4860 4861```ts 4862import { BusinessError } from '@kit.BasicServicesKit'; 4863 4864try { 4865 const localLabels = ['A', 'B']; 4866 const remoteSupportLabels = ['C', 'D']; 4867 kvStore.setSyncRange(localLabels, remoteSupportLabels, (err: BusinessError) => { 4868 if (err != undefined) { 4869 console.error(`Failed to set syncRange.code is ${err.code},message is ${err.message}`); 4870 return; 4871 } 4872 console.info('Succeeded in setting syncRange'); 4873 }); 4874} catch (e) { 4875 let error = e as BusinessError; 4876 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4877} 4878``` 4879 4880### setSyncRange 4881 4882setSyncRange(localLabels: string[], remoteSupportLabels: string[]): Promise<void> 4883 4884设置同步范围标签，使用Promise异步回调。 4885 4886**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4887 4888**参数：** 4889 4890| 参数名 | 类型 | 必填 | 说明 | 4891| ------------------- | -------- | ---- | -------------------------------- | 4892| localLabels | string[] | 是 | 表示本地设备的同步标签。 | 4893| remoteSupportLabels | string[] | 是 | 表示要同步数据的设备的同步标签。 | 4894 4895**返回值：** 4896 4897| 类型 | 说明 | 4898| ------------------- | ------------------------- | 4899| Promise<void> | 无返回结果的Promise对象。 | 4900 4901**错误码：** 4902 4903以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4904 4905| **错误码ID** | **错误信息** | 4906| ------------ | ------------ | 4907| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 4908 4909**示例：** 4910 4911```ts 4912import { BusinessError } from '@kit.BasicServicesKit'; 4913 4914try { 4915 const localLabels = ['A', 'B']; 4916 const remoteSupportLabels = ['C', 'D']; 4917 kvStore.setSyncRange(localLabels, remoteSupportLabels).then(() => { 4918 console.info('Succeeded in setting syncRange'); 4919 }).catch((err: BusinessError) => { 4920 console.error(`Failed to set syncRange.code is ${err.code},message is ${err.message}`); 4921 }); 4922} catch (e) { 4923 let error = e as BusinessError; 4924 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4925} 4926``` 4927 4928### setSyncParam 4929 4930setSyncParam(defaultAllowedDelayMs: number, callback: AsyncCallback<void>): void 4931 4932设置数据库端端同步允许的默认延时，使用callback异步回调。 4933 4934> **说明：** 4935> 4936> 设置默认延时后，调用[sync](#sync)接口不会立即触发端端同步，而是等待指定的延时时间后再执行。 4937 4938**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4939 4940**参数：** 4941 4942| 参数名 | 类型 | 必填 | 说明 | 4943| --------------------- | ------------------------- | ---- | -------------------------------------------- | 4944| defaultAllowedDelayMs | number | 是 | 表示一个延时时间，单位为毫秒（ms），取值范围为0或[100, 86400000]。| 4945| callback | AsyncCallback<void> | 是 | 回调函数。设置成功，err为undefined，否则为错误对象。 | 4946 4947**错误码：** 4948 4949以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 4950 4951| **错误码ID** | **错误信息** | 4952| ------------ | ------------ | 4953| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 4954 4955**示例：** 4956 4957```ts 4958import { BusinessError } from '@kit.BasicServicesKit'; 4959 4960try { 4961 const defaultAllowedDelayMs = 500; 4962 kvStore.setSyncParam(defaultAllowedDelayMs, (err: BusinessError) => { 4963 if (err != undefined) { 4964 console.error(`Failed to set syncParam.code is ${err.code},message is ${err.message}`); 4965 return; 4966 } 4967 console.info('Succeeded in setting syncParam'); 4968 }); 4969} catch (e) { 4970 let error = e as BusinessError; 4971 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 4972} 4973``` 4974 4975### setSyncParam 4976 4977setSyncParam(defaultAllowedDelayMs: number): Promise<void> 4978 4979设置数据库端端同步允许的默认延时，使用Promise异步回调。 4980 4981> **说明：** 4982> 4983> 设置默认延时后，调用[sync](#sync)接口不会立即触发端端同步，而是等待指定的延时时间后再执行。 4984 4985**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 4986 4987**参数：** 4988 4989| 参数名 | 类型 | 必填 | 说明 | 4990| --------------------- | -------- | ---- | -------------------------------------------- | 4991| defaultAllowedDelayMs | number | 是 | 表示一个延时时间，单位为毫秒（ms），取值范围为0或[100, 86400000]。| 4992 4993**返回值：** 4994 4995| 类型 | 说明 | 4996| ------------------- | ------------------------- | 4997| Promise<void> | 无返回结果的Promise对象。 | 4998 4999**错误码：** 5000 5001以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 5002 5003| **错误码ID** | **错误信息** | 5004| ------------ | ------------ | 5005| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 5006 5007**示例：** 5008 5009```ts 5010import { BusinessError } from '@kit.BasicServicesKit'; 5011 5012try { 5013 const defaultAllowedDelayMs = 500; 5014 kvStore.setSyncParam(defaultAllowedDelayMs).then(() => { 5015 console.info('Succeeded in setting syncParam'); 5016 }).catch((err: BusinessError) => { 5017 console.error(`Failed to set syncParam.code is ${err.code},message is ${err.message}`); 5018 }); 5019} catch (e) { 5020 let error = e as BusinessError; 5021 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 5022} 5023``` 5024 5025### sync 5026 5027sync(deviceIds: string[], mode: SyncMode, delayMs?: number): void 5028 5029在手动同步方式下，触发数据库端端同步。关于键值型数据库的端端同步方式说明，请见[键值型数据库跨设备数据同步](../../database/data-sync-of-kv-store.md)。 5030> **说明：** 5031> 5032> 其中deviceIds为[DeviceBasicInfo](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#devicebasicinfo)中的networkId, 通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 5033 5034**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 5035 5036**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5037 5038**参数：** 5039 5040| 参数名 | 类型 | 必填 | 说明 | 5041| --------- | --------------------- | ---- | ---------------------------------------------- | 5042| deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的networkId列表。 | 5043| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | 5044| delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒），默认为0。设置delayMs后，调用sync接口时延时时间为delayMs。未设置时以[setSyncParam](#setsyncparam)设置的时长为准。| 5045 5046**错误码：** 5047 5048以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5049 5050| **错误码ID** | **错误信息** | 5051| ------------ | ------------------- | 5052| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 5053| 15100003 | Database corrupted. | 5054| 15100004 | Not found. | 5055 5056**示例：** 5057 5058```ts 5059import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 5060import { UIAbility } from '@kit.AbilityKit'; 5061import { BusinessError } from '@kit.BasicServicesKit'; 5062 5063let devManager: distributedDeviceManager.DeviceManager; 5064const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; 5065const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; 5066// create deviceManager 5067export default class EntryAbility extends UIAbility { 5068 onCreate() { 5069 let context = this.context; 5070 try { 5071 devManager = distributedDeviceManager.createDeviceManager(context.applicationInfo.name); 5072 let deviceIds: string[] = []; 5073 if (devManager != null) { 5074 let devices = devManager.getAvailableDeviceListSync(); 5075 for (let i = 0; i < devices.length; i++) { 5076 deviceIds[i] = devices[i].networkId as string; 5077 } 5078 } 5079 try { 5080 if (kvStore != null) { 5081 kvStore.on('syncComplete', (data: [string, number][]) => { 5082 console.info('Sync dataChange'); 5083 }); 5084 if (kvStore != null) { 5085 kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, (err: BusinessError) => { 5086 if (err != undefined) { 5087 console.error(`Failed to sync.code is ${err.code},message is ${err.message}`); 5088 return; 5089 } 5090 console.info('Succeeded in putting data'); 5091 const mode = distributedKVStore.SyncMode.PULL_ONLY; 5092 if (kvStore != null) { 5093 kvStore.sync(deviceIds, mode, 1000); 5094 } 5095 }); 5096 } 5097 } 5098 } catch (e) { 5099 let error = e as BusinessError; 5100 console.error(`Failed to sync.code is ${error.code},message is ${error.message}`); 5101 } 5102 5103 } catch (err) { 5104 let error = err as BusinessError; 5105 console.error("createDeviceManager errCode:" + error.code + ",errMessage:" + error.message); 5106 } 5107 } 5108} 5109``` 5110 5111### sync 5112 5113sync(deviceIds: string[], query: Query, mode: SyncMode, delayMs?: number): void 5114 5115在手动同步方式下，触发数据库端端同步，此方法为同步方法。关于键值型数据库的端端同步方式说明，请见[键值型数据库跨设备数据同步](../../database/data-sync-of-kv-store.md)。 5116> **说明：** 5117> 5118> 其中deviceIds为[DeviceBasicInfo](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#devicebasicinfo)中的networkId, 通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 5119 5120**需要权限**： ohos.permission.DISTRIBUTED_DATASYNC。 5121 5122**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5123 5124**参数：** 5125 5126| 参数名 | 类型 | 必填 | 说明 | 5127| --------- | --------------------- | ---- | ---------------------------------------------- | 5128| deviceIds | string[] | 是 | 同一组网环境下，需要同步的设备的networkId列表。 | 5129| query | [Query](#query) | 是 | 表示数据库的查询谓词条件。 | 5130| mode | [SyncMode](#syncmode) | 是 | 同步模式。 | 5131| delayMs | number | 否 | 可选参数，允许延时时间，单位：ms（毫秒），默认为0。设置delayMs后，调用sync接口时延时时间为delayMs。未设置时以[setSyncParam](#setsyncparam)设置的时长为准。| 5132 5133**错误码：** 5134 5135以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5136 5137| **错误码ID** | **错误信息** | 5138| ------------ | ------------------- | 5139| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 5140| 15100003 | Database corrupted. | 5141| 15100004 | Not found. | 5142 5143**示例：** 5144 5145```ts 5146import { distributedDeviceManager } from '@kit.DistributedServiceKit'; 5147import { UIAbility } from '@kit.AbilityKit'; 5148import { BusinessError } from '@kit.BasicServicesKit'; 5149 5150const KEY_TEST_SYNC_ELEMENT = 'key_test_sync'; 5151const VALUE_TEST_SYNC_ELEMENT = 'value-string-001'; 5152// create deviceManager 5153export default class EntryAbility extends UIAbility { 5154 onCreate() { 5155 let context = this.context; 5156 try { 5157 let devManager = distributedDeviceManager.createDeviceManager(context.applicationInfo.name); 5158 let deviceIds: string[] = []; 5159 if (devManager != null) { 5160 let devices = devManager.getAvailableDeviceListSync(); 5161 for (let i = 0; i < devices.length; i++) { 5162 deviceIds[i] = devices[i].networkId as string; 5163 } 5164 } 5165 try { 5166 if (kvStore != null) { 5167 kvStore.on('syncComplete', (data: [string, number][]) => { 5168 console.info('Sync dataChange'); 5169 }); 5170 if (kvStore != null) { 5171 kvStore.put(KEY_TEST_SYNC_ELEMENT + 'testSync101', VALUE_TEST_SYNC_ELEMENT, (err: BusinessError) => { 5172 if (err != undefined) { 5173 console.error(`Failed to sync.code is ${err.code},message is ${err.message}`); 5174 return; 5175 } 5176 console.info('Succeeded in putting data'); 5177 const mode = distributedKVStore.SyncMode.PULL_ONLY; 5178 const query = new distributedKVStore.Query(); 5179 query.prefixKey("batch_test"); 5180 query.deviceId(devManager.getLocalDeviceNetworkId()); 5181 if (kvStore != null) { 5182 kvStore.sync(deviceIds, query, mode, 1000); 5183 } 5184 }); 5185 } 5186 } 5187 } catch (e) { 5188 let error = e as BusinessError; 5189 console.error(`Failed to sync.code is ${error.code},message is ${error.message}`); 5190 } 5191 5192 } catch (err) { 5193 let error = err as BusinessError; 5194 console.error("createDeviceManager errCode:" + error.code + ",errMessage:" + error.message); 5195 } 5196 } 5197} 5198``` 5199 5200### on('dataChange') 5201 5202on(event: 'dataChange', type: SubscribeType, listener: Callback<ChangeNotification>): void 5203 5204订阅指定类型的数据变更通知。 5205 5206**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5207 5208**参数：** 5209 5210| 参数名 | 类型 | 必填 | 说明 | 5211| -------- | --------------------------------------------------------- | ---- | ---------------------------------------------------- | 5212| event | string | 是 | 订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 5213| type | [SubscribeType](#subscribetype) | 是 | 表示订阅的类型。 | 5214| listener | Callback<[ChangeNotification](#changenotification)> | 是 | 回调函数。成功返回数据变更时通知的对象。| 5215 5216**错误码：** 5217 5218以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5219 5220| **错误码ID** | **错误信息** | 5221| ------------ | -------------------------------------- | 5222| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 5223| 15100001 | Over max limits. | 5224| 15100005 | Database or result set already closed. | 5225 5226**示例：** 5227 5228```ts 5229import { BusinessError } from '@kit.BasicServicesKit'; 5230 5231try { 5232 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_LOCAL, (data: distributedKVStore.ChangeNotification) => { 5233 console.info(`dataChange callback call data: ${data}`); 5234 }); 5235} catch (e) { 5236 let error = e as BusinessError; 5237 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 5238} 5239``` 5240 5241### on('syncComplete') 5242 5243on(event: 'syncComplete', syncCallback: Callback<Array<[string, number]>>): void 5244 5245订阅端端同步完成事件回调通知。 5246 5247**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5248 5249**参数：** 5250 5251| 参数名 | 类型 | 必填 | 说明 | 5252| ------------ | --------------------------------------------- | ---- | ------------------------------------------------------ | 5253| event | string | 是 | 订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 5254| syncCallback | Callback<Array<[string, number]>> | 是 | 回调函数。用于向调用方发送同步结果的回调。 | 5255 5256**错误码：** 5257 5258以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 5259 5260| **错误码ID** | **错误信息** | 5261| ------------ | -------------------------------------- | 5262| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 5263 5264**示例：** 5265 5266```ts 5267import { BusinessError } from '@kit.BasicServicesKit'; 5268 5269 5270const KEY_TEST_FLOAT_ELEMENT = 'key_test_float'; 5271const VALUE_TEST_FLOAT_ELEMENT = 321.12; 5272try { 5273 kvStore.on('syncComplete', (data: [string, number][]) => { 5274 console.info(`syncComplete ${data}`); 5275 }); 5276 kvStore.put(KEY_TEST_FLOAT_ELEMENT, VALUE_TEST_FLOAT_ELEMENT).then(() => { 5277 console.info('succeeded in putting'); 5278 }).catch((err: BusinessError) => { 5279 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 5280 }); 5281} catch (e) { 5282 let error = e as BusinessError; 5283 console.error(`Failed to subscribe syncComplete.code is ${error.code},message is ${error.message}`); 5284} 5285``` 5286 5287### off('dataChange') 5288 5289off(event:'dataChange', listener?: Callback<ChangeNotification>): void 5290 5291取消订阅数据变更通知。 5292 5293**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5294 5295**参数：** 5296 5297| 参数名 | 类型 | 必填 | 说明 | 5298| -------- | --------------------------------------------------------- | ---- | -------------------------------------------------------- | 5299| event | string | 是 | 取消订阅的事件名，固定为'dataChange'，表示数据变更事件。 | 5300| listener | Callback<[ChangeNotification](#changenotification)> | 否 | 取消订阅的函数。如不设置callback，则取消所有已订阅的函数。 | 5301 5302**错误码：** 5303 5304以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5305 5306| **错误码ID** | **错误信息** | 5307| ------------ | -------------------------------------- | 5308| 401 | Parameter error. Possible causes: 1.Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 5309| 15100005 | Database or result set already closed. | 5310 5311**示例：** 5312 5313```ts 5314import { BusinessError } from '@kit.BasicServicesKit'; 5315 5316class KvstoreModel { 5317 call(data: distributedKVStore.ChangeNotification) { 5318 console.info(`dataChange : ${data}`); 5319 } 5320 5321 subscribeDataChange() { 5322 try { 5323 if (kvStore != null) { 5324 kvStore.on('dataChange', distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE, this.call); 5325 } 5326 } catch (err) { 5327 let error = err as BusinessError; 5328 console.error(`Failed to subscribeDataChange.code is ${error.code},message is ${error.message}`); 5329 } 5330 } 5331 5332 unsubscribeDataChange() { 5333 try { 5334 if (kvStore != null) { 5335 kvStore.off('dataChange', this.call); 5336 } 5337 } catch (err) { 5338 let error = err as BusinessError; 5339 console.error(`Failed to unsubscribeDataChange.code is ${error.code},message is ${error.message}`); 5340 } 5341 } 5342} 5343``` 5344 5345### off('syncComplete') 5346 5347off(event: 'syncComplete', syncCallback?: Callback<Array<[string, number]>>): void 5348 5349取消订阅端端同步完成事件回调通知。 5350 5351**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5352 5353**参数：** 5354 5355| 参数名 | 类型 | 必填 | 说明 | 5356| ------------ | --------------------------------------------- | ---- | ---------------------------------------------------------- | 5357| event | string | 是 | 取消订阅的事件名，固定为'syncComplete'，表示同步完成事件。 | 5358| syncCallback | Callback<Array<[string, number]>> | 否 | 取消订阅的函数。如不设置callback，则取消所有已订阅的函数。 | 5359 5360**错误码：** 5361 5362以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)。 5363 5364| **错误码ID** | **错误信息** | 5365| ------------ | -------------------------------------- | 5366| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 5367 5368**示例：** 5369 5370```ts 5371import { BusinessError } from '@kit.BasicServicesKit'; 5372 5373class KvstoreModel { 5374 call(data: [string, number][]) { 5375 console.info(`syncComplete : ${data}`); 5376 } 5377 5378 subscribeDataChange() { 5379 try { 5380 if (kvStore != null) { 5381 kvStore.on('syncComplete', this.call); 5382 } 5383 } catch (err) { 5384 let error = err as BusinessError; 5385 console.error(`Failed to subscribeDataChange.code is ${error.code},message is ${error.message}`); 5386 } 5387 } 5388 5389 unsubscribeDataChange() { 5390 try { 5391 if (kvStore != null) { 5392 kvStore.off('syncComplete', this.call); 5393 } 5394 } catch (err) { 5395 let error = err as BusinessError; 5396 console.error(`Failed to unsubscribeDataChange.code is ${error.code},message is ${error.message}`); 5397 } 5398 } 5399} 5400``` 5401 5402### getSecurityLevel 5403 5404getSecurityLevel(callback: AsyncCallback<SecurityLevel>): void 5405 5406获取数据库的安全级别，使用callback异步回调。 5407 5408**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5409 5410**参数：** 5411 5412| 参数名 | 类型 | 必填 | 说明 | 5413| -------- | ---------------------------------------------------- | ---- | -------------------------------- | 5414| callback | AsyncCallback<[SecurityLevel](#securitylevel)> | 是 | 回调函数。返回数据库的安全级别。 | 5415 5416**错误码：** 5417 5418以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 5419 5420| **错误码ID** | **错误信息** | 5421| ------------ | -------------------------------------- | 5422| 15100005 | Database or result set already closed. | 5423 5424**示例：** 5425 5426```ts 5427import { BusinessError } from '@kit.BasicServicesKit'; 5428 5429try { 5430 kvStore.getSecurityLevel((err: BusinessError, data: distributedKVStore.SecurityLevel) => { 5431 if (err != undefined) { 5432 console.error(`Failed to get SecurityLevel.code is ${err.code},message is ${err.message}`); 5433 return; 5434 } 5435 console.info('Succeeded in getting securityLevel'); 5436 }); 5437} catch (e) { 5438 let error = e as BusinessError; 5439 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 5440} 5441``` 5442 5443### getSecurityLevel 5444 5445getSecurityLevel(): Promise<SecurityLevel> 5446 5447获取数据库的安全级别，使用Promise异步回调。 5448 5449**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5450 5451**返回值：** 5452 5453| 类型 | 说明 | 5454| ---------------------------------------------- | ----------------------------------- | 5455| Promise<[SecurityLevel](#securitylevel)> | Promise对象。返回数据库的安全级别。 | 5456 5457**错误码：** 5458 5459以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)。 5460 5461| **错误码ID** | **错误信息** | 5462| ------------ | -------------------------------------- | 5463| 15100005 | Database or result set already closed. | 5464 5465**示例：** 5466 5467```ts 5468import { BusinessError } from '@kit.BasicServicesKit'; 5469 5470try { 5471 kvStore.getSecurityLevel().then((data: distributedKVStore.SecurityLevel) => { 5472 console.info('Succeeded in getting securityLevel'); 5473 }).catch((err: BusinessError) => { 5474 console.error(`Failed to get SecurityLevel.code is ${err.code},message is ${err.message}`); 5475 }); 5476} catch (e) { 5477 let error = e as BusinessError; 5478 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 5479} 5480``` 5481 5482## DeviceKVStore 5483 5484设备协同数据库，继承自SingleKVStore，提供查询数据和端端同步数据的方法，可以使用SingleKVStore的方法例如：put、putBatch等。 5485 5486设备协同数据库，以设备维度对数据进行区分，每台设备仅能写入和修改本设备的数据，其它设备的数据对其是只读的，无法修改其它设备的数据。 5487 5488比如，可以使用设备协同数据库实现设备间的图片分享，可以查看其他设备的图片，但无法修改和删除其他设备的图片。 5489 5490在调用DeviceKVStore的方法前，需要先通过[getKVStore](#getkvstore)构建一个DeviceKVStore实例。 5491 5492### get 5493 5494get(key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void 5495 5496获取本设备指定键的值，使用callback异步回调。 5497 5498**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5499 5500**参数：** 5501 5502| 参数名 | 类型 | 必填 | 说明 | 5503| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 5504| key | string | 是 | 要查询数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 5505| callback | AsyncCallback<boolean \| string \| number \| Uint8Array> | 是 | 回调函数。返回获取查询的值。 | 5506 5507**错误码：** 5508 5509以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5510 5511| **错误码ID** | **错误信息** | 5512| ------------ | -------------------------------------- | 5513| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 5514| 15100003 | Database corrupted. | 5515| 15100004 | Not found. | 5516| 15100005 | Database or result set already closed. | 5517 5518**示例：** 5519 5520```ts 5521import { BusinessError } from '@kit.BasicServicesKit'; 5522 5523const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 5524const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 5525try { 5526 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err: BusinessError) => { 5527 if (err != undefined) { 5528 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 5529 return; 5530 } 5531 console.info("Succeeded in putting"); 5532 if (kvStore != null) { 5533 kvStore.get(KEY_TEST_STRING_ELEMENT, (err: BusinessError, data: boolean | string | number | Uint8Array) => { 5534 if (err != undefined) { 5535 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5536 return; 5537 } 5538 console.info(`Succeeded in getting data.data=${data}`); 5539 }); 5540 } 5541 }); 5542} catch (e) { 5543 let error = e as BusinessError; 5544 console.error(`Failed to get.code is ${error.code},message is ${error.message}`); 5545} 5546``` 5547 5548### get 5549 5550get(key: string): Promise<boolean | string | number | Uint8Array> 5551 5552获取本设备指定键的值，使用Promise异步回调。 5553 5554**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5555 5556**参数：** 5557 5558| 参数名 | 类型 | 必填 | 说明 | 5559| ------ | ------ | ---- | ------------------------------------------------------------ | 5560| key | string | 是 | 要查询数据的Key，不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 5561 5562**返回值：** 5563 5564| 类型 | 说明 | 5565| -------------------------------------------------------- | ------------------------------- | 5566| Promise<boolean \| string \| number \| Uint8Array> | Promise对象。返回获取查询的值。 | 5567 5568**错误码：** 5569 5570以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5571 5572| **错误码ID** | **错误信息** | 5573| ------------ | -------------------------------------- | 5574| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 5575| 15100003 | Database corrupted. | 5576| 15100004 | Not found. | 5577| 15100005 | Database or result set already closed. | 5578 5579**示例：** 5580 5581```ts 5582import { BusinessError } from '@kit.BasicServicesKit'; 5583 5584const KEY_TEST_STRING_ELEMENT = 'key_test_string'; 5585const VALUE_TEST_STRING_ELEMENT = 'value-test-string'; 5586try { 5587 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(() => { 5588 console.info(`Succeeded in putting data`); 5589 if (kvStore != null) { 5590 kvStore.get(KEY_TEST_STRING_ELEMENT).then((data: boolean | string | number | Uint8Array) => { 5591 console.info(`Succeeded in getting data.data=${data}`); 5592 }).catch((err: BusinessError) => { 5593 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5594 }); 5595 } 5596 }).catch((err: BusinessError) => { 5597 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 5598 }); 5599} catch (e) { 5600 let error = e as BusinessError; 5601 console.error(`Failed to get.code is ${error.code},message is ${error.message}`); 5602} 5603``` 5604 5605### get 5606 5607get(deviceId: string, key: string, callback: AsyncCallback<boolean | string | number | Uint8Array>): void 5608 5609获取与指定设备ID和Key匹配的string值，使用callback异步回调。 5610> **说明：** 5611> 5612> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 5613> deviceId具体获取方式请参考[sync接口示例](#sync)。 5614 5615**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5616 5617**参数：** 5618 5619| 参数名 | 类型 | 必填 | 说明 | 5620| ----- | ------ | ---- | ----------------------- | 5621| deviceId |string | 是 |标识要查询其数据的设备。 | 5622| key |string | 是 |表示要查询Key值的键, 不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 5623| callback |AsyncCallback<boolean\|string\|number\|Uint8Array> | 是 |回调函数，返回匹配给定条件的字符串值。 | 5624 5625**错误码：** 5626 5627以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5628 5629| **错误码ID** | **错误信息** | 5630| ------------ | -------------------------------------- | 5631| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 5632| 15100003 | Database corrupted. | 5633| 15100004 | Not found. | 5634| 15100005 | Database or result set already closed. | 5635 5636**示例：** 5637 5638```ts 5639import { BusinessError } from '@kit.BasicServicesKit'; 5640 5641const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 5642const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 5643try { 5644 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, async (err: BusinessError) => { 5645 if (err != undefined) { 5646 console.error(`Failed to put.code is ${err.code},message is ${err.message}`); 5647 return; 5648 } 5649 console.info('Succeeded in putting'); 5650 if (kvStore != null) { 5651 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT, (err: BusinessError, data: boolean | string | number | Uint8Array) => { 5652 if (err != undefined) { 5653 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5654 return; 5655 } 5656 console.info('Succeeded in getting'); 5657 }); 5658 } 5659 }) 5660} catch (e) { 5661 let error = e as BusinessError; 5662 console.error(`Failed to get.code is ${error.code},message is ${error.message}`); 5663} 5664``` 5665 5666### get 5667 5668get(deviceId: string, key: string): Promise<boolean | string | number | Uint8Array> 5669 5670获取与指定设备ID和Key匹配的string值，使用Promise异步回调。 5671> **说明：** 5672> 5673> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 5674> deviceId具体获取方式请参考[sync接口示例](#sync)。 5675 5676**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5677 5678**参数：** 5679 5680| 参数名 | 类型 | 必填 | 说明 | 5681| -------- | -------- | ---- | ------------------------ | 5682| deviceId | string | 是 | 标识要查询其数据的设备。 | 5683| key | string | 是 | 表示要查询Key值的键, 不能为空且长度不大于[MAX_KEY_LENGTH](#constants)。 | 5684 5685**返回值：** 5686 5687| 类型 | 说明 | 5688| ------ | ------- | 5689|Promise<boolean\|string\|number\|Uint8Array> |Promise对象。返回匹配给定条件的字符串值。| 5690 5691**错误码：** 5692 5693以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5694 5695| **错误码ID** | **错误信息** | 5696| ------------ | -------------------------------------- | 5697| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types; 3. Parameter verification failed. | 5698| 15100003 | Database corrupted. | 5699| 15100004 | Not found. | 5700| 15100005 | Database or result set already closed. | 5701 5702**示例：** 5703 5704```ts 5705import { BusinessError } from '@kit.BasicServicesKit'; 5706 5707const KEY_TEST_STRING_ELEMENT = 'key_test_string_2'; 5708const VALUE_TEST_STRING_ELEMENT = 'value-string-002'; 5709try { 5710 kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT).then(async () => { 5711 console.info('Succeeded in putting'); 5712 if (kvStore != null) { 5713 kvStore.get('localDeviceId', KEY_TEST_STRING_ELEMENT).then((data: boolean | string | number | Uint8Array) => { 5714 console.info('Succeeded in getting'); 5715 }).catch((err: BusinessError) => { 5716 console.error(`Failed to get.code is ${err.code},message is ${err.message}`); 5717 }); 5718 } 5719 }).catch((error: BusinessError) => { 5720 console.error(`Failed to put.code is ${error.code},message is ${error.message}`); 5721 }); 5722} catch (e) { 5723 let error = e as BusinessError; 5724 console.error(`Failed to get.code is ${error.code},message is ${error.message}`); 5725} 5726``` 5727 5728### getEntries 5729 5730getEntries(keyPrefix: string, callback: AsyncCallback<Entry[]>): void 5731 5732获取匹配本设备指定键前缀的所有键值对，使用callback异步回调。 5733 5734**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5735 5736**参数：** 5737 5738| 参数名 | 类型 | 必填 | 说明 | 5739| --------- | -------------------------------------- | ---- | ---------------------------------------- | 5740| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 5741| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回匹配指定前缀的键值对列表。 | 5742 5743**错误码：** 5744 5745以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5746 5747| **错误码ID** | **错误信息** | 5748| ------------ | -------------------------------------- | 5749| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 5750| 15100003 | Database corrupted. | 5751| 15100005 | Database or result set already closed. | 5752 5753**示例：** 5754 5755```ts 5756import { BusinessError } from '@kit.BasicServicesKit'; 5757 5758try { 5759 let entries: distributedKVStore.Entry[] = []; 5760 for (let i = 0; i < 10; i++) { 5761 let key = 'batch_test_string_key'; 5762 let entry: distributedKVStore.Entry = { 5763 key: key + i, 5764 value: { 5765 type: distributedKVStore.ValueType.STRING, 5766 value: 'batch_test_string_value' 5767 } 5768 } 5769 entries.push(entry); 5770 } 5771 console.info(`entries: ${entries}`); 5772 kvStore.putBatch(entries, async (err: BusinessError) => { 5773 if (err != undefined) { 5774 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 5775 return; 5776 } 5777 console.info('Succeeded in putting Batch'); 5778 if (kvStore != null) { 5779 kvStore.getEntries('batch_test_string_key', (err: BusinessError, entries: distributedKVStore.Entry[]) => { 5780 if (err != undefined) { 5781 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 5782 return; 5783 } 5784 console.info('Succeeded in getting Entries'); 5785 console.info(`entries.length: ${entries.length}`); 5786 console.info(`entries[0]: ${entries[0]}`); 5787 }); 5788 } 5789 }); 5790} catch (e) { 5791 let error = e as BusinessError; 5792 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message} `); 5793} 5794``` 5795 5796### getEntries 5797 5798getEntries(keyPrefix: string): Promise<Entry[]> 5799 5800获取匹配本设备指定键前缀的所有键值对，使用Promise异步回调。 5801 5802**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 5803 5804**参数：** 5805 5806| 参数名 | 类型 | 必填 | 说明 | 5807| --------- | ------ | ---- | -------------------- | 5808| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 5809 5810**返回值：** 5811 5812| 类型 | 说明 | 5813| -------------------------------- | ------------------------------------------- | 5814| Promise<[Entry](#entry)[]> | Promise对象。返回匹配指定前缀的键值对列表。 | 5815 5816**错误码：** 5817 5818以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5819 5820| **错误码ID** | **错误信息** | 5821| ------------ | -------------------------------------- | 5822| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 5823| 15100003 | Database corrupted. | 5824| 15100005 | Database or result set already closed. | 5825 5826**示例：** 5827 5828```ts 5829import { BusinessError } from '@kit.BasicServicesKit'; 5830 5831try { 5832 let entries: distributedKVStore.Entry[] = []; 5833 for (let i = 0; i < 10; i++) { 5834 let key = 'batch_test_string_key'; 5835 let entry: distributedKVStore.Entry = { 5836 key: key + i, 5837 value: { 5838 type: distributedKVStore.ValueType.STRING, 5839 value: 'batch_test_string_value' 5840 } 5841 } 5842 entries.push(entry); 5843 } 5844 console.info(`entries: ${entries}`); 5845 kvStore.putBatch(entries).then(async () => { 5846 console.info('Succeeded in putting Batch'); 5847 if (kvStore != null) { 5848 kvStore.getEntries('batch_test_string_key').then((entries: distributedKVStore.Entry[]) => { 5849 console.info('Succeeded in getting Entries'); 5850 console.info(`PutBatch ${entries}`); 5851 }).catch((err: BusinessError) => { 5852 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 5853 }); 5854 } 5855 }).catch((err: BusinessError) => { 5856 console.error(`Failed to put Batch.code is ${err.code},message is ${err.message}`); 5857 }); 5858} catch (e) { 5859 let error = e as BusinessError; 5860 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message} `); 5861} 5862``` 5863 5864### getEntries 5865 5866getEntries(deviceId: string, keyPrefix: string, callback: AsyncCallback<Entry[]>): void 5867 5868获取与指定设备ID和Key前缀匹配的所有键值对，使用callback异步回调。 5869> **说明：** 5870> 5871> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 5872> deviceId具体获取方式请参考[sync接口示例](#sync)。 5873 5874**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5875 5876**参数：** 5877 5878| 参数名 | 类型 | 必填 | 说明 | 5879| --------- | -------------------------------------- | ---- | ---------------------------------------------- | 5880| deviceId | string | 是 | 标识要查询其数据的设备。 | 5881| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 5882| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数，返回满足给定条件的所有键值对的列表。 | 5883 5884**错误码：** 5885 5886以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5887 5888| **错误码ID** | **错误信息** | 5889| ------------ | -------------------------------------- | 5890| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 5891| 15100003 | Database corrupted. | 5892| 15100005 | Database or result set already closed. | 5893 5894**示例：** 5895 5896```ts 5897import { BusinessError } from '@kit.BasicServicesKit'; 5898 5899try { 5900 let entries: distributedKVStore.Entry[] = []; 5901 for (let i = 0; i < 10; i++) { 5902 let key = 'batch_test_string_key'; 5903 let entry: distributedKVStore.Entry = { 5904 key: key + i, 5905 value: { 5906 type: distributedKVStore.ValueType.STRING, 5907 value: 'batch_test_string_value' 5908 } 5909 } 5910 entries.push(entry); 5911 } 5912 console.info(`entries : ${entries}`); 5913 kvStore.putBatch(entries, async (err: BusinessError) => { 5914 if (err != undefined) { 5915 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 5916 return; 5917 } 5918 console.info('Succeeded in putting batch'); 5919 if (kvStore != null) { 5920 kvStore.getEntries('localDeviceId', 'batch_test_string_key', (err: BusinessError, entries: distributedKVStore.Entry[]) => { 5921 if (err != undefined) { 5922 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 5923 return; 5924 } 5925 console.info('Succeeded in getting entries'); 5926 console.info(`entries.length: ${entries.length}`); 5927 console.info(`entries[0]: ${entries[0]}`); 5928 }); 5929 } 5930 }); 5931} catch (e) { 5932 let error = e as BusinessError; 5933 console.error(`Failed to put batch.code is ${error.code},message is ${error.message}`); 5934} 5935``` 5936 5937### getEntries 5938 5939getEntries(deviceId: string, keyPrefix: string): Promise<Entry[]> 5940 5941获取与指定设备ID和Key前缀匹配的所有键值对，使用Promise异步回调。 5942> **说明：** 5943> 5944> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 5945> deviceId具体获取方式请参考[sync接口示例](#sync)。 5946 5947**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 5948 5949**参数：** 5950 5951| 参数名 | 类型 | 必填 | 说明 | 5952| --------- | -------- | ---- | ------------------------ | 5953| deviceId | string | 是 | 标识要查询其数据的设备。 | 5954| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。| 5955 5956**返回值：** 5957 5958| 类型 | 说明 | 5959| -------------------------------- | ------------------------------------------------- | 5960| Promise<[Entry](#entry)[]> | Promise对象。返回匹配给定条件的所有键值对的列表。 | 5961 5962**错误码：** 5963 5964以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 5965 5966| **错误码ID** | **错误信息** | 5967| ------------ | -------------------------------------- | 5968| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 5969| 15100003 | Database corrupted. | 5970| 15100005 | Database or result set already closed. | 5971 5972**示例：** 5973 5974<!--code_no_check--> 5975```ts 5976import { BusinessError } from '@kit.BasicServicesKit'; 5977 5978try { 5979 let entries: distributedKVStore.Entry[] = []; 5980 for (let i = 0; i < 10; i++) { 5981 let key = 'batch_test_string_key'; 5982 let entry: distributedKVStore.Entry = { 5983 key: key + i, 5984 value: { 5985 type: distributedKVStore.ValueType.STRING, 5986 value: 'batch_test_string_value' 5987 } 5988 } 5989 entries.push(entry); 5990 } 5991 console.info(`entries: ${entries}`); 5992 kvStore.putBatch(entries).then(async () => { 5993 console.info('Succeeded in putting batch'); 5994 if (kvStore != null) { 5995 kvStore.getEntries('localDeviceId', 'batch_test_string_key').then((entries: distributedKVStore.Entry[]) => { 5996 console.info('Succeeded in getting entries'); 5997 console.info(`entries.length: ${entries.length}`); 5998 console.info(`entries[0]: ${entries[0]}`); 5999 console.info(`entries[0].value: ${entries[0].value}`); 6000 console.info(`entries[0].value.value: ${entries[0].value.value}`); 6001 }).catch((err: BusinessError) => { 6002 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 6003 }); 6004 } 6005 }).catch((err: BusinessError) => { 6006 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6007 }); 6008} catch (e) { 6009 let error = e as BusinessError; 6010 console.error(`Failed to put batch.code is ${error.code},message is ${error.message}`); 6011} 6012``` 6013 6014### getEntries 6015 6016getEntries(query: Query, callback: AsyncCallback<Entry[]>): void 6017 6018获取本设备与指定Query对象匹配的键值对列表，使用callback异步回调。 6019 6020**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6021 6022**参数：** 6023 6024| 参数名 | 类型 | 必填 | 说明 | 6025| -------- | -------------------------------------- | ---- | ----------------------------------------------------- | 6026| query | [Query](#query) | 是 | 表示要匹配的键前缀。 | 6027| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回本设备与指定Query对象匹配的键值对列表。 | 6028 6029**错误码：** 6030 6031以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6032 6033| **错误码ID** | **错误信息** | 6034| ------------ | -------------------------------------- | 6035| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6036| 15100003 | Database corrupted. | 6037| 15100005 | Database or result set already closed. | 6038 6039**示例：** 6040 6041```ts 6042import { BusinessError } from '@kit.BasicServicesKit'; 6043 6044try { 6045 let arr = new Uint8Array([21, 31]); 6046 let entries: distributedKVStore.Entry[] = []; 6047 for (let i = 0; i < 10; i++) { 6048 let key = 'batch_test_bool_key'; 6049 let entry: distributedKVStore.Entry = { 6050 key: key + i, 6051 value: { 6052 type: distributedKVStore.ValueType.BYTE_ARRAY, 6053 value: arr 6054 } 6055 } 6056 entries.push(entry); 6057 } 6058 console.info(`entries: {entries}`); 6059 kvStore.putBatch(entries, (err: BusinessError) => { 6060 console.info('Succeeded in putting Batch'); 6061 const query = new distributedKVStore.Query(); 6062 query.prefixKey("batch_test"); 6063 if (kvStore != null) { 6064 kvStore.getEntries(query, (err: BusinessError, entries: distributedKVStore.Entry[]) => { 6065 if (err != undefined) { 6066 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 6067 return; 6068 } 6069 console.info('Succeeded in getting Entries'); 6070 console.info(`entries.length: ${entries.length}`); 6071 console.info(`entries[0]: ${entries[0]}`); 6072 }); 6073 } 6074 }); 6075} catch (e) { 6076 let error = e as BusinessError; 6077 console.error(`Failed to get Entries.code is ${error.code},message is ${error.message}`); 6078} 6079``` 6080 6081### getEntries 6082 6083getEntries(query: Query): Promise<Entry[]> 6084 6085获取本设备与指定Query对象匹配的键值对列表，使用Promise异步回调。 6086 6087**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6088 6089**参数：** 6090 6091| 参数名 | 类型 | 必填 | 说明 | 6092| ------ | -------------- | ---- | -------------- | 6093| query | [Query](#query) | 是 | 表示查询对象。 | 6094 6095**返回值：** 6096 6097| 类型 | 说明 | 6098| -------------------------------- | -------------------------------------------------------- | 6099| Promise<[Entry](#entry)[]> | Promise对象。返回本设备与指定Query对象匹配的键值对列表。 | 6100 6101**错误码：** 6102 6103以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6104 6105| **错误码ID** | **错误信息** | 6106| ------------ | -------------------------------------- | 6107| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6108| 15100003 | Database corrupted. | 6109| 15100005 | Database or result set already closed. | 6110 6111**示例：** 6112 6113```ts 6114import { BusinessError } from '@kit.BasicServicesKit'; 6115 6116try { 6117 let arr = new Uint8Array([21, 31]); 6118 let entries: distributedKVStore.Entry[] = []; 6119 for (let i = 0; i < 10; i++) { 6120 let key = 'batch_test_bool_key'; 6121 let entry: distributedKVStore.Entry = { 6122 key: key + i, 6123 value: { 6124 type: distributedKVStore.ValueType.BYTE_ARRAY, 6125 value: arr 6126 } 6127 } 6128 entries.push(entry); 6129 } 6130 console.info(`entries: {entries}`); 6131 kvStore.putBatch(entries).then(async () => { 6132 console.info('Succeeded in putting Batch'); 6133 const query = new distributedKVStore.Query(); 6134 query.prefixKey("batch_test"); 6135 if (kvStore != null) { 6136 kvStore.getEntries(query).then((entries: distributedKVStore.Entry[]) => { 6137 console.info('Succeeded in getting Entries'); 6138 }).catch((err: BusinessError) => { 6139 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`); 6140 }); 6141 } 6142 }).catch((err: BusinessError) => { 6143 console.error(`Failed to get Entries.code is ${err.code},message is ${err.message}`) 6144 }); 6145 console.info('Succeeded in getting Entries'); 6146} catch (e) { 6147 let error = e as BusinessError; 6148 console.error(`Failed to get Entries.code is ${error.code},message is ${error.message}`); 6149} 6150``` 6151 6152### getEntries 6153 6154getEntries(deviceId: string, query: Query, callback: AsyncCallback<Entry[]>): void 6155 6156获取与指定设备ID和Query对象匹配的键值对列表，使用callback异步回调。 6157> **说明：** 6158> 6159> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6160> deviceId具体获取方式请参考[sync接口示例](#sync)。 6161 6162**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6163 6164**参数：** 6165 6166| 参数名 | 类型 | 必填 | 说明 | 6167| -------- | -------------------------------------- | ---- | ------------------------------------------------------- | 6168| deviceId | string | 是 | 键值对所属的设备ID。 | 6169| query | [Query](#query) | 是 | 表示查询对象。 | 6170| callback | AsyncCallback<[Entry](#entry)[]> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的键值对列表。 | 6171 6172**错误码：** 6173 6174以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6175 6176| **错误码ID** | **错误信息** | 6177| ------------ | -------------------------------------- | 6178| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6179| 15100003 | Database corrupted. | 6180| 15100005 | Database or result set already closed. | 6181 6182**示例：** 6183 6184```ts 6185import { BusinessError } from '@kit.BasicServicesKit'; 6186 6187try { 6188 let arr = new Uint8Array([21, 31]); 6189 let entries: distributedKVStore.Entry[] = []; 6190 for (let i = 0; i < 10; i++) { 6191 let key = 'batch_test_bool_key'; 6192 let entry: distributedKVStore.Entry = { 6193 key: key + i, 6194 value: { 6195 type: distributedKVStore.ValueType.BYTE_ARRAY, 6196 value: arr 6197 } 6198 } 6199 entries.push(entry); 6200 } 6201 console.info(`entries: ${entries}`); 6202 kvStore.putBatch(entries, async (err: BusinessError) => { 6203 if (err != undefined) { 6204 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6205 return; 6206 } 6207 console.info('Succeeded in putting batch'); 6208 let query = new distributedKVStore.Query(); 6209 query.deviceId('localDeviceId'); 6210 query.prefixKey("batch_test"); 6211 if (kvStore != null) { 6212 kvStore.getEntries('localDeviceId', query, (err: BusinessError, entries: distributedKVStore.Entry[]) => { 6213 if (err != undefined) { 6214 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 6215 return; 6216 } 6217 console.info('Succeeded in getting entries'); 6218 console.info(`entries.length: ${entries.length}`); 6219 console.info(`entries[0]: ${entries[0]}`); 6220 }) 6221 } 6222 }); 6223 console.info('Succeeded in getting entries'); 6224} catch (e) { 6225 let error = e as BusinessError; 6226 console.error(`Failed to get entries.code is ${error.code},message is ${error.message}`); 6227} 6228``` 6229 6230### getEntries 6231 6232getEntries(deviceId: string, query: Query): Promise<Entry[]> 6233 6234获取与指定设备ID和Query对象匹配的键值对列表，使用Promise异步回调。 6235> **说明：** 6236> 6237> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6238> deviceId具体获取方式请参考[sync接口示例](#sync)。 6239 6240**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6241 6242**参数：** 6243 6244| 参数名 | 类型 | 必填 | 说明 | 6245| -------- | -------------- | ---- | -------------------- | 6246| deviceId | string | 是 | 键值对所属的设备ID。 | 6247| query | [Query](#query) | 是 | 表示查询对象。 | 6248 6249**返回值：** 6250 6251| 类型 | 说明 | 6252| -------------------------------- | ---------------------------------------------------------- | 6253| Promise<[Entry](#entry)[]> | Promise对象。返回与指定设备ID和Query对象匹配的键值对列表。 | 6254 6255**错误码：** 6256 6257以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6258 6259| **错误码ID** | **错误信息** | 6260| ------------ | -------------------------------------- | 6261| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6262| 15100003 | Database corrupted. | 6263| 15100005 | Database or result set already closed. | 6264 6265**示例：** 6266 6267<!--code_no_check--> 6268```ts 6269import { BusinessError } from '@kit.BasicServicesKit'; 6270 6271try { 6272 let arr = new Uint8Array([21, 31]); 6273 let entries: distributedKVStore.Entry[] = []; 6274 for (let i = 0; i < 10; i++) { 6275 let key = 'batch_test_bool_key'; 6276 let entry: distributedKVStore.Entry = { 6277 key: key + i, 6278 value: { 6279 type: distributedKVStore.ValueType.BYTE_ARRAY, 6280 value: arr 6281 } 6282 } 6283 entries.push(entry); 6284 } 6285 console.info(`entries: ${entries}`); 6286 kvStore.putBatch(entries).then(async () => { 6287 console.info('Succeeded in putting batch'); 6288 let query = new distributedKVStore.Query(); 6289 query.deviceId('localDeviceId'); 6290 query.prefixKey("batch_test"); 6291 if (kvStore != null) { 6292 kvStore.getEntries('localDeviceId', query).then((entries: distributedKVStore.Entry[]) => { 6293 console.info('Succeeded in getting entries'); 6294 }).catch((err: BusinessError) => { 6295 console.error(`Failed to get entries.code is ${err.code},message is ${err.message}`); 6296 }); 6297 } 6298 }).catch((err: BusinessError) => { 6299 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6300 }); 6301 console.info('Succeeded in getting entries'); 6302} catch (e) { 6303 let error = e as BusinessError; 6304 console.error(`Failed to get entries.code is ${error.code},message is ${error.message}`); 6305} 6306``` 6307 6308### getResultSet 6309 6310getResultSet(keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 6311 6312从DeviceKVStore数据库中获取本设备具有指定前缀的结果集，使用callback异步回调。 6313 6314**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6315 6316**参数：** 6317 6318| 参数名 | 类型 | 必填 | 说明 | 6319| --------- | ---------------------------------------------------------- | ---- | ------------------------------------ | 6320| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 6321| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回具有指定前缀的结果集。 | 6322 6323**错误码：** 6324 6325以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6326 6327| **错误码ID** | **错误信息** | 6328| ------------ | -------------------------------------- | 6329| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6330| 15100001 | Over max limits. | 6331| 15100003 | Database corrupted. | 6332| 15100005 | Database or result set already closed. | 6333 6334**示例：** 6335 6336```ts 6337import { BusinessError } from '@kit.BasicServicesKit'; 6338 6339try { 6340 let resultSet: distributedKVStore.KVStoreResultSet; 6341 let entries: distributedKVStore.Entry[] = []; 6342 for (let i = 0; i < 10; i++) { 6343 let key = 'batch_test_string_key'; 6344 let entry: distributedKVStore.Entry = { 6345 key: key + i, 6346 value: { 6347 type: distributedKVStore.ValueType.STRING, 6348 value: 'batch_test_string_value' 6349 } 6350 } 6351 entries.push(entry); 6352 } 6353 kvStore.putBatch(entries, async (err: BusinessError) => { 6354 if (err != undefined) { 6355 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6356 return; 6357 } 6358 console.info('Succeeded in putting batch'); 6359 if (kvStore != null) { 6360 kvStore.getResultSet('batch_test_string_key', async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 6361 if (err != undefined) { 6362 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6363 return; 6364 } 6365 console.info('Succeeded in getting result set'); 6366 resultSet = result; 6367 if (kvStore != null) { 6368 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 6369 if (err != undefined) { 6370 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 6371 return; 6372 } 6373 console.info('Succeeded in closing result set'); 6374 }) 6375 } 6376 }); 6377 } 6378 }); 6379} catch (e) { 6380 let error = e as BusinessError; 6381 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 6382} 6383``` 6384 6385### getResultSet 6386 6387getResultSet(keyPrefix: string): Promise<KVStoreResultSet> 6388 6389从DeviceKVStore数据库中获取本设备具有指定前缀的结果集，使用Promise异步回调。 6390 6391**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6392 6393**参数：** 6394 6395| 参数名 | 类型 | 必填 | 说明 | 6396| --------- | ------ | ---- | -------------------- | 6397| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 6398 6399**返回值：** 6400 6401| 类型 | 说明 | 6402| ---------------------------------------------------- | --------------------------------------- | 6403| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回具有指定前缀的结果集。 | 6404 6405**错误码：** 6406 6407以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6408 6409| **错误码ID** | **错误信息** | 6410| ------------ | -------------------------------------- | 6411| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6412| 15100001 | Over max limits. | 6413| 15100003 | Database corrupted. | 6414| 15100005 | Database or result set already closed. | 6415 6416**示例：** 6417 6418```ts 6419import { BusinessError } from '@kit.BasicServicesKit'; 6420 6421try { 6422 let resultSet: distributedKVStore.KVStoreResultSet; 6423 let entries: distributedKVStore.Entry[] = []; 6424 for (let i = 0; i < 10; i++) { 6425 let key = 'batch_test_string_key'; 6426 let entry: distributedKVStore.Entry = { 6427 key: key + i, 6428 value: { 6429 type: distributedKVStore.ValueType.STRING, 6430 value: 'batch_test_string_value' 6431 } 6432 } 6433 entries.push(entry); 6434 } 6435 kvStore.putBatch(entries).then(async () => { 6436 console.info('Succeeded in putting batch'); 6437 }).catch((err: BusinessError) => { 6438 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6439 }); 6440 kvStore.getResultSet('batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 6441 console.info('Succeeded in getting result set'); 6442 resultSet = result; 6443 if (kvStore != null) { 6444 kvStore.closeResultSet(resultSet).then(() => { 6445 console.info('Succeeded in closing result set'); 6446 }).catch((err: BusinessError) => { 6447 console.error(`Failed to close resultset.code is ${err.code},message is ${err.message}`); 6448 }); 6449 } 6450 }).catch((err: BusinessError) => { 6451 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6452 }); 6453} catch (e) { 6454 let error = e as BusinessError; 6455 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 6456} 6457``` 6458 6459### getResultSet 6460 6461getResultSet(deviceId: string, keyPrefix: string, callback: AsyncCallback<KVStoreResultSet>): void 6462 6463获取与指定设备ID和Key前缀匹配的KVStoreResultSet对象，使用callback异步回调。 6464> **说明：** 6465> 6466> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6467> deviceId具体获取方式请参考[sync接口示例](#sync)。 6468 6469**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6470 6471**参数：** 6472 6473| 参数名 | 类型 | 必填 | 说明 | 6474| --------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 6475| deviceId | string | 是 | 标识要查询其数据的设备。 | 6476| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 6477| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回与指定设备ID和Key前缀匹配的KVStoreResultSet对象。 | 6478 6479**错误码：** 6480 6481以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6482 6483| **错误码ID** | **错误信息** | 6484| ------------ | -------------------------------------- | 6485| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6486| 15100001 | Over max limits. | 6487| 15100003 | Database corrupted. | 6488| 15100005 | Database or result set already closed. | 6489 6490**示例：** 6491 6492```ts 6493import { BusinessError } from '@kit.BasicServicesKit'; 6494 6495try { 6496 let resultSet: distributedKVStore.KVStoreResultSet; 6497 kvStore.getResultSet('localDeviceId', 'batch_test_string_key', async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 6498 if (err != undefined) { 6499 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6500 return; 6501 } 6502 console.info('Succeeded in getting resultSet'); 6503 resultSet = result; 6504 if (kvStore != null) { 6505 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 6506 if (err != undefined) { 6507 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6508 return; 6509 } 6510 console.info('Succeeded in closing resultSet'); 6511 }) 6512 } 6513 }); 6514} catch (e) { 6515 let error = e as BusinessError; 6516 console.error(`Failed to get resultSet.code is ${error.code},message is ${error.message}`); 6517} 6518``` 6519 6520### getResultSet 6521 6522getResultSet(deviceId: string, keyPrefix: string): Promise<KVStoreResultSet> 6523 6524获取与指定设备ID和Key前缀匹配的KVStoreResultSet对象，使用Promise异步回调。 6525> **说明：** 6526> 6527> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6528> deviceId具体获取方式请参考[sync接口示例](#sync)。 6529 6530**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6531 6532**参数：** 6533 6534| 参数名 | 类型 | 必填 | 说明 | 6535| --------- | -------- | ---- | ------------------------ | 6536| deviceId | string | 是 | 标识要查询其数据的设备。 | 6537| keyPrefix | string | 是 | 表示要匹配的键前缀。不能包含'^'，包含'^'将导致谓词失效，查询结果会返回数据库中的所有数据。 | 6538 6539**返回值：** 6540 6541| 类型 | 说明 | 6542| ------------------------------------------------------ | ------------------------------------------------------------ | 6543| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回与指定设备ID和Key前缀匹配的KVStoreResultSet对象。 | 6544 6545**错误码：** 6546 6547以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6548 6549| **错误码ID** | **错误信息** | 6550| ------------ | -------------------------------------- | 6551| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6552| 15100001 | Over max limits. | 6553| 15100003 | Database corrupted. | 6554| 15100005 | Database or result set already closed. | 6555 6556**示例：** 6557 6558<!--code_no_check--> 6559```ts 6560import { BusinessError } from '@kit.BasicServicesKit'; 6561 6562try { 6563 let resultSet: distributedKVStore.KVStoreResultSet; 6564 kvStore.getResultSet('localDeviceId', 'batch_test_string_key').then((result: distributedKVStore.KVStoreResultSet) => { 6565 console.info('Succeeded in getting resultSet'); 6566 resultSet = result; 6567 if (kvStore != null) { 6568 kvStore.closeResultSet(resultSet).then(() => { 6569 console.info('Succeeded in closing resultSet'); 6570 }).catch((err: BusinessError) => { 6571 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6572 }); 6573 } 6574 }).catch((err: BusinessError) => { 6575 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6576 }); 6577} catch (e) { 6578 let error = e as BusinessError; 6579 console.error(`Failed to get resultSet.code is ${error.code},message is ${error.message}`); 6580} 6581``` 6582 6583### getResultSet 6584 6585getResultSet(deviceId: string, query: Query, callback: AsyncCallback<KVStoreResultSet>): void 6586 6587获取与指定设备ID和Query对象匹配的KVStoreResultSet对象，使用callback异步回调。 6588> **说明：** 6589> 6590> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6591> deviceId具体获取方式请参考[sync接口示例](#sync)。 6592 6593**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6594 6595**参数：** 6596 6597| 参数名 | 类型 | 必填 | 说明 | 6598| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 6599| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 6600| query | [Query](#query) | 是 | 表示查询对象。 | 6601| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | 6602 6603**错误码：** 6604 6605以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6606 6607| **错误码ID** | **错误信息** | 6608| ------------ | -------------------------------------- | 6609| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6610| 15100001 | Over max limits. | 6611| 15100003 | Database corrupted. | 6612| 15100005 | Database or result set already closed. | 6613 6614**示例：** 6615 6616```ts 6617import { BusinessError } from '@kit.BasicServicesKit'; 6618 6619try { 6620 let resultSet: distributedKVStore.KVStoreResultSet; 6621 let entries: distributedKVStore.Entry[] = []; 6622 for (let i = 0; i < 10; i++) { 6623 let key = 'batch_test_string_key'; 6624 let entry: distributedKVStore.Entry = { 6625 key: key + i, 6626 value: { 6627 type: distributedKVStore.ValueType.STRING, 6628 value: 'batch_test_string_value' 6629 } 6630 } 6631 entries.push(entry); 6632 } 6633 kvStore.putBatch(entries, async (err: BusinessError) => { 6634 if (err != undefined) { 6635 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6636 return; 6637 } 6638 console.info('Succeeded in putting batch'); 6639 const query = new distributedKVStore.Query(); 6640 query.prefixKey("batch_test"); 6641 if (kvStore != null) { 6642 kvStore.getResultSet('localDeviceId', query, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 6643 if (err != undefined) { 6644 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6645 return; 6646 } 6647 console.info('Succeeded in getting resultSet'); 6648 resultSet = result; 6649 if (kvStore != null) { 6650 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 6651 if (err != undefined) { 6652 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6653 return; 6654 } 6655 console.info('Succeeded in closing resultSet'); 6656 }) 6657 } 6658 }); 6659 } 6660 }); 6661} catch (e) { 6662 let error = e as BusinessError; 6663 console.error(`Failed to get resultSet.code is ${error.code},message is ${error.message}`); 6664} 6665``` 6666 6667### getResultSet 6668 6669getResultSet(deviceId: string, query: Query): Promise<KVStoreResultSet> 6670 6671获取与指定设备ID和Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 6672> **说明：** 6673> 6674> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6675> deviceId具体获取方式请参考[sync接口示例](#sync)。 6676 6677**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 6678 6679**参数：** 6680 6681| 参数名 | 类型 | 必填 | 说明 | 6682| -------- | -------------- | ---- | ---------------------------------- | 6683| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 6684| query | [Query](#query) | 是 | 表示查询对象。 | 6685 6686**返回值：** 6687 6688| 类型 | 说明 | 6689| ------------------------------------------------------ | ------------------------------------------------------------ | 6690| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。返回与指定设备ID和Query对象匹配的KVStoreResultSet对象。 | 6691 6692**错误码：** 6693 6694以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6695 6696| **错误码ID** | **错误信息** | 6697| ------------ | -------------------------------------- | 6698| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6699| 15100001 | Over max limits. | 6700| 15100003 | Database corrupted. | 6701| 15100005 | Database or result set already closed. | 6702 6703**示例：** 6704 6705<!--code_no_check--> 6706```ts 6707import { BusinessError } from '@kit.BasicServicesKit'; 6708 6709try { 6710 let resultSet: distributedKVStore.KVStoreResultSet; 6711 let entries: distributedKVStore.Entry[] = []; 6712 for (let i = 0; i < 10; i++) { 6713 let key = 'batch_test_string_key'; 6714 let entry: distributedKVStore.Entry = { 6715 key: key + i, 6716 value: { 6717 type: distributedKVStore.ValueType.STRING, 6718 value: 'batch_test_string_value' 6719 } 6720 } 6721 entries.push(entry); 6722 } 6723 kvStore.putBatch(entries).then(async () => { 6724 console.info('Succeeded in putting batch'); 6725 }).catch((err: BusinessError) => { 6726 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6727 }); 6728 const query = new distributedKVStore.Query(); 6729 query.prefixKey("batch_test"); 6730 if (kvStore != null) { 6731 kvStore.getResultSet('localDeviceId', query).then((result: distributedKVStore.KVStoreResultSet) => { 6732 console.info('Succeeded in getting resultSet'); 6733 resultSet = result; 6734 if (kvStore != null) { 6735 kvStore.closeResultSet(resultSet).then(() => { 6736 console.info('Succeeded in closing resultSet'); 6737 }).catch((err: BusinessError) => { 6738 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6739 }); 6740 } 6741 }).catch((err: BusinessError) => { 6742 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6743 }); 6744 } 6745 query.deviceId('localDeviceId'); 6746 console.info("GetResultSet " + query.getSqlLike()); 6747 6748} catch (e) { 6749 let error = e as BusinessError; 6750 console.error(`Failed to get resultSet.code is ${error.code},message is ${error.message}`); 6751} 6752``` 6753 6754### getResultSet 6755 6756getResultSet(query: Query): Promise<KVStoreResultSet> 6757 6758获取与本设备指定Query对象匹配的KVStoreResultSet对象，使用Promise异步回调。 6759 6760**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6761 6762**参数：** 6763 6764| 参数名 | 类型 | 必填 | 说明 | 6765| ------ | -------------- | ---- | -------------- | 6766| query | [Query](#query) | 是 | 表示查询对象。 | 6767 6768**返回值：** 6769 6770| 类型 | 说明 | 6771| ---------------------------------------------------- | ------------------------------------------------------------ | 6772| Promise<[KVStoreResultSet](#kvstoreresultset)> | Promise对象。获取与本设备指定Query对象匹配的KVStoreResultSet对象。 | 6773 6774**错误码：** 6775 6776以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6777 6778| **错误码ID** | **错误信息** | 6779| ------------ | -------------------------------------- | 6780| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6781| 15100001 | Over max limits. | 6782| 15100003 | Database corrupted. | 6783| 15100005 | Database or result set already closed. | 6784 6785**示例：** 6786 6787```ts 6788import { BusinessError } from '@kit.BasicServicesKit'; 6789 6790try { 6791 let resultSet: distributedKVStore.KVStoreResultSet; 6792 let entries: distributedKVStore.Entry[] = []; 6793 for (let i = 0; i < 10; i++) { 6794 let key = 'batch_test_string_key'; 6795 let entry: distributedKVStore.Entry = { 6796 key: key + i, 6797 value: { 6798 type: distributedKVStore.ValueType.STRING, 6799 value: 'batch_test_string_value' 6800 } 6801 } 6802 entries.push(entry); 6803 } 6804 kvStore.putBatch(entries).then(async () => { 6805 console.info('Succeeded in putting batch'); 6806 }).catch((err: BusinessError) => { 6807 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6808 }); 6809 const query = new distributedKVStore.Query(); 6810 query.prefixKey("batch_test"); 6811 kvStore.getResultSet(query).then((result: distributedKVStore.KVStoreResultSet) => { 6812 console.info('Succeeded in getting result set'); 6813 resultSet = result; 6814 }).catch((err: BusinessError) => { 6815 console.error(`Failed to get resultset.code is ${err.code},message is ${err.message}`); 6816 }); 6817} catch (e) { 6818 let error = e as BusinessError; 6819 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 6820} 6821``` 6822 6823### getResultSet 6824 6825getResultSet(query: Query, callback:AsyncCallback<KVStoreResultSet>): void 6826 6827获取与本设备指定Query对象匹配的KVStoreResultSet对象，使用callback异步回调。 6828> **说明：** 6829> 6830> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 6831> deviceId具体获取方式请参考[sync接口示例](#sync)。 6832 6833**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6834 6835**参数：** 6836 6837| 参数名 | 类型 | 必填 | 说明 | 6838| -------- | -------------- | ---- | ---------------------------------- | 6839| query | [Query](#query) | 是 | 表示查询对象。 | 6840| callback | AsyncCallback<[KVStoreResultSet](#kvstoreresultset)> | 是 | 回调函数，获取与指定Predicates对象匹配的KVStoreResultSet对象。 | 6841 6842 6843**错误码：** 6844 6845以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6846 6847| **错误码ID** | **错误信息** | 6848| ------------ | -------------------------------------- | 6849| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types.| 6850| 15100001 | Over max limits. | 6851| 15100003 | Database corrupted. | 6852| 15100005 | Database or result set already closed. | 6853 6854**示例：** 6855 6856```ts 6857import { BusinessError } from '@kit.BasicServicesKit'; 6858 6859try { 6860 let resultSet: distributedKVStore.KVStoreResultSet; 6861 let entries: distributedKVStore.Entry[] = []; 6862 for (let i = 0; i < 10; i++) { 6863 let key = 'batch_test_string_key'; 6864 let entry: distributedKVStore.Entry = { 6865 key: key + i, 6866 value: { 6867 type: distributedKVStore.ValueType.STRING, 6868 value: 'batch_test_string_value' 6869 } 6870 } 6871 entries.push(entry); 6872 } 6873 kvStore.putBatch(entries, async (err: BusinessError) => { 6874 if (err != undefined) { 6875 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 6876 return; 6877 } 6878 console.info('Succeeded in putting batch'); 6879 const query = new distributedKVStore.Query(); 6880 query.prefixKey("batch_test"); 6881 if (kvStore != null) { 6882 kvStore.getResultSet(query, async (err: BusinessError, result: distributedKVStore.KVStoreResultSet) => { 6883 if (err != undefined) { 6884 console.error(`Failed to get resultSet.code is ${err.code},message is ${err.message}`); 6885 return; 6886 } 6887 console.info('Succeeded in getting resultSet'); 6888 resultSet = result; 6889 if (kvStore != null) { 6890 kvStore.closeResultSet(resultSet, (err: BusinessError) => { 6891 if (err != undefined) { 6892 console.error(`Failed to close resultSet.code is ${err.code},message is ${err.message}`); 6893 return; 6894 } 6895 console.info('Succeeded in closing resultSet'); 6896 }) 6897 } 6898 }); 6899 } 6900 }); 6901} catch (e) { 6902 let error = e as BusinessError; 6903 console.error(`Failed to get resultSet`); 6904} 6905``` 6906 6907### getResultSize 6908 6909getResultSize(query: Query, callback: AsyncCallback<number>): void 6910 6911获取与本设备指定Query对象匹配的结果数，使用callback异步回调。 6912 6913**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6914 6915**参数：** 6916 6917| 参数名 | 类型 | 必填 | 说明 | 6918| -------- | --------------------------- | ---- | ------------------------------------------------- | 6919| query | [Query](#query) | 是 | 表示查询对象。 | 6920| callback | AsyncCallback<number> | 是 | 回调函数。返回与本设备指定Query对象匹配的结果数。 | 6921 6922**错误码：** 6923 6924以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6925 6926| **错误码ID** | **错误信息** | 6927| ------------ | -------------------------------------- | 6928| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 6929| 15100003 | Database corrupted. | 6930| 15100005 | Database or result set already closed. | 6931 6932**示例：** 6933 6934```ts 6935import { BusinessError } from '@kit.BasicServicesKit'; 6936 6937try { 6938 let entries: distributedKVStore.Entry[] = []; 6939 for (let i = 0; i < 10; i++) { 6940 let key = 'batch_test_string_key'; 6941 let entry: distributedKVStore.Entry = { 6942 key: key + i, 6943 value: { 6944 type: distributedKVStore.ValueType.STRING, 6945 value: 'batch_test_string_value' 6946 } 6947 } 6948 entries.push(entry); 6949 } 6950 kvStore.putBatch(entries, (err: BusinessError) => { 6951 console.info('Succeeded in putting batch'); 6952 const query = new distributedKVStore.Query(); 6953 query.prefixKey("batch_test"); 6954 if (kvStore != null) { 6955 kvStore.getResultSize(query, (err: BusinessError, resultSize: number) => { 6956 if (err != undefined) { 6957 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 6958 return; 6959 } 6960 console.info('Succeeded in getting result set size'); 6961 }); 6962 } 6963 }); 6964} catch (e) { 6965 let error = e as BusinessError; 6966 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 6967} 6968``` 6969 6970### getResultSize 6971 6972getResultSize(query: Query): Promise<number> 6973 6974获取与本设备指定Query对象匹配的结果数，使用Promise异步回调。 6975 6976**系统能力：** SystemCapability.DistributedDataManager.KVStore.Core 6977 6978**参数：** 6979 6980| 参数名 | 类型 | 必填 | 说明 | 6981| ------ | -------------- | ---- | -------------- | 6982| query | [Query](#query) | 是 | 表示查询对象。 | 6983 6984**返回值：** 6985 6986| 类型 | 说明 | 6987| --------------------- | ---------------------------------------------------- | 6988| Promise<number> | Promise对象。获取与本设备指定Query对象匹配的结果数。 | 6989 6990**错误码：** 6991 6992以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 6993 6994| **错误码ID** | **错误信息** | 6995| ------------ | -------------------------------------- | 6996| 401 | Parameter error. Possible causes:1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 6997| 15100003 | Database corrupted. | 6998| 15100005 | Database or result set already closed. | 6999 7000**示例：** 7001 7002```ts 7003import { BusinessError } from '@kit.BasicServicesKit'; 7004 7005try { 7006 let entries: distributedKVStore.Entry[] = []; 7007 for (let i = 0; i < 10; i++) { 7008 let key = 'batch_test_string_key'; 7009 let entry: distributedKVStore.Entry = { 7010 key: key + i, 7011 value: { 7012 type: distributedKVStore.ValueType.STRING, 7013 value: 'batch_test_string_value' 7014 } 7015 } 7016 entries.push(entry); 7017 } 7018 kvStore.putBatch(entries).then(async () => { 7019 console.info('Succeeded in putting batch'); 7020 }).catch((err: BusinessError) => { 7021 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 7022 }); 7023 const query = new distributedKVStore.Query(); 7024 query.prefixKey("batch_test"); 7025 kvStore.getResultSize(query).then((resultSize: number) => { 7026 console.info('Succeeded in getting result set size'); 7027 }).catch((err: BusinessError) => { 7028 console.error(`Failed to get result size.code is ${err.code},message is ${err.message}`); 7029 }); 7030} catch (e) { 7031 let error = e as BusinessError; 7032 console.error(`An unexpected error occurred.code is ${error.code},message is ${error.message}`); 7033} 7034``` 7035 7036### getResultSize 7037 7038getResultSize(deviceId: string, query: Query, callback: AsyncCallback<number>): void; 7039 7040获取与指定设备ID和Query对象匹配的结果数，使用callback异步回调。 7041> **说明：** 7042> 7043> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 7044> deviceId具体获取方式请参考[sync接口示例](#sync)。 7045 7046**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 7047 7048**参数：** 7049 7050| 参数名 | 类型 | 必填 | 说明 | 7051| -------- | --------------------------- | ---- | --------------------------------------------------- | 7052| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 7053| query | [Query](#query) | 是 | 表示查询对象。 | 7054| callback | AsyncCallback<number> | 是 | 回调函数。返回与指定设备ID和Query对象匹配的结果数。 | 7055 7056**错误码：** 7057 7058以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 7059 7060| **错误码ID** | **错误信息** | 7061| ------------ | -------------------------------------- | 7062| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 7063| 15100003 | Database corrupted. | 7064| 15100004 | Not found. | 7065| 15100005 | Database or result set already closed. | 7066 7067**示例：** 7068 7069```ts 7070import { BusinessError } from '@kit.BasicServicesKit'; 7071 7072try { 7073 let entries: distributedKVStore.Entry[] = []; 7074 for (let i = 0; i < 10; i++) { 7075 let key = 'batch_test_string_key'; 7076 let entry: distributedKVStore.Entry = { 7077 key: key + i, 7078 value: { 7079 type: distributedKVStore.ValueType.STRING, 7080 value: 'batch_test_string_value' 7081 } 7082 } 7083 entries.push(entry); 7084 } 7085 kvStore.putBatch(entries, (err: BusinessError) => { 7086 if (err != undefined) { 7087 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 7088 return; 7089 } 7090 console.info('Succeeded in putting batch'); 7091 const query = new distributedKVStore.Query(); 7092 query.prefixKey("batch_test"); 7093 if (kvStore != null) { 7094 kvStore.getResultSize('localDeviceId', query, (err: BusinessError, resultSize: number) => { 7095 if (err != undefined) { 7096 console.error(`Failed to get resultSize.code is ${err.code},message is ${err.message}`); 7097 return; 7098 } 7099 console.info('Succeeded in getting resultSize'); 7100 }); 7101 } 7102 }); 7103} catch (e) { 7104 let error = e as BusinessError; 7105 console.error(`Failed to get resultSize.code is ${error.code},message is ${error.message}`); 7106} 7107``` 7108 7109### getResultSize 7110 7111getResultSize(deviceId: string, query: Query): Promise<number> 7112 7113获取与指定设备ID和Query对象匹配的结果数，使用Promise异步回调。 7114> **说明：** 7115> 7116> 其中deviceId通过调用[deviceManager.getAvailableDeviceListSync](../apis-distributedservice-kit/js-apis-distributedDeviceManager.md#getavailabledevicelistsync)方法得到。 7117> deviceId具体获取方式请参考[sync接口示例](#sync)。 7118 7119**系统能力：** SystemCapability.DistributedDataManager.KVStore.DistributedKVStore 7120 7121**参数：** 7122 7123| 参数名 | 类型 | 必填 | 说明 | 7124| -------- | -------------- | ---- | ---------------------------------- | 7125| deviceId | string | 是 | KVStoreResultSet对象所属的设备ID。 | 7126| query | [Query](#query) | 是 | 表示查询对象。 | 7127 7128**返回值：** 7129 7130| 类型 | 说明 | 7131| --------------------- | ------------------------------------------------------ | 7132| Promise<number> | Promise对象。返回与指定设备ID和Query对象匹配的结果数。 | 7133 7134**错误码：** 7135 7136以下错误码的详细介绍请参见[分布式键值数据库错误码](errorcode-distributedKVStore.md)和[通用错误码](../errorcode-universal.md)。 7137 7138| **错误码ID** | **错误信息** | 7139| ------------ | -------------------------------------- | 7140| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameters types. | 7141| 15100003 | Database corrupted. | 7142| 15100004 | Not found. | 7143| 15100005 | Database or result set already closed. | 7144 7145**示例：** 7146 7147```ts 7148import { BusinessError } from '@kit.BasicServicesKit'; 7149 7150try { 7151 let entries: distributedKVStore.Entry[] = []; 7152 for (let i = 0; i < 10; i++) { 7153 let key = 'batch_test_string_key'; 7154 let entry: distributedKVStore.Entry = { 7155 key: key + i, 7156 value: { 7157 type: distributedKVStore.ValueType.STRING, 7158 value: 'batch_test_string_value' 7159 } 7160 } 7161 entries.push(entry); 7162 } 7163 kvStore.putBatch(entries).then(async () => { 7164 console.info('Succeeded in putting batch'); 7165 }).catch((err: BusinessError) => { 7166 console.error(`Failed to put batch.code is ${err.code},message is ${err.message}`); 7167 }); 7168 let query = new distributedKVStore.Query(); 7169 query.prefixKey("batch_test"); 7170 kvStore.getResultSize('localDeviceId', query).then((resultSize: number) => { 7171 console.info('Succeeded in getting resultSize'); 7172 }).catch((err: BusinessError) => { 7173 console.error(`Failed to get resultSize.code is ${err.code},message is ${err.message}`); 7174 }); 7175} catch (e) { 7176 let error = e as BusinessError; 7177 console.error(`Failed to get resultSize.code is ${error.code},message is ${error.message}`); 7178} 7179``` 7180