Skip to content

Commit

Permalink
Update sql_difference.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@Elliezza
Elliezza authored Dec 13, 2023
1 parent e648f88 commit 7a76d0e
Showing 1 changed file with 37 additions and 28 deletions.
65 changes: 37 additions & 28 deletions docs/en/openmldb_sql/sql_difference.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,19 +6,19 @@ Unless otherwise specified, the default version is OpenMLDB: >= v0.7.1

## Support Overview

The table below summarizes the differences in overall performance between OpenMLDB SQL and standard SQL based on SELECT statement elements across three execution modes (for execution mode details, please refer to Using Process and Execution Mode). OpenMLDB SQL is currently partially compatible with standard SQL, with additional syntax introduced to accommodate specific business scenarios. New syntax is indicated in bold in the table.
The table below summarizes the differences in overall performance between OpenMLDB SQL and standard SQL based on SELECT statement elements across three execution modes (for execution mode details, please refer to [Workflow and Execution Modes](../quickstart/concepts/modes.md)). OpenMLDB SQL is currently partially compatible with standard SQL, with additional syntax introduced to accommodate specific business scenarios. New syntax is indicated in bold in the table.

Note: ✓ indicates that the statement is supported, while ✕ indicates that it is not.

| | **OpenMLDB SQL**<br>**Offline Mode** | **OpenMLDB SQL**<br>**Online Preview Mode** | **OpenMLDB SQL**<br>**Online Request Mode** | **Standard SQL** | **Remarks** |
| -------------- | ---------------------------- | -------------------------------- | -------------------------------- | ------------ | ------------------------------------------------------------ |
| WHERE Clause | ✓ | ✓ | ✕ | ✓ | Some functionalities can be achieved through built-in functions with the `_where` suffix. |
| HAVING Clause | ✓ | ✓ | X | ✓ | |
| JOIN Clause | ✓ | ✕ | ✓ | ✓ | OpenMLDB only supports **LAST JOIN**. |
| JOIN Clause | ✓ | ✕ | ✓ | ✓ | OpenMLDB only supports **LAST JOIN** and **LEFT JOIN**. |
| GROUP BY | ✓ | ✕ | ✕ | ✓ | |
| ORDER BY | ✓ | ✓ | ✓ | ✓ | Support is limited to usage within the `WINDOW` and `LAST JOIN` clauses; it does not support reverse sorting in `DESC`. |
| LIMIT | ✓ | ✓ | ✕ | ✓ | |
| WINDOW Clause | ✓ | ✓ | ✓ | ✓ | OpenMLDB includes new syntac **WINDOW UNION** and **WINDOW ATTRIBUTES**. |
| WINDOW Clause | ✓ | ✓ | ✓ | ✓ | OpenMLDB includes new syntax **WINDOW UNION** and **WINDOW ATTRIBUTES**. |
| WITH Clause | ✕ | ✕ | ✕ | ✓ | OpenMLDB supports begins from version v0.8.0. |
| Aggregate Function | ✓ | ✓ | ✓ | ✓ | OpenMLDB has more extension functions. |

Expand All @@ -38,7 +38,7 @@ Compared to standard SQL, the differences in OpenMLDB SQL can be explained from

To prevent user errors from affecting online performance, OpenMLDB has introduced relevant parameters that limit the number of full table scans in offline mode and online preview mode. If these limitations are enabled, certain operations involving scans of multiple records (such as SELECT *, aggregation operations, etc.) may result in truncated results and, consequently, incorrect outcomes. It's essential to note that these parameters do not affect the accuracy of results in online request mode.

