harmony 鸿蒙@ohos.data.relationalStore (RDB Store) (System API)

  • 2025-06-12
  • 浏览 (5)

@ohos.data.relationalStore (RDB Store) (System API)

The relational database (RDB) store manages data based on relational models. It provides a complete mechanism for managing local databases based on the underlying SQLite. To satisfy different needs in complicated scenarios, the RDB store offers a series of APIs for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. The worker threads are not supported. ArkTS supports the following basic data types: number, string, binary data, and boolean. The maximum size of a data record is 2 MB. If a data record exceeds 2 MB, it can be inserted successfully but cannot be read.

The relationalStore module provides the following functions:

  • RdbPredicates: provides predicates indicating the nature, feature, or relationship of a data entity in an RDB store. It is used to define the operation conditions for an RDB store.
  • RdbStore: provides APIs for managing data in an RDB store.
  • ResultSet: provides APIs for accessing the result set obtained from the RDB store.

NOTE

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

  • This topic describes only the system APIs provided by the module. For details about its public APIs, see @ohos.data.relationalStore.

Modules to Import

import { relationalStore } from '@kit.ArkData';

StoreConfig

Defines the configuration of an RDB store.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Name Type Mandatory Description
isSearchable11+ boolean No Whether the RDB store is searchable. The value true means the RDB store is searchable; the value false means the opposite. The default value is false.
System API: This is a system API.
This parameter is supported since API version 11.
haMode12+ HAMode No High availability (HA) mode.
The value SINGLE means data can be written only to a single RDB store. The value MAIN_REPLICA means data can be written to the main and replica RDB stores to ensure HA. However, this mode is not supported in encryption and attach scenarios. The default value is SINGLE. The value MAIN_REPLICA may affect the database write performance.
System API: This is a system API.
This parameter is supported since API version 12.

HAMode12+

Enumerates the HA modes of an RDB store.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Name Value Description
SINGLE 0 Allows data to be written to a single RDB store.
MAIN_REPLICA 1 Allows data to be written to the main and replica RDB stores for HA. This mode is not supported in encryption and attach scenarios.

Reference11+

Represents the reference between tables by field. If table b references table a, table a is the source table and b is the target table.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

System API: This is a system API.

Name Type Mandatory Description
sourceTable string Yes Name of the table referenced.
targetTable string Yes Name of the table that references the source table.
refFields Record Yes Fields referenced. In a KV pair, the key indicates the field in the source table, and the value indicates the field in the target table.

DistributedConfig10+

Defines the configuration of the distributed mode of tables.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Name Type Mandatory Description
references11+ Array<Reference> No References between tables. You can reference multiple fields, and their values must be the same in the source and target tables. By default, database tables are not referenced with each other.
System API: This is a system API.
This parameter is supported since API version 11.

RdbStore

Provides APIs for managing data in an RDB store. Before using the RdbStore APIs, use executeSql to initialize the database table structure and related data.

update

update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void

Updates data based on the specified DataSharePredicates object. This API uses an asynchronous callback to return the result. Due to the limit of the shared memory (max. 2 MB), a single data record cannot exceed 2 MB. Otherwise, the query operation will fail.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table.
values ValuesBucket Yes Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.
predicates dataSharePredicates.DataSharePredicates Yes Update conditions specified by the DataSharePredicates object.
callback AsyncCallback<number> Yes Callback used to return the number of rows updated.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { ValuesBucket } from '@kit.ArkData';

let value1 = "Rose";
let value2 = 22;
let value3 = 200.5;
let value4 = new Uint8Array([1, 2, 3, 4, 5]);

