From 0290fd260f402cf3b005eeef5de40de09e9ce9a9 Mon Sep 17 00:00:00 2001 From: annie_wangli Date: Mon, 24 Jan 2022 18:00:53 +0800 Subject: [PATCH 1/3] update docs Signed-off-by: annie_wangli --- en/device-dev/subsystems/Readme-EN.md | 8 ++++---- .../figure/en-us_image_0000001115980740.png | Bin 0 -> 6213 bytes .../subsys-data-relational-database.md | 5 +++++ en/device-dev/subsystems/subsys-data.md | 4 ++++ 4 files changed, 13 insertions(+), 4 deletions(-) create mode 100644 en/device-dev/subsystems/figure/en-us_image_0000001115980740.png create mode 100644 en/device-dev/subsystems/subsys-data-relational-database.md create mode 100644 en/device-dev/subsystems/subsys-data.md diff --git a/en/device-dev/subsystems/Readme-EN.md b/en/device-dev/subsystems/Readme-EN.md index 9cc761113c8..93db19d5a6b 100644 --- a/en/device-dev/subsystems/Readme-EN.md +++ b/en/device-dev/subsystems/Readme-EN.md @@ -39,14 +39,14 @@ - [KWS SDK](subsys-aiframework-demo-sdk.md) - [KWS Plug-in](subsys-aiframework-demo-plugin.md) - [KWS Configuration File](subsys-aiframework-demo-conf.md) +- [Data Management](subsys-database.md) + - [RDB](subsys-database-relational.md) + - [RDB Overview](subsys-database-relational-overview.md) + - [RDB Development](subsys-database-relational-guide.md) - [Sensors](subsys-sensor.md) - [Sensors Overview](subsys-sensor-overview.md) - [Sensors Usage Guidelines](subsys-sensor-guide.md) - [Sensors Usage Example](subsys-sensor-demo.md) -- [USB](subsys-usbservice.md) - - [[USB Overview](subsys-usbservice-overview.md) - - [USB Usage Guidelines](subsys-usbservice-guide.md) - - [USB Usage Example](subsys-usbservice-demo.md) - [Application Framework](subsys-application-framework.md) - [Overview](subsys-application-framework-overview.md) - [Setting Up a Development Environment](subsys-application-framework-envbuild.md) diff --git a/en/device-dev/subsystems/figure/en-us_image_0000001115980740.png b/en/device-dev/subsystems/figure/en-us_image_0000001115980740.png new file mode 100644 index 0000000000000000000000000000000000000000..c343579a89f8e1c8bec5523c843424f89ca1b825 GIT binary patch literal 6213 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 Date: Tue, 25 Jan 2022 20:12:47 +0800 Subject: [PATCH 2/3] update docs Signed-off-by: annie_wangli --- .../subsys-data-relational-database-guide.md | 191 ++++++++++++++++++ ...ubsys-data-relational-database-overview.md | 37 ++++ 2 files changed, 228 insertions(+) create mode 100644 en/device-dev/subsystems/subsys-data-relational-database-guide.md create mode 100644 en/device-dev/subsystems/subsys-data-relational-database-overview.md diff --git a/en/device-dev/subsystems/subsys-data-relational-database-guide.md b/en/device-dev/subsystems/subsys-data-relational-database-guide.md new file mode 100644 index 00000000000..15df71090d0 --- /dev/null +++ b/en/device-dev/subsystems/subsys-data-relational-database-guide.md @@ -0,0 +1,191 @@ +# 关系型数据库开发指导 + +## 场景介绍 + +关系型数据库是在SQLite基础上实现的本地数据操作机制，提供给用户无需编写原生SQL语句就能进行数据增删改查的方法，同时也支持原生SQL语句操作。 + +## 接口说明 +### 数据库的创建和删除 + +关系型数据库提供了数据库创建方式，以及对应的删除接口，涉及的API如下所示。 + +表1 数据库创建和删除API + +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStoreConfig | RdbStoreConfig(const std::string &path,
StorageMode storageMode = StorageMode::MODE_DISK,
bool readOnly = false,
const std::vector &encryptKey = std::vector(),
const std::string &journalMode = "",
const std::string &syncMode = "",
const std::string &databaseFileType = "",
const std::string &databaseFileSecurityLevel = "") | 对数据库进行配置，包括设置数据库名、存储模式、日志模式、同步模式，是否为只读，及数据库加密。
  • path：数据库路径；
  • readOnly：是否只读；
  • storageMode：存储模式；
  • encryptKey：加密密钥;
  • journalMode：日志模式；
  • syncMode：同步模式；
  • databaseFileType：数据库类型；
  • databaseFileSecurityLevel：安全等级
