@ohos.data.storage (Lightweight Data Storage)

The DataStorage module provides applications with data processing capability and allows applications to perform lightweight data storage and query. Data is stored in key-value (KV) pairs. Keys are of the string type, and values can be of the number, string, or Boolean type.

NOTE

• The initial APIs of this module are supported since API version 6. Newly added APIs will be marked with a superscript to indicate their earliest API version.

• The APIs of this module are no longer maintained since API version 9. You are advised to use @ohos.data.preferences.

• The APIs of this module can be used only in the FA model.

Modules to Import

import data_storage from '@ohos.data.storage';

Constants

System capability: SystemCapability.DistributedDataManager.Preferences.Core

data_storage.getStorageSync

getStorageSync(path: string): Storage

Reads the specified file and loads its data to the Storage instance for data operations.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  let storage = data_storage.getStorageSync(path + '/mystore');
  storage.putSync('startup', 'auto');
  storage.flushSync();
});

data_storage.getStorage

getStorage(path: string, callback: AsyncCallback<Storage>): void

Reads the specified file and loads its data to the Storage instance for data operations. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  data_storage.getStorage(path + '/mystore', function (err, storage) {
    if (err) {
      console.info("Failed to get the storage. path: " + path + '/mystore');
      return;
    }
    storage.putSync('startup', 'auto');
    storage.flushSync();
  })
});

data_storage.getStorage

getStorage(path: string): Promise<Storage>

Reads the specified file and loads its data to the Storage instance for data operations. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  let getPromise = data_storage.getStorage(path + '/mystore');
  getPromise.then((storage) => {
    storage.putSync('startup', 'auto');
    storage.flushSync();
  }).catch((err) => {
    console.info("Failed to get the storage. path: " + path + '/mystore');
  })
});

data_storage.deleteStorageSync

deleteStorageSync(path: string): void

Deletes the singleton Storage instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the Storage instance cannot be used for data operations. Otherwise, data inconsistency will occur.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
    path = filePath;
    console.info("======================>getFilesDirPromise====================>");

    data_storage.deleteStorageSync(path + '/mystore');
});

data_storage.deleteStorage

deleteStorage(path: string, callback: AsyncCallback<void>): void

Deletes the singleton Storage instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the Storage instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  data_storage.deleteStorage(path + '/mystore', function (err) {
    if (err) {
      console.info("Failed to delete the storage with err: " + err);
      return;
    }
    console.info("Succeeded in deleting the storage.");
  })
});

data_storage.deleteStorage

deleteStorage(path: string): Promise<void>

Deletes the singleton Storage instance of a file from the memory, and deletes the specified file, its backup file, and damaged files. After the specified files are deleted, the Storage instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  let promisedelSt = data_storage.deleteStorage(path + '/mystore');
  promisedelSt.then(() => {
    console.info("Succeeded in deleting the storage.");
  }).catch((err) => {
    console.info("Failed to delete the storage with err: " + err);
  })
});

data_storage.removeStorageFromCacheSync

removeStorageFromCacheSync(path: string): void

Removes the singleton Storage instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
    path = filePath;
    console.info("======================>getFilesDirPromise====================>");

    data_storage.removeStorageFromCacheSync(path + '/mystore');
});

data_storage.removeStorageFromCache

removeStorageFromCache(path: string, callback: AsyncCallback<void>): void

Removes the singleton Storage instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  data_storage.removeStorageFromCache(path + '/mystore', function (err) {
    if (err) {
      console.info("Failed to remove storage from cache with err: " + err);
      return;
    }
    console.info("Succeeded in removing storage from cache.");
  })
});

data_storage.removeStorageFromCache

removeStorageFromCache(path: string): Promise<void>

Removes the singleton Storage instance of a file from the cache. The removed instance cannot be used for data operations. Otherwise, data inconsistency will occur. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

import featureAbility from '@ohos.ability.featureAbility';

let path;
let context = featureAbility.getContext();
context.getFilesDir().then((filePath) => {
  path = filePath;
  console.info("======================>getFilesDirPromise====================>");

  let promiserevSt = data_storage.removeStorageFromCache(path + '/mystore')
  promiserevSt.then(() => {
    console.info("Succeeded in removing storage from cache.");
  }).catch((err) => {
    console.info("Failed to remove storage from cache with err: " + err);
  })
});

Storage

Provides APIs for obtaining and modifying storage data.

getSync

getSync(key: string, defValue: ValueType): ValueType

Obtains the value corresponding to a key. If the value is null or not of the default value type, defValue is returned.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

let value = storage.getSync('startup', 'default');
console.info("The value of startup is " + value);

get

get(key: string, defValue: ValueType, callback: AsyncCallback<ValueType>): void

Obtains the value corresponding to a key. If the value is null or not of the default value type, defValue is returned. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

storage.get('startup', 'default', function(err, value) {
    if (err) {
        console.info("Failed to get the value of startup with err: " + err);
        return;
      }
    console.info("The value of startup is " + value);
})

get

get(key: string, defValue: ValueType): Promise<ValueType>

Obtains the value corresponding to a key. If the value is null or not of the default value type, defValue is returned. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