// You can use either of the following:
const valueBucket1: ValuesBucket = {
  'NAME': value1,
  'AGE': value2,
  'SALARY': value3,
  'CODES': value4,
};
const valueBucket2: ValuesBucket = {
  NAME: value1,
  AGE: value2,
  SALARY: value3,
  CODES: value4,
};
const valueBucket3: ValuesBucket = {
  "NAME": value1,
  "AGE": value2,
  "SALARY": value3,
  "CODES": value4,
};

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if(store != undefined) {
  (store as relationalStore.RdbStore).update("EMPLOYEE", valueBucket1, predicates, (err, rows) => {
    if (err) {
      console.error(`Updated failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`Updated row count: ${rows}`);
  })
}

update

update(table: string, values: ValuesBucket, predicates: dataSharePredicates.DataSharePredicates):Promise<number>

Updates data based on the specified DataSharePredicates object. This API uses a promise to return the result. Due to the limit of the shared memory (max. 2 MB), a single data record cannot exceed 2 MB. Otherwise, the query operation will fail.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table.
values ValuesBucket Yes Rows of data to update in the RDB store. The key-value pair is associated with the column name in the target table.
predicates dataSharePredicates.DataSharePredicates Yes Update conditions specified by the DataSharePredicates object.

Return value

Type Description
Promise<number> Promise used to return the number of rows updated.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { ValuesBucket } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

let value1 = "Rose";
let value2 = 22;
let value3 = 200.5;
let value4 = new Uint8Array([1, 2, 3, 4, 5]);

// You can use either of the following:
const valueBucket1: ValuesBucket = {
  'NAME': value1,
  'AGE': value2,
  'SALARY': value3,
  'CODES': value4,
};
const valueBucket2: ValuesBucket = {
  NAME: value1,
  AGE: value2,
  SALARY: value3,
  CODES: value4,
};
const valueBucket3: ValuesBucket = {
  "NAME": value1,
  "AGE": value2,
  "SALARY": value3,
  "CODES": value4,
};

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if(store != undefined) {
  (store as relationalStore.RdbStore).update("EMPLOYEE", valueBucket1, predicates).then(async (rows: Number) => {
    console.info(`Updated row count: ${rows}`);
  }).catch((err: BusinessError) => {
    console.error(`Updated failed, code is ${err.code},message is ${err.message}`);
  })
}

delete

delete(table: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<number>):void

Deletes data from the RDB store based on the specified DataSharePredicates object. This API uses an asynchronous callback to return the result.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table, which cannot be an empty string.
predicates dataSharePredicates.DataSharePredicates Yes Conditions specified by the DataSharePredicates object for deleting data.
callback AsyncCallback<number> Yes Callback used to return the number of rows deleted.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

Example

import { dataSharePredicates } from '@kit.ArkData';

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if(store != undefined) {
  (store as relationalStore.RdbStore).delete("EMPLOYEE", predicates, (err, rows) => {
    if (err) {
      console.error(`Delete failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`Delete rows: ${rows}`);
  })
}

delete

delete(table: string, predicates: dataSharePredicates.DataSharePredicates):Promise<number>

Deletes data from the RDB store based on the specified DataSharePredicates object. This API uses a promise to return the result.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table.
predicates dataSharePredicates.DataSharePredicates Yes Conditions specified by the DataSharePredicates object for deleting data.

Return value

Type Description
Promise<number> Promise used to return the number of rows deleted.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.
14800047 The WAL file size exceeds the default limit.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Lisa");
if(store != undefined) {
  (store as relationalStore.RdbStore).delete("EMPLOYEE", predicates).then((rows: Number) => {
    console.info(`Delete rows: ${rows}`);
  }).catch((err: BusinessError) => {
    console.error(`Delete failed, code is ${err.code},message is ${err.message}`);
  })
}

query10+

query(table: string, predicates: dataSharePredicates.DataSharePredicates, callback: AsyncCallback<ResultSet>):void

Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result. Due to the limit of the shared memory (max. 2 MB), a single data record cannot exceed 2 MB. Otherwise, the query operation will fail.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table.
predicates dataSharePredicates.DataSharePredicates Yes Query conditions specified by the DataSharePredicates object.
callback AsyncCallback<ResultSet> Yes Callback used to return the result. If the operation is successful, a ResultSet object will be returned.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800014 Already closed.
14800015 The database does not respond.

Example

import { dataSharePredicates } from '@kit.ArkData';

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
if(store != undefined) {
  (store as relationalStore.RdbStore).query("EMPLOYEE", predicates, (err, resultSet) => {
    if (err) {
      console.error(`Query failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
    // resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
    while (resultSet.goToNextRow()) {
      const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
      const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
      const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
      const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
      console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
    }
    // Release the dataset memory.
    resultSet.close();
  })
}

query

query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>):void

Queries data from the RDB store based on specified conditions. This API uses an asynchronous callback to return the result. Due to the limit of the shared memory (max. 2 MB), a single data record cannot exceed 2 MB. Otherwise, the query operation will fail.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table.
predicates dataSharePredicates.DataSharePredicates Yes Query conditions specified by the DataSharePredicates object.
columns Array<string> Yes Columns to query. If this parameter is not specified, the query applies to all columns.
callback AsyncCallback<ResultSet> Yes Callback used to return the result. If the operation is successful, a ResultSet object will be returned.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800014 Already closed.
14800015 The database does not respond.

Example

import { dataSharePredicates } from '@kit.ArkData';

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
if(store != undefined) {
  (store as relationalStore.RdbStore).query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"], (err, resultSet) => {
    if (err) {
      console.error(`Query failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
    // resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
    while (resultSet.goToNextRow()) {
      const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
      const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
      const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
      const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
      console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
    }
    // Release the dataset memory.
    resultSet.close();
  })
}

query

query(table: string, predicates: dataSharePredicates.DataSharePredicates, columns?: Array<string>):Promise<ResultSet>

Queries data from the RDB store based on specified conditions. This API uses a promise to return the result. Due to the limit of the shared memory (max. 2 MB), a single data record cannot exceed 2 MB. Otherwise, the query operation will fail.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Model restriction: This API can be used only in the stage model.

System API: This is a system API.

Parameters

Name Type Mandatory Description
table string Yes Name of the target table.
predicates dataSharePredicates.DataSharePredicates Yes Query conditions specified by the DataSharePredicates object.
columns Array<string> No Columns to query. If this parameter is not specified, the query applies to all columns.

Return value

Type Description
Promise<ResultSet> Promise used to return the result. If the operation is successful, a ResultSet object will be returned.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
14800000 Inner error.
14800014 Already closed.
14800015 The database does not respond.

Example

import { dataSharePredicates } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new dataSharePredicates.DataSharePredicates();
predicates.equalTo("NAME", "Rose");
if(store != undefined) {
  (store as relationalStore.RdbStore).query("EMPLOYEE", predicates, ["ID", "NAME", "AGE", "SALARY", "CODES"]).then((resultSet: relationalStore.ResultSet) => {
    console.info(`ResultSet column names: ${resultSet.columnNames}, column count: ${resultSet.columnCount}`);
    // resultSet is a cursor of a data set. By default, the cursor points to the -1st record. Valid data starts from 0.
    while (resultSet.goToNextRow()) {
      const id = resultSet.getLong(resultSet.getColumnIndex("ID"));
      const name = resultSet.getString(resultSet.getColumnIndex("NAME"));
      const age = resultSet.getLong(resultSet.getColumnIndex("AGE"));
      const salary = resultSet.getDouble(resultSet.getColumnIndex("SALARY"));
      console.info(`id=${id}, name=${name}, age=${age}, salary=${salary}`);
    }
    // Release the dataset memory.
    resultSet.close();
  }).catch((err: BusinessError) => {
    console.error(`Query failed, code is ${err.code},message is ${err.message}`);
  })
}

cloudSync11+

cloudSync(mode: SyncMode, predicates: RdbPredicates, progress: Callback<ProgressDetails>, callback: AsyncCallback<void>): void

Manually performs device-cloud sync based on specified conditions. This API uses an asynchronous callback to return the result. The cloud sync function must be implemented. Otherwise, this API cannot be used.

NOTE

Since API version 18, you can specify assets in predicates when performing manual device-cloud sync. In this case, the sync mode must be relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST.

When specifying the predicates, you can use the primary key (mandatory) and asset (optional) as sync conditions. If assets are specified, the predicate supports only equalTo, with a limit of 50 assets. If more assets are involved, you are advised to use only the primary key as the sync condition.

System capability: SystemCapability.DistributedDataManager.CloudSync.Client

System API: This is a system API.

Parameters

Name Type Mandatory Description
mode SyncMode Yes Sync mode of the database.
predicates RdbPredicates Yes Conditions for data sync.
progress Callback<ProgressDetails> Yes Callback used to process database sync details.
callback AsyncCallback<void> Yes Callback used to return the sync result to the caller.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 if permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The tablesNames must be not empty. 5. The progress must be a callback type. 6.The callback must be a function.
801 Capability not supported.
14800014 Already closed.

Example 1: Manually sync data on the local device with the cloud.

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
predicates.in("id", ["id1", "id2"]);

if(store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
   }, (err) => {
     if (err) {
       console.error(`cloudSync failed, code is ${err.code},message is ${err.message}}`);
       return;
     }
     console.info('Cloud sync succeeded');
  });
};

Example 2: Download the specified asset.

import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
let asset : relationalStore.Asset = {
  name: "name",
  uri: "uri",
  path: "path",
  createTime: new Date().getTime().toString(),
  modifyTime: new Date().getTime().toString(),
  size: "1024"
}
// Specify the primary key and asset (asset column in the database) in the predicates.
predicates.beginWrap().equalTo("id", "id1").and().equalTo("asset", asset).endWrap();

if(store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
   }, (err) => {
     if (err) {
       console.error(`cloud sync failed, code is ${err.code},message is ${err.message}}`);
       return;
     }
     console.info('cloud sync succeeded');
  });
};