| +| RdbOpenCallback | int OnCreate(RdbStore &rdbStore) | 数据库创建时被回调，开发者可以在该方法中初始化表结构，并添加一些应用使用到的初始化数据。 | +| RdbOpenCallback | int OnUpgrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库升级时被回调。 | +| RdbOpenCallback | int OnDowngrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库降级时被回调。 | +| RdbHelper | std::shared_ptr\ GetRdbStore(const RdbStoreConfig &config, int version, RdbOpenCallback &openCallback, int &errCode) | 根据配置创建或打开数据库。 | +| RdbHelper | int DeleteRdbStore(const std::string &path) | 删除指定的数据库。 | + +### 数据库的加密 + +关系型数据库提供数据库加密的能力，在创建数据库时若指定了密钥，则会创建为加密数据库。再次使用此数据库时，需要指定该密钥，才能正确打开数据库。 + +表2 数据库修改密钥API +| 类名 | 接口名 | 描述 | +| ---- | ---- | ---- | +| RdbStore | int ChangeEncryptKey(const std::vector &newKey) | 为数据库设置新的加密密钥。注：仅支持加密数据库更换加密密钥。 | + +### 数据库谓词的使用 + +关系型数据库提供了用于设置数据库操作条件的谓词AbsRdbPredicates，其中包括两个实现子类RdbPredicates和RawRdbPredicates： + +- RdbPredicates：开发者无需编写复杂的SQL语句，仅通过调用该类中条件相关的方法，如equalTo、notEqualTo、groupBy、orderByAsc、beginsWith等，就可自动完成SQL语句拼接，方便用户聚焦业务操作。 +- RawRdbPredicates：可满足复杂SQL语句的场景，支持开发者自己设置where条件子句和whereArgs参数。不支持equalTo等条件接口的使用。 + + 表7 数据库谓词API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbPredicates | AbsPredicates *EqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值相等。 | + | RdbPredicates | AbsPredicates *NotEqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值不相等。 | + | RdbPredicates | AbsPredicates *BeginsWith(std::string field, std::string value) | 设置谓词条件，满足field字段以value值开头。 | + | RdbPredicates | AbsPredicates *Between(std::string field, std::string low, std::string high) | 设置谓词条件，满足field字段在最小值low和最大值high之间。 | + | RdbPredicates | AbsPredicates *OrderByAsc(std::string field) | 设置谓词条件，根据field字段升序排列。 | + | RdbPredicates | void SetWhereClause(std::string whereClause) | 设置where条件子句。 | + | RdbPredicates | void SetWhereArgs(std::vector\ whereArgs) | 设置whereArgs参数，该值表示where子句中占位符的值。 | + +### 数据表的增删改查 + +关系型数据库提供对本地数据增删改查操作的能力，相关API如下所示。 + +- 新增 + + 关系型数据库提供了插入数据的接口，通过ValuesBucket输入要存储的数据，通过返回值判断是否插入成功，插入成功时返回最新插入数据所在的行号，失败时则返回-1。 + + 表3 数据表插入API + + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | int Insert(int64_t &outRowId, const std::string &table, const ValuesBucket &initialValues) | 向数据库插入数据。
  • table：待添加数据的表名。
  • initialValues：以ValuesBucket存储的待插入的数据。它提供一系列put方法，如PutString(const std::string &columnName, const std::string &value)，PutDouble(const std::string &columnName, double value)，用于向ValuesBucket中添加数据。
| + +- 删除 + + 调用删除接口，通过AbsRdbPredicates指定删除条件。该接口的返回值表示删除的数据行数，可根据此值判断是否删除成功。如果删除失败，则返回0。 + + 表5 数据表删除API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | int Delete(int &deletedRows, const AbsRdbPredicates &predicates) | 删除数据。
  • deletedRows：删除的记录条数。
  • predicates：Rdb谓词，指定了删除操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| + +- 更新 + + 调用更新接口，传入要更新的数据，并通过AbsRdbPredicates指定更新条件。该接口的返回值表示更新操作影响的行数。如果更新失败，则返回0。 + + 表4 数据表更新API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | int Update(int &changedRows, const ValuesBucket &values, const AbsRdbPredicates &predicates) | 更新数据库表中符合谓词指定条件的数据。
  • changedRows：更新的记录条数。
  • values：以ValuesBucket存储的要更新的数据。
  • predicates：指定了更新操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| + +- 查询 + + 关系型数据库提供了两种查询数据的方式： + + - 直接调用查询接口。使用该接口，会将包含查询条件的谓词自动拼接成完整的SQL语句进行查询操作，无需用户传入原生的SQL语句。 + - 执行原生的SQL语句进行查询操作。 + + 表6 数据表查询API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | RdbStore | std::unique_ptr Query(const AbsRdbPredicates &predicates, const std::vector\ columns) | 查询数据。
  • predicates：谓词，可以设置查询条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
  • columns：规定查询返回的列。