The configuration of these parameters is done within the tablet configuration file `conf/tablet.flags`, as detailed in the document on Configuration File. The parameters affecting scan limits include:
The configuration of these parameters is done within the tablet configuration file `conf/tablet.flags`, as detailed in the document on [Configuration File](../deploy/conf.md#the-configuration-file-for-tablet-conftabletflags). The parameters affecting scan limits include:

- Maximum Number of Scans: `--max_traverse_cnt`
- Maximum Number of Scanned Keys: `--max_traverse_pk_cnt`
Expand All @@ -52,9 +52,9 @@ In versions from v0.7.3 onwards, it's expected that the default values for these
| ------------------ | ------------ | ---------------- | ---------------- |
| Table References | ✓ | ✓ | ✕ |
| LAST JOIN | ✓ | ✓ | ✕ |
| Subquery/ With Clause | ✓ | ✓ | ✕ |
| Subquery/ WITH Clause | ✓ | ✓ | ✕ |

In the online request mode, the `WHERE` clause isn't supported. However, some functionalities can be achieved through computation functions with the `_where` suffix, like `count_where` and `avg_where`, among others. For detailed information, please consult the [Built-In Computation Function Document](https://chat.openai.com/c/functions_and_operators/Files/udfs_8h.md).
In the online request mode, the `WHERE` clause isn't supported. However, some functionalities can be achieved through computation functions with the `_where` suffix, like `count_where` and `avg_where`, among others. For detailed information, please refer to [Built-In Functions](./udfs_8h.md).

### LIMIT Clause

Expand All @@ -66,7 +66,7 @@ LIMIT is followed by an INT literal, and it does not support other expressions.
| WHERE | ✓ | ✓ | ✕ |
| WINDOW | ✓ | ✓ | ✕ |
| LAST JOIN | ✓ | ✓ | ✕ |
| GROUP BY & HAVING | ✕ | ✓ | X |
| GROUP BY & HAVING | ✕ | ✓ | ✕ |

### WINDOW Clause

Expand Down Expand Up @@ -94,19 +94,22 @@ The GROUP BY statement is still considered an experimental feature and only supp
| LAST JOIN | ✕ | ✕ | ✕ |
| Subquery | ✕ | ✕ | ✕ |

### JOIN Clause（LAST JOIN）
### JOIN Clause

OpenMLDB exclusively supports the LAST JOIN syntax. For a detailed description, please refer to the section on LAST JOIN in the extended syntax. A JOIN consists of two inputs, the left and right. In the online request mode, it supports two inputs as physical tables or specific subqueries. You can refer to the table for specific details. If a scenario is not listed, it means it's not supported.
OpenMLDB exclusively supports the LAST JOIN and LEFT JOIN syntax. For a detailed description, please refer to the section on JOIN in the extended syntax. A JOIN consists of two inputs, the left and right. In the online request mode, it supports two inputs as physical tables or specific subqueries. You can refer to the table for specific details. If a scenario is not listed, it means it's not supported.

| **Apply to** | **Offline Mode** | **Online Preview Mode** | **Online Request Mode** |
| ------------------------------------------------------------ | ---------------- | ----------------------- | ----------------------- |
| Two Table References | ✓✓ | ✓✕ | ✕✓ |
| As for WHERE subqueries, they are only allowed in the following cases:<br/>- When both the left and right tables are simple column filters<br/>- When both the left and right tables are the result of WINDOW or LAST JOIN operations | ✕✓ | ✕✓ | ✕✓ |
| **Apply to** | **Offline Mode** | **Online Preview Mode** | **Online Request Mode** |
| ---------------------------------------------- | ------------ | ---------------- | ---------------- |
| LAST JOIN + two table reference | ✓ | ✕ | ✓ |
| LAST JOIN + simple column filtering for both tables| ✓ | ✕ | ✓ |
| LAST JOIN + left table is filtering with WHERE | ✓ | ✕ | ✓ |
| LAST JOIN one of the table is WINDOW or LAST JOIN | ✓ | ✕ | ✓ |
| LAST JOIN + right table is LEFT JOIN subquery | ✕ | ✕ | ✓ |
| LEFT JOIN | ✕ | ✕ | ✕ |

Special Restrictions:

- Launching LAST JOIN for specific subqueries involves additional requirements. For more information, please refer to [Launch Requirements](https://chat.openai.com/openmldb_sql/deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#usagespecifications-last-join-inonlinerequestmode).
- LAST JOIN is currently not supported in online preview mode.
- Launching LAST JOIN for specific subqueries involves additional requirements. For more information, please refer to [Online Requirements](../openmldb_sql/deployment_manage/ONLINE_REQUEST_REQUIREMENTS.md#specifications-of-last-join-under-online-request-mode).
- LAST JOIN and LEFT JOIN is currently not supported in online preview mode.

### WITH Clause

Expand All @@ -124,11 +127,11 @@ Aggregation functions can be applied to all tables or windows. Window aggregatio

- Regarding full table aggregation, OpenMLDB v0.6.0 began supporting this feature in online preview mode. However, it's essential to pay attention to the described [Scanning Limit Configuration](https://openmldb.feishu.cn/wiki/wikcnhBl4NsKcAX6BO9NDtKAxDf#doxcnLWICKzccMuPiWwdpVjSaIe).

- OpenMLDB offers various extensions for aggregation functions. To find the specific functions supported, please consult the product documentation in [OpenMLDB Built-In Function](https://chat.openai.com/openmldb_sql/functions_and_operators/Files/udfs_8h.md).
- OpenMLDB offers various extensions for aggregation functions. To find the specific functions supported, please consult the product documentation in [OpenMLDB Built-In Function](../openmldb_sql/udfs_8h.md).

## Extended Syntax

OpenMLDB has focused on deep customization of the `WINDOW` and `LAST JOIN` statements, and this section will provide an in-depth explanation of these two statements.
OpenMLDB has focused on deep customization of the `WINDOW` and `LAST JOIN` statements and this section will provide an in-depth explanation of these two statements.

### WINDOW Clause

Expand All @@ -141,17 +144,17 @@ A typical WINDOW statement in OpenMLDB generally includes the following elements
- Window Attributes: Includes OpenMLDB-specific window attribute definitions, such as `MAXSIZE`, `EXCLUDE CURRENT_ROW`, `EXCLUDE CURRENT_TIME`, and `INSTANCE_NOT_IN_WINDOW`.
- Multi-table Definition: Uses the extended syntax `WINDOW ... UNION` to determine whether concatenation of cross-table data sources is required.

For a detailed syntax of the WINDOW statement, please refer to the [WINDOW Documentation](link to the documentation)(../openmldb_sql/dql/WINDOW_CLAUSE.md)
For a detailed syntax of the WINDOW statement, please refer to the [WINDOW Documentation](../openmldb_sql/dql/WINDOW_CLAUSE.md)

| **Statement Element** | **Support Syntax** | **Description** | Required? |
| ---------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | --------- |
| Data Definition | PARTITION BY | OpenMLDB supports multiple column data types: bool, int16, int32, int64, string, date, timestamp. | ✓ |
| Data Sorting | ORDER BY | - It only supports sorting on a single column. <br />- Supported data types for sorting include int16, int32, int64, and timestamp. <br />- Reverse order (`DESC`) is not supported. | ✓ |
| Scope Definition | Here's a summary of window definition syntax: | - You must specify both upper and lower boundaries. <br />- The boundary keyword `FOLLOWING` is not supported. <br />- In online request mode, the "current row" represents the present request line. From a table perspective, the current row is conceptually inserted into the appropriate position in the table based on the `ORDER BY` criteria. | ✓ |
| Scope Unit | - For basic upper and lower bounds definition, you can use ROWS/ROWS_RANGE BETWEEN ... AND... <br />- Scope definition is supported with keywords like PRECEDING, OPEN PRECEDING, CURRENT ROW, and UNBOUNDED.ROWS<br>ROWS_RANGE (Extended) | - ROW_RANGE is an extended syntax for defining window boundaries similar to standard SQL RANGE-type windows. It allows defining window boundaries with either numerical values or values with time units. This is an extended syntax.<br />- Window ranges defined in time units are equivalent to window definitions where time is converted into milliseconds. For example, `ROWS_RANGE 10s PRECEDING` and `ROWS_RANGE 10000 PRECEDING` are equivalent. | ✓ |
| Window Properties (Extended) | MAXSIZE <br>EXCLUDE CURRENT_ROW<br>EXCLUDE CURRENT_TIME<br>INSTANCE_NOT_IN_WINDOW | MAXSIZE is only valid to ROWS_RANGE | - |
| Multi Table Definition (Extension) | In practical use, the syntax form is relatively complex. Please refer to:<br/>[Cross Table Feature Development Tutorial](../tutorial/tutorial_sql_2.md)<br/>[WINDOW UNION Syntax Documentation](../openmldb_sql/dql/WINDOW_CLAUSE.md#1-window--union) | - It permits the merging of multiple tables. <br />- It allows the union of simple subqueries. <br />- It is commonly used in combination with aggregation functions for cross-table aggregation operations. | - |
| Incognito Window | - | It's essential to note that a complete window definition must include `PARTITION BY`, `ORDER BY`, and window range definition. | - |
| Data Sorting | ORDER BY | - It only supports sorting on a single column. <br />- Supported data types for sorting include int16, int32, int64, and timestamp. <br />- Reverse order (`DESC`) is not supported. <br />- Must specify for versions before v0.8.4 | - |
| Scope Definition | <be> Basic upper and lower bounds definition: ROWS/ROWS_RANGE BETWEEN ... AND ... <be> Scope definition is supported with keywords PRECEDING, OPEN PRECEDING, CURRENT ROW, UNBOUNDED | - Must specify both upper and lower boundaries. <br />- The boundary keyword `FOLLOWING` is not supported. <br />- In online request mode, `CURRENT ROW` represents the present request line. From a table perspective, the current row is virtually inserted into the appropriate position in the table based on the `ORDER BY` criteria. | ✓ |
| Scope Unit | ROWS<br>ROWS_RANGE (Extended) | - ROW_RANGE is an extended syntax for defining window boundaries similar to standard SQL RANGE-type windows. It allows defining window boundaries with either numerical values or values with time units. This is an extended syntax.<br />- Window ranges defined in time units are equivalent to window definitions where time is converted into milliseconds. For example, `ROWS_RANGE 10s PRECEDING ...` and `ROWS_RANGE 10000 PRECEDING...` are equivalent. | ✓ |
| Window Properties (Extended) | MAXSIZE <br>EXCLUDE CURRENT_ROW<br>EXCLUDE CURRENT_TIME<br>INSTANCE_NOT_IN_WINDOW | MAXSIZE is only valid to ROWS_RANGE <be> Without ORDER BY and EXCLUDE CURRENT_TIME cannot be used together | - |
| Multi Table Definition (Extension) | In practical use, the syntax form is relatively complex. Please refer to:<br/>[Cross Table Feature Development Tutorial](../tutorial/tutorial_sql_2.md)<br/>[WINDOW UNION Syntax Documentation](../openmldb_sql/dql/WINDOW_CLAUSE.md#1-window--union) | - Merging of multiple tables is allowed <br />- Union of simple subqueries is allowed <br />- It is commonly used in combination with aggregation functions for cross-table aggregation operations. | - |
| Incognito Window | - | Complete window definition must include `PARTITION BY`, `ORDER BY`, and window range definition. | - |

#### Special Restrictions

Expand Down Expand Up @@ -233,17 +236,17 @@ SELECT

#### Example of WINDOW ... UNION

In practical development, many applications store data in multiple tables. In such cases, the syntax `WINDOW ... UNION` is commonly used for cross-table aggregation operations. Please refer to the "Multi-Table Aggregation Features" section in the [Cross-Table Feature Development Tutorial](https://chat.openai.com/tutorial/tutorial_sql_2.md).
In practical development, many applications store data in multiple tables. In such cases, the syntax `WINDOW ... UNION` is commonly used for cross-table aggregation operations. Please refer to the "Multi-Table Aggregation Features" section in the [Cross-Table Feature Development Tutorial](../tutorial/tutorial_sql_2.md).

### LAST JOIN Clause

For detailed syntax specifications for LAST JOIN, please refer to the [LAST JOIN Documentation](https://chat.openai.com/openmldb_sql/dql/JOIN_CLAUSE.md).
For detailed syntax specifications for LAST JOIN, please refer to the [LAST JOIN Documentation](../openmldb_sql/dql/JOIN_CLAUSE.md#join-clause).

| **Statement Element** | **Support Syntax** | **Description** | Required? |
| --------------------- | ------------------ | ------------------------------------------------------------ | --------- |
| ON | ✓ | Supported column types include: BOOL, INT16, INT32, INT64, STRING, DATE, TIMESTAMP. | ✓ |
| USING | X | - | - |
| ORDER BY | ✓ | - Only the following column types can be used: INT16, INT32, INT64, TIMESTAMP. <br />- The reverse order keyword DESC is not supported. | - |
| ORDER BY | ✓ | - LAST JOIN extended syntax, not supported by LEFT JOIN. <br />- Only the following column types can be used: INT16, INT32, INT64, TIMESTAMP. <br />- The reverse order keyword DESC is not supported. | - |

#### Example of LAST JOIN

Expand All @@ -253,5 +256,11 @@ SELECT
FROM
t1
LAST JOIN t2 ON t1.col1 = t2.col1;

SELECT
*
FROM
t1
LEFT JOIN t2 ON t1.col1 = t2.col1;
```

0 comments on commit 7a76d0e

Please sign in to comment.