cloudSync11+

cloudSync(mode: SyncMode, predicates: RdbPredicates, progress: Callback<ProgressDetails>): Promise<void>

Manually performs device-cloud sync based on specified conditions. This API uses a promise to return the result. The cloud sync function must be implemented. Otherwise, this API cannot be used.

NOTE

Since API version 18, you can specify assets in predicates when performing manual device-cloud sync. In this case, the sync mode must be relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST.

When specifying the predicates, you can use the primary key (mandatory) and asset (optional) as sync conditions. If assets are specified, the predicate supports only equalTo, with a limit of 50 assets. If more assets are involved, you are advised to use only the primary key as the sync condition.

System capability: SystemCapability.DistributedDataManager.CloudSync.Client

System API: This is a system API.

Parameters

Name Type Mandatory Description
mode SyncMode Yes Sync mode of the database.
predicates RdbPredicates Yes Conditions for data sync.
progress Callback<ProgressDetails> Yes Callback used to process database sync details.

Return value

Type Description
Promise<void> Promise used to return the sync result.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 if permission verification failed, application which is not a system application uses system API.
401 Parameter error. Possible causes: 1. Need 2 - 4 parameter(s). 2. The RdbStore must be not nullptr. 3. The mode must be a SyncMode of cloud. 4. The tablesNames must be not empty. 5. The progress must be a callback type.
801 Capability not supported.
14800014 Already closed.