| + | RdbStore | std::unique_ptr QuerySql(const std::string &sql, const std::vector\ &selectionArgs = std::vector\()) | 执行原生的用于查询操作的SQL语句。
  • sql：原生用于查询的sql语句。
  • selectionArgs：sql语句中占位符参数的值，若select语句中没有使用占位符，该参数可以设置为null。
| + +### 查询结果集的使用 + +关系型数据库提供了查询返回的结果集ResultSet，其指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ResultSet对外API如下所示。 + + 表8 结果集API + | 类名 | 接口名 | 描述 | + | ---- | ---- | ---- | + | ResultSet | int GoTo(int offset) | 从结果集当前位置移动指定偏移量。 | + | ResultSet | int GoToRow(int position) | 将结果集移动到指定位置。 | + | ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | + | ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | + | ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | + | ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | + | ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | + | ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | + | ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | + | ResultSet | int GetColumnCount(int &count) | 获取结果集中的列数。 | + | ResultSet | int GetString(int columnIndex, std::string &value) | 获取当前行指定列的值，以String类型返回。 | + | ResultSet | int GetBlob(int columnIndex, std::vector\ &blob) | 获取当前行指定列的值，以字节数组形式返回。 | + | ResultSet | int GetDouble(int columnIndex, double &value) | 获取当前行指定列的值，以double型返回。 | + +## 约束与限制 + +无。 + +## 开发步骤 + +1. 创建数据库。 + + a. 配置数据库相关信息，包括数据库的名称、存储模式、是否为只读模式等。 + + b. 初始化数据库表结构和相关数据。 + + c. 创建数据库。 + + 示例代码如下： + ``` + const std::string DATABASE_NAME = RDB_TEST_PATH + "RdbStoreTest.db"; + const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, salary REAL, blobType BLOB)"; + + class OpenCallback : public RdbOpenCallback { + public: + int OnCreate(RdbStore &rdbStore) override; + int OnUpgrade(RdbStore &rdbStore, int oldVersion, int newVersion) override; + }; + + int OpenCallback::OnCreate(RdbStore &store) + { + return store.ExecuteSql(CREATE_TABLE_TEST); + } + + RdbStoreConfig config(DATABASE_NAME); + OpenCallback callback; + + std::shared_ptr store = RdbHelper::GetRdbStore(config, 1, callback, 0); + ``` + +2. 插入数据。 + + a. 构造要插入的数据，以ValuesBucket形式存储。 + + b. 调用关系型数据库提供的插入接口。 + + c. 创建数据库。 + + 示例代码如下： + ``` + ValuesBucket values; + + values.PutInt("id", 1); + values.PutString("name", std::string("Tom")); + values.PutInt("age", 18); + values.PutDouble("salary", 100.5); + values.PutBlob("blobType", std::vector{ 1, 2, 3 }); + store->Insert(id, "test", values); + ``` + +3. 查询数据。 + + a. 构造用于查询的谓词对象，设置查询条件。 + + b. 指定查询返回的数据列。 + + c. 调用查询接口查询数据。 + + d. 调用结果集接口，遍历返回结果。 + + 示例代码如下： + ``` + std::vector columns = {"id", "name", "age", "salary"}; + + RdbPredicates predicates("test"); + predicates.EqualTo("age", "25")->OrderByAsc("salary"); + std::unique_ptr resultSet = store->Query(predicates, columns) + resultSet.goToNextRow(); + ``` + diff --git a/en/device-dev/subsystems/subsys-data-relational-database-overview.md b/en/device-dev/subsystems/subsys-data-relational-database-overview.md new file mode 100644 index 00000000000..e152fd38c14 --- /dev/null +++ b/en/device-dev/subsystems/subsys-data-relational-database-overview.md @@ -0,0 +1,37 @@ +# RDB Overview + +The relational database (RDB) manages data based on relational models. With the underlying SQLite database, the OpenHarmony RDB provides a complete mechanism for managing local databases. To satisfy different needs in complicated scenarios, the RDB offers a series of methods for performing operations such as adding, deleting, modifying, and querying data, and supports direct execution of SQL statements. + +## Basic Concepts + +- RDB + + A type of database created on the basis of relational models. The RDB stores data in rows and columns. + +- Predicate + + A representation of the property or feature of a data entity, or the relationship between data entities. It is mainly used to define operation conditions. + +- Result set + + A set of query results used to access data. You can access the required data in a result set in flexible modes. + +- SQLite database + + A lightweight open-source relational database management system that complies with Atomicity, Consistency, Isolation, and Durability (ACID). + +## Working Principles +The OpenHarmony RDB provides a common operation interface (**RdbStore**) for external systems. It uses the third-party open-source SQLite as the underlying persistent storage engine, which supports all SQLite database features. + +**Figure 1** How RDB works + +![](figure/en-us_image_0000001115980740.png) + +## Default Settings +- The default database logging mode is write-ahead logging (WAL). +- The default database flush mode is Full mode. +- The default shared memory is 8 MB for the OpenHarmony database and 2 MB for a single query. + +## Constraints +- A maximum of four connection pools can be connected to an RDB to manage read and write operations. +- To ensure data accuracy, the RDB supports only one write operation at a time. -- Gitee From 41643968fc08546d3082c2afd90628b330499839 Mon Sep 17 00:00:00 2001 From: annie_wangli Date: Wed, 26 Jan 2022 09:15:28 +0800 Subject: [PATCH 3/3] update docs Signed-off-by: annie_wangli --- .../subsys-data-relational-database-guide.md | 187 +++++++++--------- 1 file changed, 92 insertions(+), 95 deletions(-) diff --git a/en/device-dev/subsystems/subsys-data-relational-database-guide.md b/en/device-dev/subsystems/subsys-data-relational-database-guide.md index 15df71090d0..44a0b182924 100644 --- a/en/device-dev/subsystems/subsys-data-relational-database-guide.md +++ b/en/device-dev/subsystems/subsys-data-relational-database-guide.md @@ -1,133 +1,133 @@ -# 关系型数据库开发指导 +# RDB Development -## 场景介绍 +## When to Use -关系型数据库是在SQLite基础上实现的本地数据操作机制，提供给用户无需编写原生SQL语句就能进行数据增删改查的方法，同时也支持原生SQL语句操作。 +On the basis of the SQLite database, the RDB allows you to operate data with or without native SQL statements. In OpenHarmony, an RDB is also called RDB store. -## 接口说明 -### 数据库的创建和删除 +## Available APIs +### Creating and Deleting an RDB Store -关系型数据库提供了数据库创建方式，以及对应的删除接口，涉及的API如下所示。 +The following table describes APIs available for creating and deleting an RDB store. -表1 数据库创建和删除API +Table 1 APIs for creating and deleting an RDB store -| 类名 | 接口名 | 描述 | +| Class| API| Description| | ---- | ---- | ---- | -| RdbStoreConfig | RdbStoreConfig(const std::string &path,
StorageMode storageMode = StorageMode::MODE_DISK,
bool readOnly = false,
const std::vector &encryptKey = std::vector(),
const std::string &journalMode = "",
const std::string &syncMode = "",
const std::string &databaseFileType = "",
const std::string &databaseFileSecurityLevel = "") | 对数据库进行配置，包括设置数据库名、存储模式、日志模式、同步模式，是否为只读，及数据库加密。
  • path：数据库路径；
  • readOnly：是否只读；
  • storageMode：存储模式；
  • encryptKey：加密密钥;
  • journalMode：日志模式；
  • syncMode：同步模式；
  • databaseFileType：数据库类型；
  • databaseFileSecurityLevel：安全等级