let promiseget = storage.get('startup', 'default');
promiseget.then((value) => {
    console.info("The value of startup is " + value)
}).catch((err) => {
    console.info("Failed to get the value of startup with err: " + err);
})

putSync

putSync(key: string, value: ValueType): void

Obtains the Storage instance corresponding to the specified file, writes data to the Storage instance using a Storage API, and saves the modification using flush() or flushSync().

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

storage.putSync('startup', 'auto');

put

put(key: string, value: ValueType, callback: AsyncCallback<void>): void

Obtains the Storage instance corresponding to the specified file, writes data to the Storage instance using a Storage API, and saves the modification using flush() or flushSync(). This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

storage.put('startup', 'auto', function (err) {
    if (err) {
        console.info("Failed to put the value of startup with err: " + err);
        return;
    }
    console.info("Succeeded in putting the value of startup.");
})

put

put(key: string, value: ValueType): Promise<void>

Obtains the Storage instance corresponding to the specified file, writes data to the Storage instance using a Storage API, and saves the modification using flush() or flushSync(). This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

let promiseput = storage.put('startup', 'auto');
promiseput.then(() => {
    console.info("Succeeded in putting the value of startup.");
}).catch((err) => {
    console.info("Failed to put the value of startup with err: " + err);
})

hasSync

hasSync(key: string): boolean

Checks whether the storage object contains data with a given key.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

let isExist = storage.hasSync('startup');
if (isExist) {
    console.info("The key of startup is contained.");
}

has

has(key: string, callback: AsyncCallback<boolean>): boolean

Checks whether the storage object contains data with a given key. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

storage.has('startup', function (err, isExist) {
    if (err) {
        console.info("Failed to check the key of startup with err: " + err);
        return;
    }
    if (isExist) {
        console.info("The key of startup is contained.");
    }
})

has

has(key: string): Promise<boolean>

Checks whether the storage object contains data with a given key. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

let promisehas = storage.has('startup')
promisehas.then((isExist) => {
    if (isExist) {
        console.info("The key of startup is contained.");
    }
}).catch((err) => {
    console.info("Failed to check the key of startup with err: " + err);
})

deleteSync

deleteSync(key: string): void

Deletes data with the specified key from this storage object.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

 storage.deleteSync('startup');

delete

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

Deletes data with the specified key from this storage object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

storage.delete('startup', function (err) {
    if (err) {
        console.info("Failed to delete startup key failed err: " + err);
        return;
    }
    console.info("Succeeded in deleting startup key.");
})

delete

delete(key: string): Promise<void>

Deletes data with the specified key from this storage object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Return value

Example

let promisedel = storage.delete('startup')
promisedel.then(() => {
    console.info("Succeeded in deleting startup key.");
}).catch((err) => {
    console.info("Failed to delete startup key failed err: " + err);
})

flushSync

flushSync(): void

Saves the modification of this object to the Storage instance and synchronizes the modification to the file.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Example

storage.flushSync();

flush

flush(callback: AsyncCallback<void>): void

Saves the modification of this object to the Storage instance and synchronizes the modification to the file. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

storage.flush(function (err) {
    if (err) {
        console.info("Failed to flush to file with err: " + err);
        return;
    }
    console.info("Succeeded in flushing to file.");
})

flush

flush(): Promise<void>

Saves the modification of this object to the Storage instance and synchronizes the modification to the file. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Return value

Example

let promiseflush = storage.flush();
promiseflush.then(() => {
    console.info("Succeeded in flushing to file.");
}).catch((err) => {
    console.info("Failed to flush to file with err: " + err);
})

clearSync

clearSync(): void

Clears this Storage object.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Example

storage.clearSync();

clear

clear(callback: AsyncCallback<void>): void

Clears this Storage object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

storage.clear(function (err) {
    if (err) {
        console.info("Failed to clear the storage with err: " + err);
        return;
    }
    console.info("Succeeded in clearing the storage.");
})

clear

clear(): Promise<void>

Clears this Storage object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Return value

Example

let promiseclear = storage.clear();
promiseclear.then(() => {
    console.info("Succeeded in clearing the storage.");
}).catch((err) => {
    console.info("Failed to clear the storage with err: " + err);
})

on('change')

on(type: 'change', callback: Callback<StorageObserver>): void

Subscribes to data changes. The StorageObserver needs to be implemented. When the value of the key subscribed to is changed, a callback will be invoked after flush() or flushSync() is executed.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

let observer = function (key) {
    console.info("The key of " + key + " changed.");
}
storage.on('change', observer);
storage.putSync('startup', 'auto');
storage.flushSync();  // observer will be called.

off('change')

off(type: 'change', callback: Callback<StorageObserver>): void

Unsubscribes from data changes.

System capability: SystemCapability.DistributedDataManager.Preferences.Core

Parameters

Example

let observer = function (key) {
    console.info("The key of " + key + " changed.");
}
storage.off('change', observer);

StorageObserver

System capability: SystemCapability.DistributedDataManager.Preferences.Core

ValueType

Enumerates the value types.

System capability: SystemCapability.DistributedDataManager.Preferences.Core