Example 1: Manually sync data on the local device with the cloud.

import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
predicates.in("id", ["id1", "id2"]);

if(store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
  }).then(() => {
    console.info('cloud sync succeeded');
  }).catch((err: BusinessError) => {
    console.error(`cloud sync failed, code is ${err.code},message is ${err.message}}`);
  });
};

Example 2: Download the specified asset.

import { BusinessError } from '@kit.BasicServicesKit';

let predicates = new relationalStore.RdbPredicates("EMPLOYEE");
let asset : relationalStore.Asset = {
  name: "name",
  uri: "uri",
  path: "path",
  createTime: new Date().getTime().toString(),
  modifyTime: new Date().getTime().toString(),
  size: "1024"
}
// Specify the primary key and asset (asset column in the database) in the predicates.
predicates.beginWrap().equalTo("id", "id1").and().equalTo("asset", asset).endWrap();

if(store != undefined) {
  (store as relationalStore.RdbStore).cloudSync(relationalStore.SyncMode.SYNC_MODE_CLOUD_FIRST, predicates, (progressDetail: relationalStore.ProgressDetails) => {
    console.info(`progress: ${progressDetail}`);
   }).then(() => {
    console.info('Cloud sync succeeded');
  }).catch((err: BusinessError) => {
    console.error(`cloudSync failed, code is ${err.code},message is ${err.message}}`);
  });
};

querySharingResource11+

querySharingResource(predicates: RdbPredicates, columns?: Array<string>): Promise<ResultSet>

Queries the shared resource of the data matching the specified conditions. This API uses a promise to return the result set, which includes the shared resource ID and the column names if the column names are specified.

System capability: SystemCapability.DistributedDataManager.CloudSync.Client