| -| RdbOpenCallback | int OnCreate(RdbStore &rdbStore) | 数据库创建时被回调，开发者可以在该方法中初始化表结构，并添加一些应用使用到的初始化数据。 | -| RdbOpenCallback | int OnUpgrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库升级时被回调。 | -| RdbOpenCallback | int OnDowngrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | 数据库降级时被回调。 | -| RdbHelper | std::shared_ptr\ GetRdbStore(const RdbStoreConfig &config, int version, RdbOpenCallback &openCallback, int &errCode) | 根据配置创建或打开数据库。 | -| RdbHelper | int DeleteRdbStore(const std::string &path) | 删除指定的数据库。 | +| RdbStoreConfig | RdbStoreConfig(const std::string &path,
StorageMode storageMode = StorageMode::MODE_DISK,
bool readOnly = false,
const std::vector &encryptKey = std::vector(),
const std::string &journalMode = "",
const std::string &syncMode = "",
const std::string &databaseFileType = "",
const std::string &databaseFileSecurityLevel = "") | Configures an RDB store, including setting the name, storage mode, log mode, synchronization mode, and read-only mode, and encrypting the database.
  • **path**: path of the database.
  • **readOnly**: whether the database is read-only.
  • **storageMode**: storage mode.
  • **encryptKey**: key used for database encryption.
  • **journalMode**: database logging mode.
  • **syncMode**: data synchronization mode.
  • **databaseFileType**: database type.
  • **databaseFileSecurityLevel**: security level.
