docs: spatial index add reculster notes (#3362)

Author: b41sh

docs/cn/sql-reference/10-sql-commands/00-ddl/07-spatial-index/create-spatial-index.md

@@ -25,6 +25,7 @@ CREATE [ OR REPLACE ] SPATIAL INDEX [IF NOT EXISTS] <index>
 - 空间索引仅支持 Fuse 表。
 - 空间索引仅支持 `GEOMETRY` 列，不支持 `GEOGRAPHY` 列。
 - 一个空间索引定义中可以包含多个列，这些列都必须是 `GEOMETRY` 类型。
+- 为了获得更好的 pruning 效果，建议结合 `CLUSTER BY` 和 `ST_HILBERT` 对地理空间数据做物理聚簇，让空间上接近的对象更有机会被写入同一个 block。
 
 ## 示例
 
@@ -35,7 +36,9 @@ CREATE TABLE stores (
     store_id INT,
     store_name STRING,
     location GEOMETRY
-) ENGINE = FUSE;
+) CLUSTER BY (
+    ST_HILBERT(location, [-180, -90, 180, 90])
+);
 ```
 
 在 `location` 列上创建空间索引：
@@ -57,18 +60,20 @@ SHOW CREATE TABLE stores;
 │        │   store_name VARCHAR NULL,                                                        │
 │        │   location GEOMETRY NULL,                                                         │
 │        │   SYNC SPATIAL INDEX stores_location_idx (location)                               │
-│        │ ) ENGINE=FUSE                                                                     │
+│        │ ) ENGINE=FUSE CLUSTER BY linear(st_hilbert(location, [-180, -90, 180, 90]))       │
 └──────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-插入一些用于空间过滤的示例数据：
+插入一些用于空间过滤的示例数据，并执行 RECLUSTER 命令：
 
 ```sql
 INSERT INTO stores VALUES
   (1, 'Starbucks', TO_GEOMETRY('POINT(10 10)')),
   (2, 'Costa', TO_GEOMETRY('POINT(11 11)')),
   (3, 'Gong Cha', TO_GEOMETRY('POINT(20 20)')),
   (4, 'Dunkin', TO_GEOMETRY('POINT(-10 -10)'));
+
+ALTER TABLE stores RECLUSTER FINAL;
 ```
 
 ### 使用 `ST_WITHIN`、`ST_INTERSECTS` 和 `ST_CONTAINS` 过滤
@@ -132,7 +137,9 @@ CREATE TABLE districts (
     district_id INT,
     district_name STRING,
     geom GEOMETRY
-) ENGINE = FUSE;
+) CLUSTER BY (
+    ST_HILBERT(geom, [-180, -90, 180, 90])
+);
 
 INSERT INTO districts VALUES
   (1, 'Central', TO_GEOMETRY('POLYGON((8 8, 8 13, 13 13, 13 8, 8 8))')),

docs/cn/sql-reference/10-sql-commands/00-ddl/17-dictionary/show-dictionaries.md

@@ -65,5 +65,5 @@ SHOW DICTIONARIES;
 ├──────────┼────────────┼───────────────┼──────────────────────────┼────────────────────────────┼─────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────┤
 │ default  │ cache      │ ["key"]       │ ["VARCHAR NULL"]         │ ["value"]                  │ ["VARCHAR NULL"]                │ redis(host=127.0.0.1 port=6379)                                                         │ cache dictionary from Redis │
 │ default  │ user_info  │ ["user_id"]   │ ["BIGINT UNSIGNED NULL"] │ ["user_name","user_email"] │ ["VARCHAR NULL","VARCHAR NULL"] │ mysql(db=app host=127.0.0.1 password=[hidden] port=3306 table=users username=root)      │ User dictionary from MySQL  │
-╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯```
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
 ```

docs/en/sql-reference/10-sql-commands/00-ddl/07-spatial-index/create-spatial-index.md

@@ -25,6 +25,7 @@ CREATE [ OR REPLACE ] SPATIAL INDEX [IF NOT EXISTS] <index>
 - Spatial indexes are supported on Fuse tables only.
 - Spatial indexes support `GEOMETRY` columns only. `GEOGRAPHY` columns are not supported.
 - Multiple columns can be indexed in a single spatial index definition as long as all of them are `GEOMETRY` columns.
+- For better pruning, it is recommended to physically cluster geospatial data with `CLUSTER BY` and `ST_HILBERT`, so nearby objects are more likely to be written into the same block.
 
 ## Examples
 
@@ -35,7 +36,9 @@ CREATE TABLE stores (
     store_id INT,
     store_name STRING,
     location GEOMETRY
-) ENGINE = FUSE;
+) CLUSTER BY (
+    ST_HILBERT(location, [-180, -90, 180, 90])
+);
 ```
 
 Create a spatial index on the `location` column:
@@ -57,18 +60,20 @@ SHOW CREATE TABLE stores;
 │        │   store_name VARCHAR NULL,                                                        │
 │        │   location GEOMETRY NULL,                                                         │
 │        │   SYNC SPATIAL INDEX stores_location_idx (location)                               │
-│        │ ) ENGINE=FUSE                                                                     │
+│        │ ) ENGINE=FUSE CLUSTER BY linear(st_hilbert(location, [-180, -90, 180, 90]))       │
 └──────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
-Load a slightly richer dataset for spatial filtering:
+Load a slightly richer dataset for spatial filtering, and run RECLUSTER command:
 
 ```sql
 INSERT INTO stores VALUES
   (1, 'Starbucks', TO_GEOMETRY('POINT(10 10)')),
   (2, 'Costa', TO_GEOMETRY('POINT(11 11)')),
   (3, 'Gong Cha', TO_GEOMETRY('POINT(20 20)')),
   (4, 'Dunkin', TO_GEOMETRY('POINT(-10 -10)'));
+
+ALTER TABLE stores RECLUSTER FINAL;
 ```
 
 ### Filter with `ST_WITHIN`, `ST_INTERSECTS`, and `ST_CONTAINS`
@@ -132,7 +137,9 @@ CREATE TABLE districts (
     district_id INT,
     district_name STRING,
     geom GEOMETRY
-) ENGINE = FUSE;
+) CLUSTER BY (
+    ST_HILBERT(geom, [-180, -90, 180, 90])
+);
 
 INSERT INTO districts VALUES
   (1, 'Central', TO_GEOMETRY('POLYGON((8 8, 8 13, 13 13, 13 8, 8 8))')),

docs/en/sql-reference/10-sql-commands/00-ddl/17-dictionary/show-dictionaries.md

@@ -65,4 +65,5 @@ SHOW DICTIONARIES;
 ├──────────┼────────────┼───────────────┼──────────────────────────┼────────────────────────────┼─────────────────────────────────┼─────────────────────────────────────────────────────────────────────────────────────────┼─────────────────────────────┤
 │ default  │ cache      │ ["key"]       │ ["VARCHAR NULL"]         │ ["value"]                  │ ["VARCHAR NULL"]                │ redis(host=127.0.0.1 port=6379)                                                         │ cache dictionary from Redis │
 │ default  │ user_info  │ ["user_id"]   │ ["BIGINT UNSIGNED NULL"] │ ["user_name","user_email"] │ ["VARCHAR NULL","VARCHAR NULL"] │ mysql(db=app host=127.0.0.1 password=[hidden] port=3306 table=users username=root)      │ User dictionary from MySQL  │
-╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯```
+╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
+```