System API: This is a system API.

Parameters

Name Type Mandatory Description
predicates RdbPredicates Yes Query conditions.
columns Array<string> No Columns to be searched for. If this parameter is not specified, the returned result set contains only the shared resource ID.

Return value

Name Description
Promise<ResultSet> Promise used to return the result set.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The predicates must be an RdbPredicates. 4. The columns must be a string array.
801 Capability not supported.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let sharingResource: string;
let predicates = new relationalStore.RdbPredicates('test_table');
predicates.equalTo('data', 'data_test');
if(store != undefined) {
  (store as relationalStore.RdbStore).querySharingResource(predicates, ['uuid', 'data']).then((resultSet) => {
    if (!resultSet.goToFirstRow()) {
      console.error(`resultSet error`);
      return;
    }
    const res = resultSet.getString(resultSet.getColumnIndex(relationalStore.Field.SHARING_RESOURCE_FIELD));
    console.info(`sharing resource: ${res}`);
    sharingResource = res;
  }).catch((err: BusinessError) => {
    console.error(`query sharing resource failed, code is ${err.code},message is ${err.message}`);
  })
}

querySharingResource11+

querySharingResource(predicates: RdbPredicates, callback: AsyncCallback<ResultSet>): void

Queries the shared resource of the data matching the specified conditions. This API uses an asynchronous callback to return the result set.

System capability: SystemCapability.DistributedDataManager.CloudSync.Client

System API: This is a system API.

Parameters

Name Type Mandatory Description
predicates RdbPredicates Yes Query conditions.
callback AsyncCallback<ResultSet> Yes Callback used to return the result set.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The predicates must be an RdbPredicates. 4. The columns must be a string array.
801 Capability not supported.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

Example