| +| RdbOpenCallback | int OnCreate(RdbStore &rdbStore) | Called when an RDB store is created. You can add the method for initializing the table structure and add initialization data used by your application in the callback.| +| RdbOpenCallback | int OnUpgrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | Called when the RDB store is upgraded.| +| RdbOpenCallback | int OnDowngrade(RdbStore &rdbStore, int currentVersion, int targetVersion) | Called when the RDB store is downgraded.| +| RdbHelper | std::shared_ptr\ GetRdbStore(const RdbStoreConfig &config, int version, RdbOpenCallback &openCallback, int &errCode) | Creates or obtains an RDB store.| +| RdbHelper | int DeleteRdbStore(const std::string &path) | Deletes the specified RDB store.| -### 数据库的加密 +### Encrypting an RDB Store -关系型数据库提供数据库加密的能力，在创建数据库时若指定了密钥，则会创建为加密数据库。再次使用此数据库时，需要指定该密钥，才能正确打开数据库。 +The RDB provides the database encryption capability. When creating an RDB store , you can add a key for security purposes. After that, the RDB store can be accessed only with the correct key. -表2 数据库修改密钥API -| 类名 | 接口名 | 描述 | +Table 2 API for changing the key +| Class| API| Description| | ---- | ---- | ---- | -| RdbStore | int ChangeEncryptKey(const std::vector &newKey) | 为数据库设置新的加密密钥。注：仅支持加密数据库更换加密密钥。 | +| RdbStore | int ChangeEncryptKey(const std::vector &newKey) | Changes the encryption key for an RDB store.
Note: The encryption key can be changed only for an encrypted database.| -### 数据库谓词的使用 +### Using Predicates -关系型数据库提供了用于设置数据库操作条件的谓词AbsRdbPredicates，其中包括两个实现子类RdbPredicates和RawRdbPredicates： +The RDB provides **AbsRdbPredicates** for you to set database operation conditions. The **AbsRdbPredicates** has the following child classes: -- RdbPredicates：开发者无需编写复杂的SQL语句，仅通过调用该类中条件相关的方法，如equalTo、notEqualTo、groupBy、orderByAsc、beginsWith等，就可自动完成SQL语句拼接，方便用户聚焦业务操作。 -- RawRdbPredicates：可满足复杂SQL语句的场景，支持开发者自己设置where条件子句和whereArgs参数。不支持equalTo等条件接口的使用。 +- **RdbPredicates**: With this class, you do not need to write complex SQL statements. Instead, you can combine SQL statements simply by calling methods in this class, such as **equalTo**, **notEqualTo**, **groupBy**, **orderByAsc**, and **beginsWith**. +- **RawRdbPredicates**: With this class, you can set **whereClause** and **whereArgs**, but cannot call methods such as **equalTo**. - 表7 数据库谓词API - | 类名 | 接口名 | 描述 | + Table 7 APIs for RDB predicates + | Class| API| Description| | ---- | ---- | ---- | - | RdbPredicates | AbsPredicates *EqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值相等。 | - | RdbPredicates | AbsPredicates *NotEqualTo(std::string field, std::string value) | 设置谓词条件，满足field字段与value值不相等。 | - | RdbPredicates | AbsPredicates *BeginsWith(std::string field, std::string value) | 设置谓词条件，满足field字段以value值开头。 | - | RdbPredicates | AbsPredicates *Between(std::string field, std::string low, std::string high) | 设置谓词条件，满足field字段在最小值low和最大值high之间。 | - | RdbPredicates | AbsPredicates *OrderByAsc(std::string field) | 设置谓词条件，根据field字段升序排列。 | - | RdbPredicates | void SetWhereClause(std::string whereClause) | 设置where条件子句。 | - | RdbPredicates | void SetWhereArgs(std::vector\ whereArgs) | 设置whereArgs参数，该值表示where子句中占位符的值。 | + | RdbPredicates | AbsPredicates *EqualTo(std::string field, std::string value) | Sets the **AbsPredicates** to match the field that is equal to the specified value.| + | RdbPredicates | AbsPredicates *NotEqualTo(std::string field, std::string value) | Sets the **AbsPredicates** to match the field that is not equal to the specified value.| + | RdbPredicates | AbsPredicates *BeginsWith(std::string field, std::string value) | Sets the **AbsPredicates** to match the field that starts with the specified value.| + | RdbPredicates | AbsPredicates *Between(std::string field, std::string low, std::string high) | Sets the **AbsPredicates** to match the field that is within the range specified by **low** and **high**.| + | RdbPredicates | AbsPredicates *OrderByAsc(std::string field) | Sets the **AbsPredicates** to match the column with values sorted in ascending order.| + | RdbPredicates | void SetWhereClause(std::string whereClause) | Sets **whereClause**.| + | RdbPredicates | void SetWhereArgs(std::vector\ whereArgs) | Sets **whereArgs**, which indicates the value of the placeholder in **whereClause**.| -### 数据表的增删改查 +### Managing Data in an RDB Store -关系型数据库提供对本地数据增删改查操作的能力，相关API如下所示。 +The RDB provides APIs for inserting, deleting, updating, and querying data in the local RDB store. -- 新增 +- Inserting data - 关系型数据库提供了插入数据的接口，通过ValuesBucket输入要存储的数据，通过返回值判断是否插入成功，插入成功时返回最新插入数据所在的行号，失败时则返回-1。 + The RDB provides an API for inserting data through **ValuesBucket** in a data table. If the data is added, the row number of the data inserted is returned; otherwise, **-1** is returned. - 表3 数据表插入API + Table 3 API for inserting data to a data table - | 类名 | 接口名 | 描述 | + | Class| API| Description| | ---- | ---- | ---- | - | RdbStore | int Insert(int64_t &outRowId, const std::string &table, const ValuesBucket &initialValues) | 向数据库插入数据。
  • table：待添加数据的表名。
  • initialValues：以ValuesBucket存储的待插入的数据。它提供一系列put方法，如PutString(const std::string &columnName, const std::string &value)，PutDouble(const std::string &columnName, double value)，用于向ValuesBucket中添加数据。
