📃 docs(Update StoneDB docs): (#82) (#83)

Docs/00-about-stonedb/_category_.json

+{
+    "position": 1,
+    "label": "About StoneDB",
+    "collapsible": true
+}
\ No newline at end of file

Docs/00-about-stonedb/architecture.md

+---
+id: architecture
+sidebar_position: 1.2
+---
+
+# Architecture

Docs/00-about-stonedb/intro.md

+---
+id: intro
+sidebar_position: 1.1
+---
+# StoneDB Introduction
+
+StoneDB is an open-source hybrid transaction/analytical processing (HTAP) database designed and developed by StoneAtom based on the MySQL kernel. It is the first database of this type launched in China. StoneDB can be seamlessly switched from MySQL. It provides features such as optimal performance and real-time analytics, offering you a one-stop solution to process online transaction processing (OLTP), online analytical processing (OLAP), and HTAP workloads.
+
+StoneDB is fully compatible with the MySQL 5.6 and 5.7 protocols, the MySQL ecosystem, and common MySQL features and syntaxes. You can use tools and clients in the MySQL ecosystem on StoneDB, such as Navicat, Workbench, mysqldump, and mydumper. In addition, all workloads on StoneDB can be run on MySQL.
+
+StoneDB is optimized for OLAP applications. StoneDB that runs on a common server can process complex queries on tens of billions of data records, while ensuring high performance. Compared to databases that use MySQL Community Edition, StoneDB is at least 10 times faster in processing queries.
+
+StoneDB uses the knowledge grid technology and a column-based storage engine. This storage engine is designed for OLAP applications and uses techniques such as column-based storage, knowledge grid-based filtering, and high-efficiency data compression. With such storage engine, StoneDB provides application systems with high-performance and reduces the total cost of ownership (TCO).
+
+## Advantages
+### Integration of MySQL
+StoneDB is an HTAP database built on MySQL. To enhance analytics capabilities, it integrates a self-developed engine also named StoneDB. (In this topic, StoneDB refers to the database, if not otherwise specified.) For this reason, StoneDB is fully compatible with MySQL. You can use standard interfaces, such as Open Database Connectivity (ODBC) and Java Database Connectivity (JDBC) to connect to StoneDB. In addition, you can create local connections to connect to StoneDB. StoneDB supports APIs written in various programming languages, such as C, C++, C#, Java, PHP, and Perl. StoneDB is fully compatible with views and stored procedures that comply with the ANSI SQL-92 standard and the SQL-99 standard. In this way, your application systems that can run on MySQL can directly run on StoneDB, without the need to modify the code. This allows you to seamlessly switch MySQL to StoneDB.
+
+### Real-time HTAP
+StoneDB provides two engines: row-based storage engine InnoDB and column-based storage engine StoneDB. StoneDB uses binlogs to replicate data from the row-based storage engine to the column-based storage engine in real time. This ensures strong data consistency between the two storage engines.
+
+## Key techniques
+### Column-based storage engine
+A column-based storage engine stores data to disks column by column. When you query data, only the required fields are retrieved, which greatly reduces memory bandwidth traffic and disk I/O. In addition, in a column-based storage engine, columns do not need to be indexed, freeing the database from maintaining such indexes.
+
+### High-efficiency data compression
+In a relational database, values in the same column are of the same data type. More duplicate values stored in a column indicate a higher data compression ratio and a smaller data volume. By virtue of this, less data is retrieved for queries, and thus memory bandwidth traffic and disk I/O are reduced. 
+
+StoneDB saves storage space by using column-based storage. The data compression ratio of a column-oriented database is at least 10 times higher than that of a row-oriented database. 
+### Knowledge grid
+A knowledge grid can filter data packs based on metadata, and then decompress the data packs to obtain the data that meets the query conditions. This greatly reduces I/O, and improves response speed and network utilization.
+### Push-based vectorized query execution
+When processing a query, StoneDB pushes column-based data packs from one operator to another based on the execution plan. Compared to the execution model used by row-oriented databases, push-based execution prevents in-depth calls of stacks and saves resources.
+

Docs/00-about-stonedb/limits.md

+---
+id: limits
+sidebar_position: 1.3
+---
+
+# Limits
+StoneDB is built on MySQL by integrating a storage engine into MySQL. Therefore, StoneDB is highly compatible with the MySQL 5.6 and 5.7 protocols, and the ecosystem, common features, and common syntaxes of MySQL. However, due to characteristics of column-based storage, StoneDB is incompatible with certain MySQL operations and features.
+
+## Unsupported DDL operations
+StoneDB does not support the following DDL operations:
+
+- Modify the data type of a field.
+- Modify the length of a field.
+- Change the character set of a table or a field.
+- Convert the character set for a table.
+- Optimize a table.
+- Analyze a table.
+- Lock a table.
+- Repair a table.
+- Execute a CREATE TABLE… AS SELECT statement.
+- Reorganize a table.
+- Rename a field.
+- Configure the default value for a field.
+- Specify the default value of a field to null.
+- Specify the default value of a field to non-null.
+- Add a unique constraint.
+- Delete a unique constraint.
+- Create an index.
+- Delete an index.
+- Modify a table comment.
+
+StoneDB is a column-oriented database. Data in StoneDB is highly compressed. For this reason, table attributes and column attributes are difficult to modify. The character sets, data types, constraints, and indexes must be properly defined when tables are being created.
+## Unsupported DML operations
+StoneDB does not support the following DML operations:
+
+- Execute a DELETE statement.
+- Use subqueries in an UPDATE statement.
+- Execute an UPDATE… JOIN statement to update multiple tables.
+- Execute a REPLACE… INTO statement.
+
+StoneDB is not suitable for applications that are frequently updated. It supports only single-table update and insert operations. This is because a column-oriented database needs to find each corresponding column and update the value in the row when processing an update operation. However, a row-oriented database stores data by row. When processing an update operation, the row-oriented database only needs to find the corresponding page or block and update the data directly in the row.
+## Unsupported objects
+StoneDB does not support the following objects:
+
+- Global indexes
+- Unique constraints
+- Triggers
+- Temporary tables
+- Stored procedures containing dynamic SQL statements
+- User-defined functions containing nested SQL statements
+
+If you want to use user-defined functions that contain nested SQL statements, set the **stonedb_ini_allowmysqlquerypath** parameter to **1** in the **stonedb.cnf** configuration file.
+## Unsupported data types
+StoneDB does not support the following data types:
+
+- bit
+- enum
+- set
+- decimal whose precision is higher than 18, for example, decimal(19,x)
+- Data types that contain keyword **unsigned** or **zerofill**
+## Unsupported binary log formats
+StoneDB does not support the following binary log formats:
+
+- row
+- mixed
+
+Column-oriented databases supports only statement-based binary logs. Row-based binary logs and mixed binary logs are not supported.
+## Association queries across storage engines not supported
+By default, StoneDB does not support association queries across storage engines. If an association query involves tables in both InnoDB and the StoneDB column-based storage engine, an error will be reported. You can set the **stonedb_ini_allowmysqlquerypath** parameter to **1 **in the **stonedb.cnf** configuration file to remove this limit.
+## Transactions not supported
+Transactions must strictly comply with the ACID attributes. However, StoneDB does not support redo and undo logs and thus does not support transactions.
+## Partitions not supported
+Column-oriented databases do not support partitioning.
+## Column locking and table locking not supported
+Column-oriented databases do not support column locking or table locking.
+ 

Docs/00-about-stonedb/terms.md

+---
+id: terms
+sidebar_position: 1.4
+---
+
+# Terms
+
+| **Term** | **Description** |
+| :-- | :-- |
+| **row** | A series of data that makes up a record. |
+| **column** | Also referred to as field. In a relational database, a field must be associated with a data type when the field is being created. |
+| **table** | Consists of rows and columns. Databases use tables to store data. Tables are essential objects in databases. |
+| **view** | A virtual table that does not store actual data. It is based on the result set of an SQL statement. |
+| **stored procedure** | A collection of one or more SQL statements that are compiled and then stored in a database to execute a specific operation. To execute a stored procedure, you need to specify the name and required parameters of the stored procedure. |
+| **database** | A collection of database objects such as tables, views, and stored procedures. |
+| **instance** | A collection of databases. |
+| **data page** | The basic unit for database management. The default size for a data page is 16 KB. |
+| **data file** | Used for storing data. By default, one table corresponds to one data file. |
+| **tablespace** | A logical storage unit. By default, one table corresponds to one tablespace. |
+| **transaction** | A sequence of DML operations. This sequence satisfies the atomicity, consistency, isolation, and durability (ACID) properties. A transaction must end with a submission or rollback. Implicit submission by using DDL statements are supported. |
+| **character set** | A collection of symbols and encodings. |
+| **collation** | A collation is a collection of rules for comparing and sorting character strings. |
+| **column-based storage** | Stores data by column to disks. |
+| **data compression** | A process performed to reduce the size of data files. The data compression ratio is determined by the data type, degree of duplication, and compression algorithm. |
+| **OLTP** | The acronym of online transaction processing. OLTP features quick response for interactions and high concurrency of small transactions. Typical applications are transaction systems of banks. |
+| **OLAP** | The acronym of online analytical processing. OLAP features complex analytical querying on a large amount of data. Typical applications are data warehouses. |
+| **HTAP** | The acronym of hybrid transaction/analytical processing. HTAP is an emerging application architecture built to allow one system for both transactions and analytics. |
\ No newline at end of file

Docs/01-environment-requirements/_category_.json

+{
+    "position": 2,
+    "label": "Environment Requirements",
+    "collapsible": true
+}
\ No newline at end of file

Docs/01-environment-requirements/server-configuration-requirements.md

+---
+id: server-configuration-requirements
+sidebar_position: 2.2
+---
+# Server Configuration Requirements
+
+This topic describes the configuration requirements for a development or test environment and a production environment.
+
+
+# Configuration requirements for a development or test environment
+
+The following table describes the configuration requirements for a development or test environment.
+
+| **CPU** | **Memory** | **Storage** | **Network** |
+| --- | --- | --- | --- |
+| 2 cores+ | 2 GB+ | 10 GB+ | Megabit network card |
+
+:::caution
+
+If the development or test environment is deployed on a virtual machine, the AVX instruction set must be enabled. Otherwise, StoneDB cannot be installed.
+
+:::
+
+# Configuration requirements for a production environment
+
+The following table describes the configuration requirements for a production environment.
+
+| **CPU** | **Memory** | **Storage** | **Network** |
+| --- | --- | --- | --- |
+| 8 cores+ | 8 GB+ | 100 GB+ | Gigabit network card |
+
+:::tip
+
+We recommend you use higher configuration in your production environment.
+
+:::

Docs/01-environment-requirements/supported-servers-and-OSs.md

+---
+id: supported-servers-and-OSs
+sidebar_position: 2.1
+---
+# Support Servers and OSs
+
+StoneDB is an open-source hybrid transaction/analytical processing (HTAP) database designed and developed by StoneAtom based on the MySQL kernel. It can be deployed and run on 64-bit x86 servers and supports most mainstream network hardware and Linux OSs.
+
+# Supported servers
+The following table lists the servers on which StoneDB can run.
+
+| **Architecture** | **Supported server** |
+| --- | --- |
+| x86_64 architecture | Common x86_64 servers with AVX instruction sets enabled |
+
+:::info
+
+Support for the ARM64 or Power architecture is under testing.
+
+:::
+
+# Supported OSs
+The following table lists the OSs supported by StoneDB.
+
+| **OS** | **Version** |
+| --- | --- |
+| CentOS | 7.x |
+| Red Hat Enterprise | 7.x |
+| Ubuntu LTS | 20.04 or higher |
+
+:::info
+
+Compatibilities with other OSs such as Debian and Fedora are under testing.
+
+:::
+

Docs/02-getting-started/_category_.json

+{
+    "position": 3,
+    "label": "Getting Started",
+    "collapsible": true
+}
\ No newline at end of file

Docs/02-getting-started/quick-deployment.md

+---
+id: quick-deployment
+sidebar_position: 3.1
+---
+
+# Quick Deployment
+
+## Upload and decompress the TAR package
+```
+tar -zxvf stonedb-build_stonedb5.7_0.1_x86_64_CentOS7.9.2009_Release_2022-05-17_12_06.bin.tar.gz
+```
+
+Upload the installation package to the directory. The name of the folder extracted from the package is **stonedb**.
+
+## Check dependencies
+```
+cd stonedb/install/bin
+ldd mysqld
+ldd mysql
+```
+If the command output contains keywords **not found**, some dependencies are missing and must be installed.
+
+## Modify the configuration file
+
+```
+cd stonedb/install/
+cp stonedb.cnf stonedb.cnf.bak
+vi stonedb.cnf
+```
+
+Modify the path and parameters. If the installation folder is **stonedb**, you only need to modify the parameters.
+
+## Create an account and directories
+```
+groupadd stonedb
+useradd -g stonedb stonedb
+passwd stonedb
+cd stonedb/install/
+mkdir binlog
+mkdir log
+mkdir tmp
+mkdir redolog
+mkdir undolog
+chown -R stonedb:stonedb stonedb
+```
+
+## Initialize StoneDB
+
+```
+/stonedb/install/bin/mysqld --defaults-file=/stonedb/install/stonedb.cnf --initialize-insecure --user=stonedb
+```
+
+When you initialize StoneDB, add** parameter --initialize-insecure** to allow the admin to initially log in without the need to enter a password. The admin is required to set a password after the initial login.
+
+## Start or stop StoneDB
+```
+/stonedb/install/bin/mysqld_safe --defaults-file=/stonedb/install/stonedb.cnf --user=stonedb &
+mysqladmin -uroot -p -S /stonedb/install/tmp/mysql.sock shutdown
+```
+## Log in as admin and reset the password
+```
+mysql -uroot -p -S /stonedb/install/tmp/mysql.sock
+>set password = password('MYPASSWORD');
+```
+Replace **MYPASSWORD** with your password.

Docs/02-getting-started/quick-start.md

+---
+id: quick-start
+sidebar_position: 3.2
+---
+
+# Quick Start
+
+This topic presents some examples to show you that the StoneDB storage engine has superior performance than InnoDB on processing bulk insert of data, compressing data, and executing analytical queries.
+
+## Step 1. Deploy a test environment
+Before using StoneDB, prepare your test environment according to instructions provided in [Quick Deployment](https://stoneatom.yuque.com/staff-ft8n1u/dghuxr/pv8ath) and start StoneDB.
+
+## Step 2. Prepare test data
+Perform the following steps to generate test data.
+
+### 1. Prepare for the test
+In the test environment, create a StoneDB table and a InnoDB table. Ensure the following parameter settings of the two tables are same:
+
+- autocommit=1
+- innodb_flush_log_at_trx_commit=1
+- sync_binlog=0
+
+
+### 2. Create a database
+
+Create a database named **test**.
+
+```
+create database test DEFAULT CHARACTER SET utf8mb4;
+```
+
+### 3. Create a table
+
+In database **test**, create a table named **t_test**.
+
+```
+use test
+CREATE TABLE t_user(
+  id INT NOT NULL AUTO_INCREMENT,
+  first_name VARCHAR(20) NOT NULL,
+  last_name VARCHAR(20) NOT NULL,
+  sex VARCHAR(5) NOT NULL,
+  score INT NOT NULL,
+  copy_id INT NOT NULL,
+  PRIMARY KEY (`id`)
+) engine=STONEDB;
+```
+
+### 4. Create a stored procedure
+
+Create a stored procedure that is used to generate a table containing randomly generated names of persons.
+
+```
+DELIMITER //
+    create PROCEDURE add_user(in num INT)
+    BEGIN
+        DECLARE rowid INT DEFAULT 0;
+        DECLARE firstname VARCHAR(10);
+        DECLARE name1 VARCHAR(10);
+        DECLARE name2 VARCHAR(10);
+        DECLARE lastname VARCHAR(10) DEFAULT '';
+        DECLARE sex CHAR(1);
+        DECLARE score CHAR(2);
+        WHILE rowid < num DO
+        SET firstname = SUBSTRING(md5(rand()),1,4); 
+        SET name1 = SUBSTRING(md5(rand()),1,4); 
+        SET name2 = SUBSTRING(md5(rand()),1,4); 
+        SET sex=FLOOR(0 + (RAND() * 2));
+        SET score= FLOOR(40 + (RAND() *60));
+        SET rowid = rowid + 1;
+        IF ROUND(RAND())=0 THEN 
+        SET lastname =name1;
+        END IF;
+        IF ROUND(RAND())=1 THEN
+        SET lastname = CONCAT(name1,name2);
+        END IF;
+        insert INTO t_user(first_name,last_name,sex,score,copy_id) VALUES (firstname,lastname,sex,score,rowid);  
+        END WHILE;
+    END //
+DELIMITER ;
+```
+
+## Step 3. Test insert performance
+
+Call the stored procedure to insert 10,000,000 rows of data.
+```
+> call add_user_innodb(10000000);
+Query OK, 1 row affected (24 min 46.62 sec)
+
+> call add_user(10000000);
+Query OK, 1 row affected (9 min 21.14 sec)
+```
+According to the returned result, StoneDB takes 9 minutes and 21 seconds, while InnoDB takes 24 minutes and 46 seconds.
+
+## Step 4. Test data compression efficiency
+Compress the inserted data.
+```
+> select count(*) from t_user_innodb;
++----------+
+| count(*) |
++----------+
+| 10000000 |
++----------+
+1 row in set (1.83 sec)
+
+> select count(*) from t_user;       
++----------+
+| count(*) |
++----------+
+| 10000000 |
++----------+
+1 row in set (0.00 sec)
+
++--------------+---------------+------------+-------------+--------------+------------+---------+
+| table_schema | table_name    | table_rows | data_length | index_length | total_size | engine  |
++--------------+---------------+------------+-------------+--------------+------------+---------+
+| test         | t_user        |   10000000 | 119.99M     | 0.00M        | 119.99M    | STONEDB |
+| test         | t_user_innodb |    9995867 | 454.91M     | 0.00M        | 454.91M    | InnoDB  |
++--------------+---------------+------------+-------------+--------------+------------+---------+
+```
+According to the returned result, the data size after compression in StoneDB is 120 MB while that in InnoDB is 455 MB.
+
+## Step 5. Test performance on processing aggregate queries
+
+Execute an aggregate query.
+```
+> select first_name,count(*) from t_user group by first_name order by 1; 
++------------+----------+
+| first_name | count(*) |
++------------+----------+
+.....
+| fffb       |      142 |
+| fffc       |      140 |
+| fffd       |      156 |
+| fffe       |      140 |
+| ffff       |      132 |
++------------+----------+
+65536 rows in set (0.98 sec)
+
+> select first_name,count(*) from t_user_innodb group by first_name order by 1;
++------------+----------+
+| first_name | count(*) |
++------------+----------+
+......
+| fffb       |      178 |
+| fffc       |      161 |
+| fffd       |      170 |
+| fffe       |      156 |
+| ffff       |      139 |
++------------+----------+
+65536 rows in set (9.00 sec)
+```
+According to the returned result, StoneDB takes 0.98 seconds while InnoDB takes 9 seconds.

Docs/03-O&M-Guide/_category_.json

+{
+    "position": 4,
+    "label": "O&M Guide",
+    "collapsible": true
+}
\ No newline at end of file

Docs/03-O&M-Guide/regular-change-operations.md

+---
+id: regular-change-operations
+sidebar_position: 4.1
+---
+
+# Regular Change Operations
+
+## Change operations on schemas and data of tables
+This section describes the supported change operations on schemas and data of tables.
+
+### Create tables using the same schema
+
+1. Execute a `CREATE TABLE` statement to create a StoneDB table.
+
+Code example:
+```sql
+CREATE TABLE t_name(
+  col1 INT NOT NULL AUTO_INCREMENT,
+  col2 VARCHAR(10) NOT NULL,
+  ......
+  PRIMARY KEY (`id`)
+) engine=STONEDB;
+```
+
+2. Execute a `CREATE TABLE... LIKE `statement to create another table that uses the same schema as the table created in the step 1.
+
+Code example:
+```
+create table t_other like t_name;
+```
+
+### Clear data in a table
+Execute a `TRUNCATE TABLE` statement to clear data in a table and retain the table schema.
+
+Code example:
+```
+truncate table t_name;
+```
+
+### Add a field
+Execute an `ALTER TABLE... ADD COLUMN` statement to add a field in a given table. The added field is the last field, by default. 
+Code example:
+
+```
+alter table t_name add column c_name varchar(10);
+```
+
+### Drop a field
+Execute an `ALTER TABLE... DROP` statement to drop a field from a table.<br />Code example:
+```
+alter table t_name drop c_name;
+```
+
+### Rename a table
+Execute an `ALTER TABLE... RENAME TO` statement to rename a given table.<br />Code example:
+```
+alter table t_name rename to t_name_new;
+```
+
+## Change operations on user permissions
+
+### Create a user
+Code example:
+```
+create user 'u_name'@'hostname' identified by 'xxx';
+```
+
+### Grant user permissions
+Code example:
+```
+grant all on *.* to 'u_name'@'hostname';
+grant select on db_name.* to 'u_name'@'hostname';
+grant select(column_name) on db_name.t_name to 'u_name'@'hostname';
+```
+
+### Revoke permissions
+Code example:
+```
+revoke all privileges on *.* from 'u_name'@'hostname';
+revoke select on db_name.* from 'u_name'@'hostname';
+revoke select(column_name) on db_name.t_name from 'u_name'@'hostname';
+```
+
+### Drop a user
+Code example:
+```
+drop user 'u_name'@'hostname';
+```

Docs/download.md

+---
+id: download
+sidebar_position: 100
+---
+
+# Please wait for release
+Release time: June 30, 2022
+
+
+