Skip to content

Commit ac9d1f5

Browse files
wenchywenchy
committed
docs: add Multi-column OrderedIndex documentation with examples (en/zh)
1 parent b60ddd2 commit ac9d1f5

2 files changed

Lines changed: 334 additions & 10 deletions

File tree

‎content/en/docs/excel/metasheet.md‎

Lines changed: 170 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -752,10 +752,53 @@ Example: two worksheets *ItemConf* and *ShopConf* in HelloWorld.xlsx:
752752

753753
{{< sheet colored1 >}}
754754

755-
| Sheet | OrderedIndex | |
756-
| -------- | ---------------------------------------------- | --- |
757-
| ItemConf | ID@Item, Name@AwardItem, (ID,Name)@SpecialItem | |
758-
| ShopConf | ID@Shop, Type@ThemeShop, (ID,Type)@SpecialShop | |
755+
| Sheet | OrderedIndex | |
756+
| -------- | -------------------------------------------------------------------- | --- |
757+
| ItemConf | ID@Item, Name@AwardItem, (ID,Name)@SpecialItem | |
758+
| ShopConf | ID@Shop, Type@ThemeShop, (ID,Type)@SpecialShop, (ID,Type)<Type>@Shop | |
759+
760+
{{< /sheet >}}
761+
762+
{{< /spreadsheet >}}
763+
764+
Example with sorting: two worksheets *ItemConf* and *ShopConf* in HelloWorld.xlsx,
765+
with sorted result arrays using `<>` syntax:
766+
767+
- *ItemConf*: ordered index sorted by `Name` column.
768+
- *ShopConf*: ordered index sorted by `Type` and `ID` columns.
769+
770+
{{< spreadsheet "HelloWorld.xlsx" ItemConf ShopConf "@TABLEAU" >}}
771+
772+
{{< sheet colored >}}
773+
774+
| ID | Name | Desc |
775+
| ---------------- | ----------- | ----------------------------- |
776+
| map<int32, Item> | string | string |
777+
| Item's ID | Item's name | Item's desc |
778+
| 1 | Apple | A kind of delicious fruit. |
779+
| 2 | Orange | A kind of sour fruit. |
780+
| 3 | Banana | A kind of calorie-rich fruit. |
781+
782+
{{< /sheet >}}
783+
784+
{{< sheet colored >}}
785+
786+
| ID | Type | Desc |
787+
| ----------- | ----------- | ------------- |
788+
| [Shop]int32 | int32 | string |
789+
| Shop's ID | Shop's type | Shop's desc |
790+
| 1 | 1 | Shoes shop. |
791+
| 2 | 1 | T-Shirt shop. |
792+
| 3 | 2 | Fruite shop. |
793+
794+
{{< /sheet >}}
795+
796+
{{< sheet colored1 >}}
797+
798+
| Sheet | OrderedIndex | |
799+
| -------- | ---------------------------------------------------------------------- | --- |
800+
| ItemConf | ID<Name>@Item, (ID,Name)<Name>@SpecialItem | |
801+
| ShopConf | ID<Type,ID>@Shop, (ID,Type)<Type,ID>@SpecialShop, (ID,Type)<Type>@Shop | |
759802

760803
{{< /sheet >}}
761804

@@ -780,9 +823,131 @@ Examples:
780823
- `ID, Name@AwardItem`
781824
- `ID@Item, Name@AwardItem`
782825

826+
Example with sorting: a worksheet *ItemConf* in HelloWorld.xlsx, with sorted
827+
result array using `<>` syntax:
828+
829+
- `ID<Name>@Item`: single-column ordered index on `ID`, result array sorted by `Name`.
830+
831+
{{< spreadsheet "HelloWorld.xlsx" ItemConf "@TABLEAU" >}}
832+
833+
{{< sheet colored >}}
834+
835+
| ID | Name | Desc |
836+
| ---------------- | ----------- | ----------------------------- |
837+
| map<int32, Item> | string | string |
838+
| Item's ID | Item's name | Item's desc |
839+
| 1 | Apple | A kind of delicious fruit. |
840+
| 2 | Orange | A kind of sour fruit. |
841+
| 3 | Banana | A kind of calorie-rich fruit. |
842+
843+
{{< /sheet >}}
844+
845+
{{< sheet colored1 >}}
846+
847+
| Sheet | OrderedIndex |
848+
| -------- | ------------- |
849+
| ItemConf | ID<Name>@Item |
850+
851+
{{< /sheet >}}
852+
853+
{{< /spreadsheet >}}
854+
783855
### Multi-column OrderedIndex
784856