| + | RdbStore | int Insert(int64_t &outRowId, const std::string &table, const ValuesBucket &initialValues) | Inserts data based on the passed table name and data in **ValuesBucket**.
  • **table**: specifies the name of the target table.
  • **initialValues**: specifies the data, stored in **ValuesBucket**, to insert. A series of **put()** methods, such as **PutString(const std::string &columnName, const std::string &value)** and **PutDouble(const std::string &columnName, double value)**, are provided to add data to **ValuesBucket**.
| -- 删除 +- Deleting data - 调用删除接口，通过AbsRdbPredicates指定删除条件。该接口的返回值表示删除的数据行数，可根据此值判断是否删除成功。如果删除失败，则返回0。 + Call the **delete()** method to delete data meeting the conditions specified by **AbsRdbPredicates**. If the data is deleted, the row number of the deleted data is returned; otherwise, **0** is returned. - 表5 数据表删除API - | 类名 | 接口名 | 描述 | + Table 5 API for deleting data + | Class| API| Description| | ---- | ---- | ---- | - | RdbStore | int Delete(int &deletedRows, const AbsRdbPredicates &predicates) | 删除数据。
  • deletedRows：删除的记录条数。
  • predicates：Rdb谓词，指定了删除操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| + | RdbStore | int Delete(int &deletedRows, const AbsRdbPredicates &predicates) | Deletes data.
  • **deletedRows**: specifies the number of rows to delete.
  • **predicates**: specifies the table name and conditions for deleting the data. **AbsRdbPredicates** has the following classes:
    • **RdbPredicates**: specifies update conditions by calling its methods, such as **equalTo**.
    • **RawRdbPredicates**: specifies the table name, **whereClause** and **whereArgs** only.
