Persisting KV Store Data

When to Use

The key-value (KV) database stores data in the form of KV pairs. You can use KV stores to store data organized in a simple model, for example, product names and prices or employee IDs and daily attendance. The simple data structure allows higher compatibility with different database versions and device types.

Constraints

• For each record in a device KV store, the key cannot exceed 896 bytes and the value cannot exceed 4 MB.

• For each record in a single KV store, the key cannot exceed 1 KB and the value cannot exceed 4 MB.

• A maximum of 16 distributed KV stores can be opened simultaneously for an application.

• Blocking operations, for example, modifying UI components, are not allowed in the KV store event callbacks.

Available APIs

The following table lists the APIs used for KV data persistence. Most of the APIs are executed asynchronously, using a callback or promise to return the result. The following table uses the callback-based APIs as an example. For more information about the APIs, see Distributed KV Store.

How to Develop

1. Create a KvManager instance to manage database objects.
   Example:

Stage model:

   // Import the module.
   import { distributedKVStore } from '@kit.ArkData';

   // Stage model
   import { window } from '@kit.ArkUI';
   import { UIAbility } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';

   let kvManager: distributedKVStore.KVManager|undefined = undefined;

   export default class EntryAbility extends UIAbility {
     onCreate() {
       let context = this.context;
       const kvManagerConfig: distributedKVStore.KVManagerConfig = {
         context: context,
         bundleName: 'com.example.datamanagertest'
       };
       try {
         // Create a KVManager instance.
         kvManager = distributedKVStore.createKVManager(kvManagerConfig);
         console.info('Succeeded in creating KVManager.');
         // Create and obtain the database.
         if (kvManager !== undefined) {
           kvManager = kvManager as distributedKVStore.KVManager;
          // Perform subsequent operations.
          //...
         }
       } catch (e) {
         let error = e as BusinessError;
         console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
       }
     }
   }

FA model:

   // Import the module.
   import { distributedKVStore } from '@kit.ArkData';

   // FA model
   import { featureAbility } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';

   let kvManager: distributedKVStore.KVManager|undefined = undefined;
   let context = featureAbility.getContext(); // Obtain the context.
   const kvManagerConfig: distributedKVStore.KVManagerConfig = {
     context: context,
     bundleName: 'com.example.datamanagertest'
   };
   try {
     kvManager = distributedKVStore.createKVManager(kvManagerConfig);
     console.info('Succeeded in creating KVManager.');
     // Create and obtain the database.
   } catch (e) {
      let error = e as BusinessError;
      console.error(`Failed to create KVManager. Code:${error.code},message:${error.message}`);
   }
   if (kvManager !== undefined) {
     kvManager = kvManager as distributedKVStore.KVManager;
     // Perform subsequent operations.
     //...
   }

1. Create and obtain a KV store.
   Example:

   let kvStore: distributedKVStore.SingleKVStore|undefined = undefined;
   try {
     const options: distributedKVStore.Options = {
       createIfMissing: true,
       encrypt: false,
       backup: false,
       autoSync: false,
       // If kvStoreType is left empty, a device KV store is created by default.
       kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION,
       // Device KV store: kvStoreType: distributedKVStore.KVStoreType.DEVICE_COLLABORATION,
       securityLevel: distributedKVStore.SecurityLevel.S3
     };
     kvManager.getKVStore<distributedKVStore.SingleKVStore>('storeId', options, (err, store: distributedKVStore.SingleKVStore) => {
       if (err) {
         console.error(`Failed to get KVStore: Code:${err.code},message:${err.message}`);
         return;
       }
       console.info('Succeeded in getting KVStore.');
       kvStore = store;
       // Before performing related data operations, obtain a KV store instance.
       if (kvStore !== undefined) {
         kvStore = kvStore as distributedKVStore.SingleKVStore;
           // Perform subsequent operations.
           //...
       }
     });
   } catch (e) {
     let error = e as BusinessError;
     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
   }