let sharingResource: string;
let predicates = new relationalStore.RdbPredicates('test_table');
predicates.equalTo('data', 'data_test');
if(store != undefined) {
  (store as relationalStore.RdbStore).querySharingResource(predicates,(err, resultSet) => {
    if (err) {
      console.error(`sharing resource failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    if (!resultSet.goToFirstRow()) {
      console.error(`resultSet error`);
      return;
    }
    const res = resultSet.getString(resultSet.getColumnIndex(relationalStore.Field.SHARING_RESOURCE_FIELD));
    console.info(`sharing resource: ${res}`);
    sharingResource = res;
  })
}

querySharingResource11+

querySharingResource(predicates: RdbPredicates, columns: Array<string>, callback: AsyncCallback<ResultSet>): void

Queries the shared resource of the data matching the specified conditions. This API uses an asynchronous callback to return the shared resource ID and the column names specified.

System capability: SystemCapability.DistributedDataManager.CloudSync.Client

System API: This is a system API.

Parameters

Name Type Mandatory Description
predicates RdbPredicates Yes Query conditions.
columns Array<string> Yes Columns to be searched for.
callback AsyncCallback<ResultSet> Yes Callback used to return the result set.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Need 1 - 3 parameter(s)! 2. The RdbStore must be not nullptr. 3. The predicates must be an RdbPredicates. 4. The columns must be a string array.
801 Capability not supported.
14800000 Inner error.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

Example

let sharingResource: string;
let predicates = new relationalStore.RdbPredicates('test_table');
predicates.equalTo('data', 'data_test');
if(store != undefined) {
  (store as relationalStore.RdbStore).querySharingResource(predicates, ['uuid', 'data'], (err, resultSet) => {
    if (err) {
      console.error(`sharing resource failed, code is ${err.code},message is ${err.message}`);
      return;
    }
    if (!resultSet.goToFirstRow()) {
      console.error(`resultSet error`);
      return;
    }
    const res = resultSet.getString(resultSet.getColumnIndex(relationalStore.Field.SHARING_RESOURCE_FIELD));
    console.info(`sharing resource: ${res}`);
    sharingResource = res;
  })
}

lockCloudContainer12+

lockCloudContainer(): Promise<number>

Manually locks the cloud database of an application. This API uses a promise to return the result.

NOTE

After the cloud database is locked, data of the same application logged in with the same account on other devices cannot be synced to the cloud. The cloud sync function must be implemented. Otherwise, this API cannot be used.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

System API: This is a system API.

Return value

Type Description
Promise<number> Promise used to return the lock validity period (in ms) if the operation is successful. If the operation fails, 0 is returned.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.

Example

import { BusinessError } from '@kit.BasicServicesKit';

if(store != undefined) {
  (store as relationalStore.RdbStore).lockCloudContainer().then((time: Number) => {
    console.info('lockCloudContainer succeeded time:' + time);
  }).catch((err: BusinessError) => {
    console.error(`lockCloudContainer failed, code is ${err.code},message is ${err.message}`);
  })
}

unlockCloudContainer12+

unlockCloudContainer(): Promise<void>

Manually unlocks the cloud database of an application. This API uses a promise to return the result. The cloud sync function must be implemented. Otherwise, this API cannot be used.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

System API: This is a system API.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.

Example

import { BusinessError } from '@kit.BasicServicesKit';

if(store != undefined) {
  (store as relationalStore.RdbStore).unlockCloudContainer().then(() => {
    console.info('unlockCloudContainer succeeded');
  }).catch((err: BusinessError) => {
    console.error(`unlockCloudContainer failed, code is ${err.code},message is ${err.message}`);
  })
}

restore12+

restore(): Promise<void>

Restores data from a replica RDB store file. This API uses a promise to return the result. This API can be used only when HAMode is MAIN_REPLICA, and cannot be used in transactions.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

System API: This is a system API.

Return value

Type Description
Promise<void> Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
202 Permission verification failed, application which is not a system application uses system API.
14800000 Inner error.
14800010 Invalid database path.
14800011 Database corrupted.
14800014 Already closed.
14800015 The database does not respond.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

Example

import { BusinessError } from '@kit.BasicServicesKit';

let store: relationalStore.RdbStore|undefined = undefined;
if(store != undefined) {
  let promiseRestore = (store as relationalStore.RdbStore).restore();
  promiseRestore.then(() => {
    console.info('Succeeded in restoring.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to restore, code is ${err.code},message is ${err.message}`);
  })
}

ResultSet

Provides APIs to access the resultSet object returned by query().

getFloat32Array12+

getFloat32Array(columnIndex: number): Float32Array

Obtains the value from the specified column in the current row and outputs it in a Float32Array (array of 32-bit floating-point numbers). This API is available only for a vector store.

System capability: SystemCapability.DistributedDataManager.RelationalStore.Core

Parameters

Name Type Mandatory Description
columnIndex number Yes Index of the target column, starting from 0.

Return value

Type Description
Float32Array Value obtained, in a Float32Array.

Error codes

For details about the error codes, see Universal Error Codes and RDB Store Error Codes.

ID Error Message
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types.
801 The capability is not supported because the database is not a vector DB.
14800011 Database corrupted.
14800013 Column out of bounds.
14800014 Already closed.
14800021 SQLite: Generic error.
14800022 SQLite: Callback routine requested an abort.
14800023 SQLite: Access permission denied.
14800024 SQLite: The database file is locked.
14800025 SQLite: A table in the database is locked.
14800026 SQLite: The database is out of memory.
14800027 SQLite: Attempt to write a readonly database.
14800028 SQLite: Some kind of disk I/O error occurred.
14800029 SQLite: The database is full.
14800030 SQLite: Unable to open the database file.
14800031 SQLite: TEXT or BLOB exceeds size limit.
14800032 SQLite: Abort due to constraint violation.
14800033 SQLite: Data type mismatch.
14800034 SQLite: Library used incorrectly.

Example

let resultSet: relationalStore.ResultSet|undefined;
if(resultSet != undefined) {
  const id = (resultSet as relationalStore.ResultSet).getFloat32Array(0);
}

你可能感兴趣的鸿蒙文章

harmony 鸿蒙ArkData (ArkData Management)

harmony 鸿蒙Data

harmony 鸿蒙OH_Cursor

harmony 鸿蒙OH_Predicates

harmony 鸿蒙OH_Rdb_Config

harmony 鸿蒙OH_Rdb_Store

harmony 鸿蒙OH_VBucket

harmony 鸿蒙OH_VObject

harmony 鸿蒙Preferences

harmony 鸿蒙_r_d_b

0  赞