| -- 更新 +- Updating data - 调用更新接口，传入要更新的数据，并通过AbsRdbPredicates指定更新条件。该接口的返回值表示更新操作影响的行数。如果更新失败，则返回0。 + Call the **update()** method to modify data based on the passed data and the conditions specified by **AbsRdbPredicates**. If the data is updated, the row number of the updated data is returned; otherwise, **0** is returned. - 表4 数据表更新API - | 类名 | 接口名 | 描述 | + Table 4 API for updating data + | Class| API| Description| | ---- | ---- | ---- | - | RdbStore | int Update(int &changedRows, const ValuesBucket &values, const AbsRdbPredicates &predicates) | 更新数据库表中符合谓词指定条件的数据。
  • changedRows：更新的记录条数。
  • values：以ValuesBucket存储的要更新的数据。
  • predicates：指定了更新操作的表名和条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
| + | RdbStore | int Update(int &changedRows, const ValuesBucket &values, const AbsRdbPredicates &predicates) | Updates the data that meets the conditions specified by predicates.
  • **changedRows**: specifies the number of rows to update.
  • **values**: specifies the new data stored in **ValuesBucket**.
  • **predicates**: specifies the table name and conditions for the update operation. **AbsRdbPredicates** has the following classes:
    • **RdbPredicates**: specifies update conditions by calling its methods, such as **equalTo**.
    • **RawRdbPredicates**: specifies the table name, **whereClause** and **whereArgs** only.
| -- 查询 +- Querying data - 关系型数据库提供了两种查询数据的方式： + You can query data in an RDB store in either of the following ways: - - 直接调用查询接口。使用该接口，会将包含查询条件的谓词自动拼接成完整的SQL语句进行查询操作，无需用户传入原生的SQL语句。 - - 执行原生的SQL语句进行查询操作。 + - Call the **query()** method to query data based on the predicates, without passing any SQL statement. + - Run the native SQL statement. - 表6 数据表查询API - | 类名 | 接口名 | 描述 | + Table 6 APIs for querying data + | Class| API| Description| | ---- | ---- | ---- | - | RdbStore | std::unique_ptr Query(const AbsRdbPredicates &predicates, const std::vector\ columns) | 查询数据。
  • predicates：谓词，可以设置查询条件。AbsRdbPredicates的实现类有两个：RdbPredicates和RawRdbPredicates。
    • RdbPredicates：支持调用谓词提供的equalTo等接口，设置更新条件。
    • RawRdbPredicates：仅支持设置表名、where条件子句、whereArgs三个参数，不支持equalTo等接口调用。
  • columns：规定查询返回的列。
| - | RdbStore | std::unique_ptr QuerySql(const std::string &sql, const std::vector\ &selectionArgs = std::vector\()) | 执行原生的用于查询操作的SQL语句。
  • sql：原生用于查询的sql语句。
  • selectionArgs：sql语句中占位符参数的值，若select语句中没有使用占位符，该参数可以设置为null。
| + | RdbStore | std::unique_ptr Query(const AbsRdbPredicates &predicates, const std::vector\ columns) | Queries data.
  • **predicates**: specifies the query conditions. **AbsRdbPredicates** has the following classes:
    • **RdbPredicates**: specifies the query conditions by calling its methods, such as **equalTo**.
    • **RawRdbPredicates**: specifies the table name, **whereClause**, and **whereArgs** only.
  • **columns**: specifies the number of columns returned.
| + | RdbStore | std::unique_ptr QuerySql(const std::string &sql, const std::vector\ &selectionArgs = std::vector\()) | Executes the native SQL statements to query data.
  • **sql**: specifies the native SQL statement.
  • **selectionArgs**: specifies the parameter values corresponding to the placeholders in the SQL statements. Set it to **null** if the **select** statement has no placeholder.