1. Call put() to add data to the KV store.
   Example:

   kvStore = kvStore as distributedKVStore.SingleKVStore;
   const KEY_TEST_STRING_ELEMENT = 'key_test_string';
   const VALUE_TEST_STRING_ELEMENT = 'value_test_string';
   try {
     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
       if (err !== undefined) {
         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
         return;
       }
       console.info('Succeeded in putting data.');
     });
   } catch (e) {
     let error = e as BusinessError;
     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
   }

NOTE

The put() method adds a KV pair if the specified key does not exists and changes the value if the the specified key already exists.

1. Call get() to obtain the value of a key.
   Example:

   try {
     kvStore = kvStore as distributedKVStore.SingleKVStore;
     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
       if (err !== undefined) {
         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
         return;
       }
       console.info('Succeeded in putting data.');
       kvStore = kvStore as distributedKVStore.SingleKVStore;
       kvStore.get(KEY_TEST_STRING_ELEMENT, (err, data) => {
         if (err != undefined) {
           console.error(`Failed to get data. Code:${err.code},message:${err.message}`);
           return;
         }
         console.info(`Succeeded in getting data. Data:${data}`);
       });
     });
   } catch (e) {
     let error = e as BusinessError;
     console.error(`Failed to get data. Code:${error.code},message:${error.message}`);
   }

1. Call delete() to delete the data of the specified key.
   Example:

   try {
     kvStore = kvStore as distributedKVStore.SingleKVStore;
     kvStore.put(KEY_TEST_STRING_ELEMENT, VALUE_TEST_STRING_ELEMENT, (err) => {
       if (err !== undefined) {
         console.error(`Failed to put data. Code:${err.code},message:${err.message}`);
         return;
       }
       console.info('Succeeded in putting data.');
       kvStore = kvStore as distributedKVStore.SingleKVStore;
       kvStore.delete(KEY_TEST_STRING_ELEMENT, (err) => {
         if (err !== undefined) {
           console.error(`Failed to delete data. Code:${err.code},message:${err.message}`);
           return;
         }
         console.info('Succeeded in deleting data.');
       });
     });
   } catch (e) {
     let error = e as BusinessError;
     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
   }

1. Close the distributed KV store of the given storeId.
   Example:

   try {
     // appId is the bundle name of the application.
     kvManager = kvManager as distributedKVStore.KVManager;
     kvStore = undefined;
     kvManager.closeKVStore('appId', 'storeId', (err: BusinessError)=> {
       if (err) {
         console.error(`Failed to close KVStore.code is ${err.code},message is ${err.message}`);
         return;
       }
       console.info('Succeeded in closing KVStore');
     });
   } catch (e) {
     let error = e as BusinessError;
     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
   }
   

2. Delete the distributed KV store of the given storeId.
   Example:

   try {
     // appId is the bundle name of the application.
     kvManager = kvManager as distributedKVStore.KVManager;
     kvStore = undefined;
     kvManager.deleteKVStore('appId', 'storeId', (err: BusinessError)=> {
       if (err) {
         console.error(`Failed to delete KVStore.code is ${err.code},message is ${err.message}`);
         return;
       }
       console.info('Succeeded in deleting KVStore');
     });
   } catch (e) {
     let error = e as BusinessError;
     console.error(`An unexpected error occurred. Code:${error.code},message:${error.message}`);
   }
   

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (Ark Data Management)

harmony 鸿蒙Access Control by Device and Data Level

harmony 鸿蒙Application Data Vectorization

harmony 鸿蒙AIP Overview

harmony 鸿蒙Application Data Persistence Overview

harmony 鸿蒙Database Backup and Restore

harmony 鸿蒙Database Encryption

harmony 鸿蒙Introduction to ArkData

harmony 鸿蒙Persisting Graph Store Data (for System Applications Only)

harmony 鸿蒙Persisting User Preferences (ArkTS)