785-
> ⚠️ Not supported yet.
857+
Format: `(Column1,Column2,...)<ColumnX,ColumnY,...>@IndexName`.
858+
859+
Multi-column OrderedIndex (aka Composite OrderedIndex) is composed of **multiple columns in the same struct** (in list or map) to increase query speed, and the result is returned as an **ordered array**.
860+
861+
The sign `@` is the separator between enclosed column names by parentheses and
862+
index name. If `IndexName` is not set, it will be this column's parent struct
863+
type name. One or more indexes can be specified by comma-separated rule. The
864+
columns in the angle brackets `<>` specify the sorting columns, which the
865+
**result array** of same index key sort by.
866+
867+
Examples:
868+
869+
- `(ID,Name)`: index name not set, then determined by parent struct type name.
870+
- `(ID,Name)@AwardItem`
871+
- `(ID,Name)<ID>`: sort result array by ID.
872+
- `(ID,Type)<Type>@Shop`: sort result array by Type.
873+
- `(ID,Type)<Type,Priority>@Item`: sort result array by Type and Priority.
874+
- `ID@Item, (ID,Name)@AwardItem`: one single-column ordered index and one multi-column ordered index.
875+
876+
#### Example: Multi-column OrderedIndex
877+
878+
Two worksheets *ItemConf* and *ShopConf* in HelloWorld.xlsx:
879+
880+
- *ItemConf*: multi-column ordered index on columns of the same struct as **map value**.
881+
- *ShopConf*: multi-column ordered index on columns of the same struct as **list element**.
882+
883+
{{< spreadsheet "HelloWorld.xlsx" ItemConf ShopConf "@TABLEAU" >}}
884+
885+
{{< sheet colored >}}
886+
887+
| ID | Name | Desc |
888+
| ---------------- | ----------- | ----------------------------- |
889+
| map<int32, Item> | string | string |
890+
| Item's ID | Item's name | Item's desc |
891+
| 1 | Apple | A kind of delicious fruit. |
892+
| 2 | Orange | A kind of sour fruit. |
893+
| 3 | Banana | A kind of calorie-rich fruit. |
894+
895+
{{< /sheet >}}
896+
897+
{{< sheet colored >}}
898+
899+
| ID | Type | Desc |
900+
| ----------- | ----------- | ------------- |
901+
| [Shop]int32 | int32 | string |
902+
| Shop's ID | Shop's type | Shop's desc |
903+
| 1 | 1 | Shoes shop. |
904+
| 2 | 1 | T-Shirt shop. |
905+
| 3 | 2 | Fruite shop. |
906+
907+
{{< /sheet >}}
908+
909+
{{< sheet colored1 >}}
910+
911+
| Sheet | OrderedIndex |
912+
| -------- | ------------------------------------------- |
913+
| ItemConf | (ID,Name)@SpecialItem |
914+
| ShopConf | (ID,Type)@SpecialShop, (ID,Type)<Type>@Shop |
915+
916+
{{< /sheet >}}
917+
918+
{{< /spreadsheet >}}
919+
920+
#### Example: Multi-column OrderedIndex with `<>` syntax
921+
922+
A worksheet *ShopConf* in HelloWorld.xlsx, with sorted
923+
result array using `<>` syntax:
924+
925+
- `(ID,Type)<Type>@Shop`: multi-column ordered index on `(ID, Type)`, result array sorted by `Type`.
926+
- `(ID,Type)<Type,ID>@SpecialShop`: multi-column ordered index on `(ID, Type)`, result array sorted by `Type` then `ID`.
927+
928+
{{< spreadsheet "HelloWorld.xlsx" ShopConf "@TABLEAU" >}}
929+
930+
{{< sheet colored >}}
931+
932+
| ID | Type | Desc |
933+
| ----------- | ----------- | ------------- |
934+
| [Shop]int32 | int32 | string |
935+
| Shop's ID | Shop's type | Shop's desc |
936+
| 1 | 1 | Shoes shop. |
937+
| 2 | 1 | T-Shirt shop. |
938+
| 3 | 2 | Fruite shop. |
939+
940+
{{< /sheet >}}
941+
942+
{{< sheet colored1 >}}
943+
944+
| Sheet | OrderedIndex |
945+
| -------- | ---------------------------------------------------- |
946+
| ShopConf | (ID,Type)<Type>@Shop, (ID,Type)<Type,ID>@SpecialShop |
947+
948+
{{< /sheet >}}
949+
950+
{{< /spreadsheet >}}
786951