| -### 查询结果集的使用 +### Using the Result Set -关系型数据库提供了查询返回的结果集ResultSet，其指向查询结果中的一行数据，供用户对查询结果进行遍历和访问。ResultSet对外API如下所示。 +A result set can be regarded as rows of data in the queried results. It allows you to traverse and access the data you have queried. The following table describes the external APIs of **ResultSet**. - 表8 结果集API - | 类名 | 接口名 | 描述 | + Table 8 APIs for using the result set + | Class| API| Description| | ---- | ---- | ---- | - | ResultSet | int GoTo(int offset) | 从结果集当前位置移动指定偏移量。 | - | ResultSet | int GoToRow(int position) | 将结果集移动到指定位置。 | - | ResultSet | int GoToNextRow() | 将结果集向后移动一行。 | - | ResultSet | int GoToPreviousRow() | 将结果集向前移动一行。 | - | ResultSet | int IsStarted(bool &result) | 判断结果集是否被移动过。 | - | ResultSet | int IsEnded(bool &result) | 判断结果集是否被移动到最后一行之后。 | - | ResultSet | int IsAtFirstRow(bool &result) | 判断结果集当前位置是否在第一行。 | - | ResultSet | int IsAtLastRow(bool &result) | 判断结果集当前位置是否在最后一行。 | - | ResultSet | int GetRowCount(int &count) | 获取当前结果集中的记录条数。 | - | ResultSet | int GetColumnCount(int &count) | 获取结果集中的列数。 | - | ResultSet | int GetString(int columnIndex, std::string &value) | 获取当前行指定列的值，以String类型返回。 | - | ResultSet | int GetBlob(int columnIndex, std::vector\ &blob) | 获取当前行指定列的值，以字节数组形式返回。 | - | ResultSet | int GetDouble(int columnIndex, double &value) | 获取当前行指定列的值，以double型返回。 | + | ResultSet | int GoTo(int offset) | Moves the result set forwards or backwards by the specified offset relative to its current position.| + | ResultSet | int GoToRow(int position) | Moves the result set to the specified row.| + | ResultSet | int GoToNextRow() | Moves the result set to the next row.| + | ResultSet | int GoToPreviousRow() | Moves the result set to the previous row.| + | ResultSet | int IsStarted(bool &result) | Checks whether the result set has been moved.| + | ResultSet | int IsEnded(bool &result) | Checks whether the result set is moved after the last line.| + | ResultSet | int IsAtFirstRow(bool &result) | Checks whether the result set is located in the first row.| + | ResultSet | int IsAtLastRow(bool &result) | Checks whether the result set is located in the last row.| + | ResultSet | int GetRowCount(int &count) | Obtains the number of rows in the result set.| + | ResultSet | int GetColumnCount(int &count) | Obtains the number of columns in the result set.| + | ResultSet | int GetString(int columnIndex, std::string &value) | Obtains the values in the specified column of the current row, in strings.| + | ResultSet | int GetBlob(int columnIndex, std::vector\ &blob) | Obtains the values in the specified column of the current row, in a byte array.| + | ResultSet | int GetDouble(int columnIndex, double &value) | Obtains the values in the specified column of the current row, in double.| -## 约束与限制 +## Constraints -无。 +None. -## 开发步骤 +## How to Develop -1. 创建数据库。 +1. Create an RDB store. - a. 配置数据库相关信息，包括数据库的名称、存储模式、是否为只读模式等。 + a. Configure the RDB store attributes, including the database name, storage mode, and read-only mode. - b. 初始化数据库表结构和相关数据。 + b. Initialize the table structure and related data in the RDB store. - c. 创建数据库。 + c. Create an RDB store. - 示例代码如下： + The sample code is as follows: ``` const std::string DATABASE_NAME = RDB_TEST_PATH + "RdbStoreTest.db"; const CREATE_TABLE_TEST = "CREATE TABLE IF NOT EXISTS test (id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT, age INTEGER, salary REAL, blobType BLOB)"; @@ -149,15 +149,13 @@ std::shared_ptr store = RdbHelper::GetRdbStore(config, 1, callback, 0); ``` -2. 插入数据。 +2. Insert data. - a. 构造要插入的数据，以ValuesBucket形式存储。 + a. Create a **ValuesBucket** to store the data you need to insert. - b. 调用关系型数据库提供的插入接口。 + b. Call the **insert()** method to insert data into the RDB store. - c. 创建数据库。 - - 示例代码如下： + The sample code is as follows: ``` ValuesBucket values; @@ -169,17 +167,17 @@ store->Insert(id, "test", values); ``` -3. 查询数据。 +3. Query data. - a. 构造用于查询的谓词对象，设置查询条件。 + a. Create a predicate that specifies query conditions. - b. 指定查询返回的数据列。 + b. Specify the data columns to return in the result set. - c. 调用查询接口查询数据。 + c. Call the **query()** method to query data. - d. 调用结果集接口，遍历返回结果。 + d. Call the **ResultSet** APIs to traverse data in the result set. - 示例代码如下： + The sample code is as follows: ``` std::vector columns = {"id", "name", "age", "salary"}; @@ -188,4 +186,3 @@ std::unique_ptr resultSet = store->Query(predicates, columns) resultSet.goToNextRow(); ``` - -- Gitee