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