787952
## Option `Patch`
788953

‎content/zh/docs/excel/metasheet.md‎

Lines changed: 164 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -741,10 +741,53 @@ message ZoneConf {
741741

742742
{{< sheet colored1 >}}
743743

744-
| Sheet | OrderedIndex | |
745-
| -------- | ---------------------------------------------- | --- |
746-
| ItemConf | ID@Item, Name@AwardItem, (ID,Name)@SpecialItem | |
747-
| ShopConf | ID@Shop, Type@ThemeShop, (ID,Type)@SpecialShop | |
744+
| Sheet | OrderedIndex | |
745+
| -------- | -------------------------------------------------------------------- | --- |
746+
| ItemConf | ID@Item, Name@AwardItem, (ID,Name)@SpecialItem | |
747+
| ShopConf | ID@Shop, Type@ThemeShop, (ID,Type)@SpecialShop, (ID,Type)<Type>@Shop | |
748+
749+
{{< /sheet >}}
750+
751+
{{< /spreadsheet >}}
752+
753+
带排序的示例：*HelloWorld.xlsx* 中的两个 worksheet *ItemConf* 和 *ShopConf*，
754+
使用 `<>` 语法对结果数组进行排序：
755+
756+
- *ItemConf*：ordered index 结果按 `Name` 列排序。
757+
- *ShopConf*：ordered index 结果按 `Type` 和 `ID` 列排序。
758+
759+
{{< spreadsheet "HelloWorld.xlsx" ItemConf ShopConf "@TABLEAU" >}}
760+
761+
{{< sheet colored >}}
762+
763+
| ID | Name | Desc |
764+
| ---------------- | ----------- | ----------------------------- |
765+
| map<int32, Item> | string | string |
766+
| Item's ID | Item's name | Item's desc |
767+
| 1 | Apple | A kind of delicious fruit. |
768+
| 2 | Orange | A kind of sour fruit. |
769+
| 3 | Banana | A kind of calorie-rich fruit. |
770+
771+
{{< /sheet >}}
772+
773+
{{< sheet colored >}}
774+
775+
| ID | Type | Desc |
776+
| ----------- | ----------- | ------------- |
777+
| [Shop]int32 | int32 | string |
778+
| Shop's ID | Shop's type | Shop's desc |
779+
| 1 | 1 | Shoes shop. |
780+
| 2 | 1 | T-Shirt shop. |
781+
| 3 | 2 | Fruite shop. |
782+
783+
{{< /sheet >}}
784+
785+
{{< sheet colored1 >}}
786+
787+
| Sheet | OrderedIndex | |
788+
| -------- | ---------------------------------------------------------------------- | --- |
789+
| ItemConf | ID<Name>@Item, (ID,Name)<Name>@SpecialItem | |
790+
| ShopConf | ID<Type,ID>@Shop, (ID,Type)<Type,ID>@SpecialShop, (ID,Type)<Type>@Shop | |
748791

749792
{{< /sheet >}}
750793

@@ -765,9 +808,125 @@ message ZoneConf {
765808
- `ID, Name@AwardItem`
766809
- `ID@Item, Name@AwardItem`
767810

811+
带排序的示例：*HelloWorld.xlsx* 中的 worksheet *ItemConf*，使用 `<>` 语法对结果数组进行排序：
812+
813+
- `ID<Name>@Item`：对 `ID` 列建立单列 ordered index，结果数组按 `Name` 排序。
814+
815+
{{< spreadsheet "HelloWorld.xlsx" ItemConf "@TABLEAU" >}}
816+
817+
{{< sheet colored >}}
818+
819+
| ID | Name | Desc |
820+
| ---------------- | ----------- | ----------------------------- |
821+
| map<int32, Item> | string | string |
822+
| Item's ID | Item's name | Item's desc |
823+
| 1 | Apple | A kind of delicious fruit. |
824+
| 2 | Orange | A kind of sour fruit. |
825+
| 3 | Banana | A kind of calorie-rich fruit. |
826+
827+
{{< /sheet >}}
828+
829+
{{< sheet colored1 >}}
830+
831+
| Sheet | OrderedIndex |
832+
| -------- | ------------- |
833+
| ItemConf | ID<Name>@Item |
834+
835+
{{< /sheet >}}
836+
837+
{{< /spreadsheet >}}
838+
768839
### 多列 OrderedIndex
769840

770-
> ⚠️ 暂不支持。
841+
格式：`(Column1,Column2,...)<ColumnX,ColumnY,...>@IndexName`。
842+
843+
多列 OrderedIndex（又称 Composite OrderedIndex）由同一 struct（list 或 map 中）的**多列**组成，以提高查询速度，查询结果以**有序数组**形式返回。
844+
845+
`@` 是括号内列名和 index 名之间的分隔符。如果未设置 `IndexName`，则使用该列的父 struct 类型名。可以用逗号分隔指定一个或多个 index。尖括号 `<>` 中的列指定排序列，**结果数组**按相同 index key 排序。
846+
847+
示例：
848+
849+
- `(ID,Name)`：未设置 index 名，由父 struct 类型名决定。
850+
- `(ID,Name)@AwardItem`
851+
- `(ID,Name)<ID>`：结果数组按 ID 排序。
852+
- `(ID,Type)<Type>@Shop`：结果数组按 Type 排序。
853+
- `(ID,Type)<Type,Priority>@Item`：结果数组按 Type 和 Priority 排序。
854+
- `ID@Item, (ID,Name)@AwardItem`：一个单列 ordered index 和一个多列 ordered index。
855+
856+
#### 示例：多列 OrderedIndex
857+
858+
*HelloWorld.xlsx* 中的两个 worksheet *ItemConf* 和 *ShopConf*：
859+
860+
- *ItemConf*：对 **map value** 同一 struct 的列建立多列 ordered index。
861+
- *ShopConf*：对 **list element** 同一 struct 的列建立多列 ordered index。
862+
863+
{{< spreadsheet "HelloWorld.xlsx" ItemConf ShopConf "@TABLEAU" >}}
864+
865+
{{< sheet colored >}}
866+
867+
| ID | Name | Desc |
868+
| ---------------- | ----------- | ----------------------------- |
869+
| map<int32, Item> | string | string |
870+
| Item's ID | Item's name | Item's desc |
871+
| 1 | Apple | A kind of delicious fruit. |
872+
| 2 | Orange | A kind of sour fruit. |
873+
| 3 | Banana | A kind of calorie-rich fruit. |
874+
875+
{{< /sheet >}}
876+
877+
{{< sheet colored >}}
878+
879+
| ID | Type | Desc |
880+
| ----------- | ----------- | ------------- |
881+
| [Shop]int32 | int32 | string |
882+
| Shop's ID | Shop's type | Shop's desc |
883+
| 1 | 1 | Shoes shop. |
884+
| 2 | 1 | T-Shirt shop. |
885+
| 3 | 2 | Fruite shop. |
886+
887+
{{< /sheet >}}
888+
889+
{{< sheet colored1 >}}
890+
891+
| Sheet | OrderedIndex |
892+
| -------- | ------------------------------------------- |
893+
| ItemConf | (ID,Name)@SpecialItem |
894+
| ShopConf | (ID,Type)@SpecialShop, (ID,Type)<Type>@Shop |
895+
896+
{{< /sheet >}}
897+
898+
{{< /spreadsheet >}}
899+
900+
#### 示例：多列 OrderedIndex 使用 `<>` 语法
901+
902+
*HelloWorld.xlsx* 中的 worksheet *ShopConf*，使用 `<>` 语法对结果数组进行排序：
903+
904+
- `(ID,Type)<Type>@Shop`：对 `(ID, Type)` 列建立多列 ordered index，结果数组按 `Type` 排序。
905+
- `(ID,Type)<Type,ID>@SpecialShop`：对 `(ID, Type)` 列建立多列 ordered index，结果数组按 `Type` 然后 `ID` 排序。
906+
907+
{{< spreadsheet "HelloWorld.xlsx" ShopConf "@TABLEAU" >}}
908+
909+
{{< sheet colored >}}
910+
911+
| ID | Type | Desc |
912+
| ----------- | ----------- | ------------- |
913+
| [Shop]int32 | int32 | string |
914+
| Shop's ID | Shop's type | Shop's desc |
915+
| 1 | 1 | Shoes shop. |
916+
| 2 | 1 | T-Shirt shop. |
917+
| 3 | 2 | Fruite shop. |
918+
919+
{{< /sheet >}}
920+
921+
{{< sheet colored1 >}}
922+
923+
| Sheet | OrderedIndex |
924+
| -------- | ---------------------------------------------------- |
925+
| ShopConf | (ID,Type)<Type>@Shop, (ID,Type)<Type,ID>@SpecialShop |
926+
927+
{{< /sheet >}}
928+
929+
{{< /spreadsheet >}}
771930

772931
## 选项 `Patch`
773932

0 commit comments

Comments
 (0)