From 2e4a2713ec5d36ad4be6e49b0f1d492b92be7659 Mon Sep 17 00:00:00 2001 From: linzhenqi Date: Thu, 25 Jun 2026 06:17:32 +0800 Subject: [PATCH 1/2] [Fix](doc) Fix and Add some function document --- .../distance-functions/cosine-similarity.md | 102 +++++++++++++ .../array-functions/array-cum-sum.md | 3 +- .../date-time-functions/quarter-ceil.md | 71 +++++++++ .../date-time-functions/quarter-floor.md | 71 +++++++++ .../date-time-functions/quarters-diff.md | 42 ++++++ .../spatial-functions/st-geometries.md | 131 +++++++++++++++++ .../spatial-functions/st-numgeometries.md | 107 ++++++++++++++ .../spatial-functions/st-numpoints.md | 134 +++++++++++++++++ .../distance-functions/cosine-similarity.md | 102 +++++++++++++ .../date-time-functions/quarter-ceil.md | 71 +++++++++ .../date-time-functions/quarter-floor.md | 74 ++++++++++ .../date-time-functions/quarters-diff.md | 42 ++++++ .../spatial-functions/st-geometries.md | 131 +++++++++++++++++ .../spatial-functions/st-numgeometries.md | 107 ++++++++++++++ .../spatial-functions/st-numpoints.md | 134 +++++++++++++++++ .../numeric-functions/fmod.md | 12 +- .../date-time-functions/quarter-ceil.md | 75 ++++++++++ .../date-time-functions/quarter-floor.md | 74 ++++++++++ .../date-time-functions/quarters-diff.md | 46 ++++++ .../distance-functions/cosine-distance.md | 4 +- .../distance-functions/l2-distance.md | 2 +- .../distance-functions/cosine-similarity.md | 106 ++++++++++++++ .../date-time-functions/quarter-ceil.md | 71 +++++++++ .../date-time-functions/quarter-floor.md | 70 +++++++++ .../date-time-functions/quarters-diff.md | 42 ++++++ .../spatial-functions/st-geometries.md | 135 +++++++++++++++++ .../spatial-functions/st-numgeometries.md | 111 ++++++++++++++ .../spatial-functions/st-numpoints.md | 138 ++++++++++++++++++ sidebars.ts | 1 + .../numeric-functions/fmod.md | 12 +- .../date-time-functions/date-ceil.md | 2 +- .../date-time-functions/quarter-ceil.md | 75 ++++++++++ .../date-time-functions/quarter-floor.md | 75 ++++++++++ .../date-time-functions/quarters-diff.md | 46 ++++++ .../distance-functions/cosine-distance.md | 4 +- .../distance-functions/l2-distance.md | 2 +- .../distance-functions/cosine-similarity.md | 106 ++++++++++++++ .../date-time-functions/quarter-ceil.md | 71 +++++++++ .../date-time-functions/quarter-floor.md | 71 +++++++++ .../date-time-functions/quarters-diff.md | 42 ++++++ .../spatial-functions/st-geometries.md | 135 +++++++++++++++++ .../spatial-functions/st-numgeometries.md | 111 ++++++++++++++ .../spatial-functions/st-numpoints.md | 138 ++++++++++++++++++ versioned_sidebars/version-3.x-sidebars.json | 3 + versioned_sidebars/version-4.x-sidebars.json | 4 + 45 files changed, 3085 insertions(+), 21 deletions(-) create mode 100644 docs/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md create mode 100644 docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md create mode 100644 i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md create mode 100644 versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md create mode 100644 versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md create mode 100644 versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md create mode 100644 versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md diff --git a/docs/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md b/docs/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md new file mode 100644 index 0000000000000..66f5fe513767e --- /dev/null +++ b/docs/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md @@ -0,0 +1,102 @@ +--- +{ + "title": "COSINE_SIMILARITY", + "language": "en", + "description": "Calculates the cosine similarity between two vectors." +} +--- + +## Description + +Calculates the cosine similarity between two vectors. +The similarity is computed from the dot product and vector norms, and the result is in `[-1, 1]`. + +## Syntax + +```sql +COSINE_SIMILARITY(, ) +``` + +## Parameters + +| Parameter | Description | +|---|--| +| `` | The first vector. The input type must be `ARRAY`. | +| `` | The second vector. The input type must be `ARRAY`, and the number of elements must be the same as ``. | + +## Return Value + +Returns the cosine similarity between two vectors, in FLOAT type. +If the input array is `NULL`, or any element in the array is `NULL`, an error is returned. +If the two arrays have different numbers of elements, an error is returned. +If the array is empty, or either vector is a zero vector, `0.0` is returned. + +## Example + +```sql +-- Two identical vectors have similarity 1 +SELECT COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]) | ++-----------------------------------------+ +| 1 | ++-----------------------------------------+ +``` + +`[1, 2, 3]` and `[1, 2, 3]` point in the same direction, so the similarity is `1`. + +```sql +-- Orthogonal vectors have similarity 0 +SELECT COSINE_SIMILARITY([1, 0], [0, 1]); +``` + +```text ++-----------------------------------+ +| COSINE_SIMILARITY([1, 0], [0, 1]) | ++-----------------------------------+ +| 0 | ++-----------------------------------+ +``` + +The vectors are orthogonal, so their dot product is `0` and the similarity is `0`. + +```sql +-- A zero vector returns 0 +SELECT COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]) | ++-----------------------------------------+ +| 0 | ++-----------------------------------------+ +``` + +A zero vector has no valid direction, so the result is `0`. + +```sql +-- An empty array returns 0 +SELECT COSINE_SIMILARITY([], []); +``` + +```text ++---------------------------+ +| COSINE_SIMILARITY([], []) | ++---------------------------+ +| 0 | ++---------------------------+ +``` + +```sql +-- NULL inside the input array raises an error +SELECT COSINE_SIMILARITY([1, NULL, 3], [1, 2, 3]); +``` + +```text +ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]First argument for function cosine_similarity cannot have null +``` + diff --git a/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-cum-sum.md b/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-cum-sum.md index 95a269c29cd8c..0688655c9a93f 100644 --- a/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-cum-sum.md +++ b/docs/sql-manual/sql-functions/scalar-functions/array-functions/array-cum-sum.md @@ -103,8 +103,7 @@ SELECT array_cum_sum(['a', 1, 'b', 2, 'c', 3]); | [null, 1, null, 3, null, 6] | +-----------------------------------------+ ``` -Hello Hello.,Hello123hello -Hello Hello.,Hello123hello + Empty array returns empty array: ```sql SELECT array_cum_sum(int_array) FROM array_cum_sum_test WHERE id = 3; diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md new file mode 100644 index 0000000000000..4d09659028f72 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md @@ -0,0 +1,71 @@ +--- +{ + "title": "QUARTER_CEIL", + "language": "en" +} +--- + +## Description + +Rounds a datetime value up to the nearest specified quarter period boundary. If an origin time is specified, the period is calculated based on that time. + +## Syntax + +```sql +QUARTER_CEIL() +QUARTER_CEIL(, ) +QUARTER_CEIL(, ) +QUARTER_CEIL(, , ) +``` + +## Parameters + +| Parameter | Description | +| ---- | ---- | +| `` | The datetime value to round up, type is DATE or DATETIME | +| `` | Quarter period value, type is INT, representing the number of quarters contained in each period | +| `` | The starting point of the period, type is DATE or DATETIME, default value is 0001-01-01 00:00:00 | + +Notes: +- When period is not specified, it is equivalent to using 1 quarter as the period +- When period is not a positive integer, the function result will be NULL +- The result always rounds to the future time +- The time part of the return value is always 00:00:00 + +## Return Value + +When `` is of DATE type, the return type is DATE. +When `` is of DATETIME type, the return type is DATETIME. +Represents the rounded up datetime value. The time part of the result will be set to 00:00:00. + +## Examples + +Starting from '0001-01-01 00:00:00', with periods of 5 / 4 quarters each, return the next period start point closest to the input date. +```sql +SELECT QUARTER_CEIL("2023-07-13 22:28:18", 5), QUARTER_CEIL("2023-07-13 22:28:18", 4); +``` + +```text ++----------------------------------------+----------------------------------------+ +| QUARTER_CEIL("2023-07-13 22:28:18", 5) | QUARTER_CEIL("2023-07-13 22:28:18", 4) | ++----------------------------------------+----------------------------------------+ +| 2024-10-01 00:00:00.000000 | 2024-01-01 00:00:00.000000 | ++----------------------------------------+----------------------------------------+ +``` + +Using '2022-01-01 00:00:00' as the period start point, with periods of 2 / 4 quarters each, return the next period start point closest to the input date. +```sql +SELECT QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++---------------------------------------------------------------+---------------------------------------------------------------+ +| QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2024-01-01 00:00:00 | ++---------------------------------------------------------------+---------------------------------------------------------------+ +``` + +## Best Practices + +See also [date_ceil](./date-ceil) diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md new file mode 100644 index 0000000000000..ec87ef601f42c --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -0,0 +1,71 @@ +--- +{ + "title": "QUARTER_FLOOR", + "language": "en" +} +--- + +## Description + +Rounds a datetime value down to the nearest specified quarter period boundary. If an origin time is specified, the period is calculated based on that time. + +## Syntax + +```sql +QUARTER_FLOOR() +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, , ) +``` + +## Parameters + +| Parameter | Description | +| ---- | ---- | +| `` | The datetime value to round down, type is DATE or DATETIME | +| `` | Quarter period value, type is INT, representing the number of quarters contained in each period | +| `` | The starting point of the period, type is DATE or DATETIME, default value is 0001-01-01 00:00:00 | + +Notes: +- When period is not specified, it is equivalent to using 1 quarter as the period +- When period is not a positive integer, the function result will be NULL +- The result always rounds to the past time +- The time part of the return value is always 00:00:00 + +## Return Value + +When `` is of DATE type, the return type is DATE. +When `` is of DATETIME type, the return type is DATETIME. +The time part of the result will be set to 00:00:00. + +## Examples + +Starting from '0001-01-01 00:00:00', with periods of 5 / 4 quarters each, return the period start point closest to the input date. +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 5), QUARTER_FLOOR("2023-07-13 22:28:18", 4); +``` + +```text ++-----------------------------------------+-----------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 5) | QUARTER_FLOOR("2023-07-13 22:28:18", 4) | ++-----------------------------------------+-----------------------------------------+ +| 2021-01-01 00:00:00 | 2022-01-01 00:00:00 | ++-----------------------------------------+-----------------------------------------+ +``` + +Using '2022-01-01 00:00:00' as the period start point, with periods of 2 / 4 quarters each, return the period start point closest to the input date. +```sql +SELECT QUARTER_FLOOR("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++----------------------------------------------------------------+----------------------------------------------------------------+ +| QUARTER_FLOOR("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++----------------------------------------------------------------+----------------------------------------------------------------+ +| 2023-01-01 00:00:00 | 2022-01-01 00:00:00 | ++----------------------------------------------------------------+----------------------------------------------------------------+ +``` + +## Best Practices + +See also [date_floor](./date-floor) diff --git a/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md new file mode 100644 index 0000000000000..0254834a3ef20 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md @@ -0,0 +1,42 @@ +--- +{ + "title": "QUARTERS_DIFF", + "language": "en" +} +--- + +## Description + +The `QUARTERS_DIFF` function calculates the number of quarters between two dates. This function accepts two date parameters and returns the difference in quarters after subtracting the second date from the first date. The difference in quarters is equivalent to the difference in months divided by 3 (rounded towards zero). + +## Syntax + +```sql +QUARTERS_DIFF(, ) +``` + +## Parameters + +| Parameter | Description | +|---------------|--------------------------------------------------------------------------------------| +| `` | End date, represents the later date when calculating the difference. Supports `DATE` or `DATETIME` types | +| `` | Start date, represents the earlier date when calculating the difference. Supports `DATE` or `DATETIME` types | + +## Return Value + +Returns the number of quarters obtained by subtracting `` from `` +- When either `` or `` is NULL, returns NULL + +## Examples + +```sql +select QUARTERS_DIFF('2021-03-25', '2020-10-25'), QUARTERS_DIFF('2020-10-25 10:00:00', '2022-12-25 11:00:00'); +``` + +```text ++------------------------------------------+------------------------------------------------------------+ +| QUARTERS_DIFF('2021-03-25','2020-10-25') | QUARTERS_DIFF('2020-10-25 10:00:00','2022-12-25 11:00:00') | ++------------------------------------------+------------------------------------------------------------+ +| 1 | -8 | ++------------------------------------------+------------------------------------------------------------+ +``` diff --git a/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md b/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md new file mode 100644 index 0000000000000..81d0910752f41 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md @@ -0,0 +1,131 @@ +--- +{ + "title": "ST_GEOMETRIES", + "language": "en", + "description": "Returns an array of sub-geometries from a geometry collection." +} +--- + +## Description + +Decomposes a geometry object into an array of its sub-geometries. For collection types (MultiPolygon), it returns each sub-polygon as a separate element in the array. For non-collection types (Point, LineString, Polygon, Circle), it returns a single-element array containing the geometry itself. + +## Syntax + +```sql +ST_GEOMETRIES( ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The input geometry, of type GEOMETRY or VARCHAR (in WKT format) that can be converted to GEOMETRY. | + +## Return Value + +Returns an `ARRAY` where each element is an encoded geometry object that can be used with other spatial functions such as `ST_AsText` or `ST_GeometryType`. + +`ST_GEOMETRIES` has the following edge cases: +- If the input parameter is `NULL`, returns `NULL`. +- If the input parameter cannot be parsed into a valid geometry object, returns `NULL`. +- For non-collection types (`POINT`, `LINESTRING`, `POLYGON`, `CIRCLE`), returns a single-element array containing the input geometry. +- For `MULTIPOLYGON`, returns an array where each element is one of the sub-polygons. +- Array elements can be passed to other spatial functions for further processing. + +## Example + +**Geometries of a Point (single-element array)** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]); +``` +```text ++------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]) | ++------------------------------------------------+ +| POINT (1 2) | ++------------------------------------------------+ +``` + +**Geometries of a Polygon (single-element array)** +```sql +SELECT ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------+ +| ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]) | ++----------------------------------------------------------------------------------------------------+ +| ST_POLYGON | ++----------------------------------------------------------------------------------------------------+ +``` + +**Geometries of a MultiPolygon (multiple elements)** +```sql +SELECT SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))); +``` +```text ++----------------------------------------------------------------------------------------------------------------------+ +| SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))))') | ++----------------------------------------------------------------------------------------------------------------------+ +| 2 | ++----------------------------------------------------------------------------------------------------------------------+ +``` + +**Accessing individual elements of a MultiPolygon** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((3 2, 3 3, 2 3, 2 2, 3 2)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +**Out-of-bound index (Returns NULL)** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3]; +``` +```text ++----------------------------------------------------------------------------------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3] | ++----------------------------------------------------------------------------------------------------------------------------+ +| NULL | ++----------------------------------------------------------------------------------------------------------------------------+ +``` + +**NULL Parameter** +```sql +SELECT ST_GEOMETRIES(NULL); +``` +```text ++----------------------+ +| ST_GEOMETRIES(NULL) | ++----------------------+ +| NULL | ++----------------------+ +``` + +**Invalid Parameter (Returns NULL)** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++----------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('INVALID')) | ++----------------------------------------------------+ +| NULL | ++----------------------------------------------------+ +``` \ No newline at end of file diff --git a/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md b/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md new file mode 100644 index 0000000000000..d750e6cff59f7 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md @@ -0,0 +1,107 @@ +--- +{ + "title": "ST_NUMGEOMETRIES", + "language": "en", + "description": "Returns the number of geometries in a geometry collection." +} +--- + +## Description + +Returns the number of sub-geometries contained in a geometry object. For non-collection types (Point, LineString, Polygon, Circle), it always returns 1. For collection types (MultiPolygon), it returns the number of sub-geometries in the collection. + +## Syntax + +```sql +ST_NUMGEOMETRIES( ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The input geometry, of type GEOMETRY or VARCHAR (in WKT format) that can be converted to GEOMETRY. | + +## Return Value + +Returns a BIGINT value representing the number of sub-geometries in the geometry object. + +`ST_NUMGEOMETRIES` has the following edge cases: +- If the input parameter is `NULL`, returns `NULL`. +- If the input parameter cannot be parsed into a valid geometry object, returns `NULL`. +- For non-collection types (`POINT`, `LINESTRING`, `POLYGON`, `CIRCLE`), always returns `1`. +- For `MULTIPOLYGON`, returns the number of polygons in the collection. + +## Example + +**Number of geometries in a Point** +```sql +SELECT ST_NUMGEOMETRIES(ST_Point(1, 2)); +``` +```text ++----------------------------------+ +| ST_NUMGEOMETRIES(ST_Point(1, 2)) | ++----------------------------------+ +| 1 | ++----------------------------------+ +``` + +**Number of geometries in a Polygon** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++------------------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------------------+ +``` + +**Number of geometries in a MultiPolygon with two polygons** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++------------------------------------------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++------------------------------------------------------------------------------------------------------------------+ +| 2 | ++------------------------------------------------------------------------------------------------------------------+ +``` + +**Number of geometries in a Circle** +```sql +SELECT ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)); +``` +```text ++----------------------------------------+ +| ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)) | ++----------------------------------------+ +| 1 | ++----------------------------------------+ +``` + +**NULL Parameter** +```sql +SELECT ST_NUMGEOMETRIES(NULL); +``` +```text ++------------------------+ +| ST_NUMGEOMETRIES(NULL) | ++------------------------+ +| NULL | ++------------------------+ +``` + +**Invalid Parameter (Returns NULL)** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++--------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')) | ++--------------------------------------------------+ +| NULL | ++--------------------------------------------------+ +``` \ No newline at end of file diff --git a/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md b/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md new file mode 100644 index 0000000000000..1546b089112d3 --- /dev/null +++ b/docs/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md @@ -0,0 +1,134 @@ +--- +{ + "title": "ST_NUMPOINTS", + "language": "en", + "description": "Returns the total number of points in a geometry object." +} +--- + +## Description + +Returns the total number of vertices (points) in a geometry object. For different geometry types, the counting rules are as follows: a Point returns 1, a LineString returns the number of vertices, a Polygon returns the total number of vertices across all rings (including the closing point), and a MultiPolygon returns the sum of all sub-polygon point counts. + +## Syntax + +```sql +ST_NUMPOINTS( ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The input geometry, of type GEOMETRY or VARCHAR (in WKT format) that can be converted to GEOMETRY. | + +## Return Value + +Returns a BIGINT value representing the total number of points in the geometry object. + +`ST_NUMPOINTS` has the following edge cases: +- If the input parameter is `NULL`, returns `NULL`. +- If the input parameter cannot be parsed into a valid geometry object, returns `NULL`. +- For `POINT`, returns `1`. +- For `LINESTRING`, returns the number of vertices in the line. +- For `POLYGON`, returns the total number of vertices across all rings (exterior ring + interior rings). Each ring includes the closing point. +- For `MULTIPOLYGON`, returns the sum of point counts of all sub-polygons. +- For `CIRCLE`, returns `-1` (circles do not have discrete vertices). + +## Example + +**Number of points in a Point** +```sql +SELECT ST_NUMPOINTS(ST_Point(1, 2)); +``` +```text ++------------------------------+ +| ST_NUMPOINTS(ST_Point(1, 2)) | ++------------------------------+ +| 1 | ++------------------------------+ +``` + +**Number of points in a LineString** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')); +``` +```text ++-------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')) | ++-------------------------------------------------------------------+ +| 3 | ++-------------------------------------------------------------------+ +``` + +**Number of points in a Polygon (square)** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++----------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++----------------------------------------------------------------------------+ +| 5 | ++----------------------------------------------------------------------------+ +``` + +**Number of points in a Polygon with a hole** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')); +``` +```text ++-----------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')) | ++-----------------------------------------------------------------------------------------------------------+ +| 10 | ++-----------------------------------------------------------------------------------------------------------+ +``` + +**Number of points in a MultiPolygon** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++--------------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++--------------------------------------------------------------------------------------------------------------+ +| 10 | ++--------------------------------------------------------------------------------------------------------------+ +``` + +**Number of points in a Circle (returns -1)** +```sql +SELECT ST_NUMPOINTS(ST_Circle(0, 0, 100)); +``` +```text ++--------------------------------------+ +| ST_NUMPOINTS(ST_Circle(0, 0, 100)) | ++--------------------------------------+ +| -1 | ++--------------------------------------+ +``` + +**NULL Parameter** +```sql +SELECT ST_NUMPOINTS(NULL); +``` +```text ++---------------------+ +| ST_NUMPOINTS(NULL) | ++---------------------+ +| NULL | ++---------------------+ +``` + +**Invalid Parameter (Returns NULL)** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('INVALID')); +``` +```text ++------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('INVALID')) | ++------------------------------------------------+ +| NULL | ++------------------------------------------------+ +``` \ No newline at end of file diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md new file mode 100644 index 0000000000000..3672482b93eeb --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md @@ -0,0 +1,102 @@ +--- +{ + "title": "COSINE_SIMILARITY", + "language": "zh-CN", + "description": "计算两个向量之间的余弦相似度" +} +--- + +## 描述 + +计算两个向量之间的余弦相似度。 +函数按照向量的点积与模长计算相似度，结果范围为 `[-1, 1]`。 + +## 语法 + +```sql +COSINE_SIMILARITY(, ) +``` + +## 参数 + +| 参数 | 说明 | +| -- | -- | +| `` | 第一个向量。类型必须为 `ARRAY`。 | +| `` | 第二个向量。类型必须为 `ARRAY`，且元素个数需与 `` 一致。 | + +## 返回值 + +返回两个向量的余弦相似度，类型为 FLOAT。 +如果输入数组为 `NULL`，或者数组中包含 `NULL` 元素，则报错。 +如果两个数组的元素个数不一致，则报错。 +如果数组为空，或者任一向量为零向量，则返回 `0.0`。 + +## 举例 + +```sql +-- 两个向量完全相同，相似度为 1 +SELECT COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]) | ++-----------------------------------------+ +| 1 | ++-----------------------------------------+ +``` + +`[1, 2, 3]` 与 `[1, 2, 3]` 的方向完全一致，因此相似度为 `1`。 + +```sql +-- 两个向量正交，相似度为 0 +SELECT COSINE_SIMILARITY([1, 0], [0, 1]); +``` + +```text ++-----------------------------------+ +| COSINE_SIMILARITY([1, 0], [0, 1]) | ++-----------------------------------+ +| 0 | ++-----------------------------------+ +``` + +两个向量互相垂直，点积为 `0`，因此相似度为 `0`。 + +```sql +-- 任一向量为零向量时，返回 0 +SELECT COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]) | ++-----------------------------------------+ +| 0 | ++-----------------------------------------+ +``` + +零向量没有有效方向，因此结果为 `0`。 + +```sql +-- 空数组返回 0 +SELECT COSINE_SIMILARITY([], []); +``` + +```text ++---------------------------+ +| COSINE_SIMILARITY([], []) | ++---------------------------+ +| 0 | ++---------------------------+ +``` + +```sql +-- 输入数组中包含 NULL，会报错 +SELECT COSINE_SIMILARITY([1, NULL, 3], [1, 2, 3]); +``` + +```text +ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]First argument for function cosine_similarity cannot have null +``` + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md new file mode 100644 index 0000000000000..40c157841d792 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md @@ -0,0 +1,71 @@ +--- +{ + "title": "QUARTER_CEIL", + "language": "zh-CN" +} +--- + +## 描述 + +将日期时间值向上取整到最近的指定季度周期的下个周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 + +## 语法 + +```sql +QUARTER_CEIL() +QUARTER_CEIL(, ) +QUARTER_CEIL(, ) +QUARTER_CEIL(, , ) +``` + +## 参数 + +| 参数 | 说明 | +| ---- | ---- | +| `` | 需要向上取整的日期时间值，类型为 DATE 或 DATETIME | +| `` | 季度周期值，类型为 INT，表示每个周期包含的季度数 | +| `` | 周期的起始时间点，类型为 DATE 或 DATETIME，默认值为 0001-01-01 00:00:00 | + +注意： +- 不指定 period 时，等价于以 1 个季度为周期 +- 当 period 不为正整数时，函数结果将为 NULL +- 结果总是向过去时间取整 +- 返回值的时间部分总是 00:00:00 + +## 返回值 + +当 `` 为 DATE 类型时，返回类型为 DATE。 +当 `` 为 DATETIME 类型时，返回类型为 DATETIME。 +表示向上取整后的日期时间值。结果的时间部分将被设置为 00:00:00。 + +## 举例 + +从 '0001-01-01 00:00:00' 开始，每 5 / 4 个季度为一个周期，返回距离输入日期最近的下一个周期起点。 +```sql +SELECT QUARTER_CEIL("2023-07-13 22:28:18", 5), QUARTER_CEIL("2023-07-13 22:28:18", 4); +``` + +```text ++----------------------------------------+----------------------------------------+ +| QUARTER_CEIL("2023-07-13 22:28:18", 5) | QUARTER_CEIL("2023-07-13 22:28:18", 4) | ++----------------------------------------+----------------------------------------+ +| 2024-10-01 00:00:00.000000 | 2024-01-01 00:00:00.000000 | ++----------------------------------------+----------------------------------------+ +``` + +以 '2022-01-01 00:00:00' 为周期起点，分别以 2 / 4 个季度为一个周期，返回距离输入日期最近的下一个周期起点。 +```sql +SELECT QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++---------------------------------------------------------------+---------------------------------------------------------------+ +| QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2024-01-01 00:00:00 | ++---------------------------------------------------------------+---------------------------------------------------------------+ +``` + +## 最佳实践 + +还可参阅 [date_ceil](./date-ceil) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md new file mode 100644 index 0000000000000..79271e5ed3065 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -0,0 +1,74 @@ +--- +{ + "title": "QUARTER_FLOOR", + "language": "zh-CN" +} +--- + +## 描述 + +将日期时间值向下取整到最近的指定季度周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 + +:::tip +QUARTER_FLOOR 支持从 3.0.8 和 3.1.0 版本开始。 +::: + +## 语法 + +```sql +QUARTER_FLOOR() +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, , ) +``` + +## 参数 + +| 参数 | 说明 | +| ---- | ---- | +| `` | 需要向下取整的日期时间值，类型为 DATE 或 DATETIME | +| `` | 季度周期值，类型为 INT，表示每个周期包含的季度数 | +| `` | 周期的起始时间点，类型为 DATE 或 DATETIME，默认值为 0001-01-01 00:00:00 | + +注意： +- 不指定 period 时，等价于以 1 个季度为周期 +- 当 period 不为正整数时，函数结果将为 NULL +- 结果总是向过去时间取整 +- 返回值的时间部分总是 00:00:00 + +## 返回值 + +当 `` 为 DATE 类型时，返回类型为 DATE。 +当 `` 为 DATETIME 类型时，返回类型为 DATETIME。 +结果的时间部分将被设置为 00:00:00。 + +## 举例 + +从 '0001-01-01 00:00:00' 开始，每 5 / 4 个季度为一个周期，返回距离输入日期最近的周期起点。 +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 5), QUARTER_FLOOR("2023-07-13 22:28:18", 4); +``` + +```text ++-----------------------------------------+-----------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 5) | QUARTER_FLOOR("2023-07-13 22:28:18", 4) | ++-----------------------------------------+-----------------------------------------+ +| 2021-01-01 00:00:00 | 2022-01-01 00:00:00 | ++-----------------------------------------+-----------------------------------------+ +``` + +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++----------------------------------------------------------------+----------------------------------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++----------------------------------------------------------------+----------------------------------------------------------------+ +| 2023-01-01 00:00:00 | 2022-01-01 00:00:00 | ++----------------------------------------------------------------+----------------------------------------------------------------+ +``` + +## 最佳实践 + +还可参阅 [date_floor](./date-floor) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md new file mode 100644 index 0000000000000..9c5abc79ea87d --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md @@ -0,0 +1,42 @@ +--- +{ + "title": "QUARTERS_DIFF", + "language": "zh-CN" +} +--- + +## 描述 + +`QUARTERS_DIFF` 函数用于计算两个日期之间相差的季度数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差季度数。相差季度数等价于相差月份数除以 3（向 0 取整）。 + +## 语法 + +```sql +QUARTERS_DIFF(, ) +``` + +## 参数 + +| 参数 | 说明 | +|---------------|---------------------------------------------------------| +| `` | 结束日期，表示计算差值时的较晚日期。支持 `DATE` 或 `DATETIME` 类型 | +| `` | 开始日期，表示计算差值时的较早日期。支持 `DATE` 或 `DATETIME` 类型 | + +## 返回值 + +返回 `` 减去 `` 所得季度数 +- 当 `` 与 `` 任意为 NULL 时，返回 NULL + +## 举例 + +```sql +select QUARTERS_DIFF('2021-03-25', '2020-10-25'), QUARTERS_DIFF('2020-10-25 10:00:00', '2022-12-25 11:00:00'); +``` + +```text ++------------------------------------------+------------------------------------------------------------+ +| QUARTERS_DIFF('2021-03-25','2020-10-25') | QUARTERS_DIFF('2020-10-25 10:00:00','2022-12-25 11:00:00') | ++------------------------------------------+------------------------------------------------------------+ +| 1 | -8 | ++------------------------------------------+------------------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md new file mode 100644 index 0000000000000..a4223dd41de5c --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md @@ -0,0 +1,131 @@ +--- +{ + "title": "ST_GEOMETRIES", + "language": "zh-CN", + "description": "返回几何集合中的子几何数组。" +} +--- + +## 描述 + +将几何对象拆分为其子几何组成的数组。对于集合类型（MultiPolygon），会将每个子多边形作为数组中的独立元素返回。对于非集合类型（Point、LineString、Polygon、Circle），会返回仅包含该几何对象本身的单元素数组。 + +## 语法 + +```sql +ST_GEOMETRIES( ) +``` + +## 参数 + +| 参数 | 描述 | +| :--- | :--- | +| `` | 输入几何，类型为 GEOMETRY 或 VARCHAR（WKT 格式），且可转换为 GEOMETRY。 | + +## 返回值 + +返回 `ARRAY`，其中每个元素都是一个编码后的几何对象，可与 `ST_AsText` 或 `ST_GeometryType` 等其他空间函数配合使用。 + +`ST_GEOMETRIES` 具有如下边界情况： +- 如果输入参数为 `NULL`，返回 `NULL`。 +- 如果输入参数无法解析为有效几何对象，返回 `NULL`。 +- 对于非集合类型（`POINT`、`LINESTRING`、`POLYGON`、`CIRCLE`），返回包含输入几何对象的单元素数组。 +- 对于 `MULTIPOLYGON`，返回一个数组，其中每个元素都是一个子多边形。 +- 数组元素可以继续传递给其他空间函数进行处理。 + +## 示例 + +**Point 的几何对象（单元素数组）** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]); +``` +```text ++------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]) | ++------------------------------------------------+ +| POINT (1 2) | ++------------------------------------------------+ +``` + +**Polygon 的几何对象（单元素数组）** +```sql +SELECT ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------+ +| ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]) | ++----------------------------------------------------------------------------------------------------+ +| ST_POLYGON | ++----------------------------------------------------------------------------------------------------+ +``` + +**MultiPolygon 的几何对象（多个元素）** +```sql +SELECT SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))); +``` +```text ++----------------------------------------------------------------------------------------------------------------------+ +| SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))))') | ++----------------------------------------------------------------------------------------------------------------------+ +| 2 | ++----------------------------------------------------------------------------------------------------------------------+ +``` + +**访问 MultiPolygon 的单个元素** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((3 2, 3 3, 2 3, 2 2, 3 2)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +**越界索引（返回 NULL）** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3]; +``` +```text ++----------------------------------------------------------------------------------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3] | ++----------------------------------------------------------------------------------------------------------------------------+ +| NULL | ++----------------------------------------------------------------------------------------------------------------------------+ +``` + +**NULL 参数** +```sql +SELECT ST_GEOMETRIES(NULL); +``` +```text ++----------------------+ +| ST_GEOMETRIES(NULL) | ++----------------------+ +| NULL | ++----------------------+ +``` + +**非法参数（返回 NULL）** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++----------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('INVALID')) | ++----------------------------------------------------+ +| NULL | ++----------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md new file mode 100644 index 0000000000000..c81c706c884aa --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md @@ -0,0 +1,107 @@ +--- +{ + "title": "ST_NUMGEOMETRIES", + "language": "zh-CN", + "description": "返回几何集合中的几何数量。" +} +--- + +## 描述 + +返回几何对象中包含的子几何数量。对于非集合类型（Point、LineString、Polygon、Circle），始终返回 1。对于集合类型（MultiPolygon），返回集合中的子几何数量。 + +## 语法 + +```sql +ST_NUMGEOMETRIES( ) +``` + +## 参数 + +| 参数 | 描述 | +| :--- | :--- | +| `` | 输入几何，类型为 GEOMETRY 或 VARCHAR（WKT 格式），且可转换为 GEOMETRY。 | + +## 返回值 + +返回一个 BIGINT 值，表示几何对象中的子几何数量。 + +`ST_NUMGEOMETRIES` 具有如下边界情况： +- 如果输入参数为 `NULL`，返回 `NULL`。 +- 如果输入参数无法解析为有效几何对象，返回 `NULL`。 +- 对于非集合类型（`POINT`、`LINESTRING`、`POLYGON`、`CIRCLE`），始终返回 `1`。 +- 对于 `MULTIPOLYGON`，返回集合中的多边形数量。 + +## 示例 + +**Point 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_Point(1, 2)); +``` +```text ++----------------------------------+ +| ST_NUMGEOMETRIES(ST_Point(1, 2)) | ++----------------------------------+ +| 1 | ++----------------------------------+ +``` + +**Polygon 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++------------------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------------------+ +``` + +**包含两个多边形的 MultiPolygon 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++------------------------------------------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++------------------------------------------------------------------------------------------------------------------+ +| 2 | ++------------------------------------------------------------------------------------------------------------------+ +``` + +**Circle 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)); +``` +```text ++----------------------------------------+ +| ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)) | ++----------------------------------------+ +| 1 | ++----------------------------------------+ +``` + +**NULL 参数** +```sql +SELECT ST_NUMGEOMETRIES(NULL); +``` +```text ++------------------------+ +| ST_NUMGEOMETRIES(NULL) | ++------------------------+ +| NULL | ++------------------------+ +``` + +**非法参数（返回 NULL）** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++--------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')) | ++--------------------------------------------------+ +| NULL | ++--------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md new file mode 100644 index 0000000000000..cb2c635121512 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md @@ -0,0 +1,134 @@ +--- +{ + "title": "ST_NUMPOINTS", + "language": "zh-CN", + "description": "返回几何对象中的点总数。" +} +--- + +## 描述 + +返回几何对象中的顶点（点）总数。不同几何类型的计数规则如下：Point 返回 1，LineString 返回顶点数，Polygon 返回所有环上的顶点总数（包含闭合点），MultiPolygon 返回所有子多边形点数之和。 + +## 语法 + +```sql +ST_NUMPOINTS( ) +``` + +## 参数 + +| 参数 | 描述 | +| :--- | :--- | +| `` | 输入几何，类型为 GEOMETRY 或 VARCHAR（WKT 格式），且可转换为 GEOMETRY。 | + +## 返回值 + +返回一个 BIGINT 值，表示几何对象中的点总数。 + +`ST_NUMPOINTS` 具有如下边界情况： +- 如果输入参数为 `NULL`，返回 `NULL`。 +- 如果输入参数无法解析为有效几何对象，返回 `NULL`。 +- 对于 `POINT`，返回 `1`。 +- 对于 `LINESTRING`，返回线上的顶点数。 +- 对于 `POLYGON`，返回所有环（外环 + 内环）的顶点总数。每个环都包含闭合点。 +- 对于 `MULTIPOLYGON`，返回所有子多边形点数之和。 +- 对于 `CIRCLE`，返回 `-1`（圆没有离散顶点）。 + +## 示例 + +**Point 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_Point(1, 2)); +``` +```text ++------------------------------+ +| ST_NUMPOINTS(ST_Point(1, 2)) | ++------------------------------+ +| 1 | ++------------------------------+ +``` + +**LineString 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')); +``` +```text ++-------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')) | ++-------------------------------------------------------------------+ +| 3 | ++-------------------------------------------------------------------+ +``` + +**方形 Polygon 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++----------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++----------------------------------------------------------------------------+ +| 5 | ++----------------------------------------------------------------------------+ +``` + +**带洞 Polygon 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')); +``` +```text ++-----------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')) | ++-----------------------------------------------------------------------------------------------------------+ +| 10 | ++-----------------------------------------------------------------------------------------------------------+ +``` + +**MultiPolygon 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++--------------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++--------------------------------------------------------------------------------------------------------------+ +| 10 | ++--------------------------------------------------------------------------------------------------------------+ +``` + +**Circle 中的点数（返回 -1）** +```sql +SELECT ST_NUMPOINTS(ST_Circle(0, 0, 100)); +``` +```text ++--------------------------------------+ +| ST_NUMPOINTS(ST_Circle(0, 0, 100)) | ++--------------------------------------+ +| -1 | ++--------------------------------------+ +``` + +**NULL 参数** +```sql +SELECT ST_NUMPOINTS(NULL); +``` +```text ++---------------------+ +| ST_NUMPOINTS(NULL) | ++---------------------+ +| NULL | ++---------------------+ +``` + +**非法参数（返回 NULL）** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('INVALID')); +``` +```text ++------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('INVALID')) | ++------------------------------------------------+ +| NULL | ++------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md index 4dbdba2bb67b0..64978203b9f8c 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md @@ -36,11 +36,11 @@ select fmod(10.1, 3.2); ``` ```text -+-----------------+ -| fmod(10.1, 3.2) | -+-----------------+ -| 0.50000024 | -+-----------------+ ++--------------------+ +| fmod(10.1, 3.2) | ++--------------------+ +| 0.4999999999999991 | ++--------------------+ ``` ```sql @@ -53,4 +53,4 @@ select fmod(10.1, 0); +---------------+ | NULL | +---------------+ -``` \ No newline at end of file +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md new file mode 100644 index 0000000000000..0b68d89f8a703 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md @@ -0,0 +1,75 @@ +--- +{ + "title": "QUARTER_CEIL", + "language": "zh-CN" +} +--- + +## 描述 + +将日期时间值向上取整到最近的指定季度周期的下个周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 + +:::tip +QUARTER_CEIL 支持从 3.0.8 和 3.1.0 版本开始。 +::: + +## 语法 + +```sql +QUARTER_CEIL() +QUARTER_CEIL(, ) +QUARTER_CEIL(, ) +QUARTER_CEIL(, , ) +``` + +## 参数 + +| 参数 | 说明 | +| ---- | ---- | +| `` | 需要向上取整的日期时间值，类型为 DATE 或 DATETIME | +| `` | 季度周期值，类型为 INT，表示每个周期包含的季度数 | +| `` | 周期的起始时间点，类型为 DATE 或 DATETIME，默认值为 0001-01-01 00:00:00 | + +注意： +- 不指定 period 时，等价于以 1 个季度为周期 +- 当 period 不为正整数时，函数结果将为 NULL +- 结果总是向过去时间取整 +- 返回值的时间部分总是 00:00:00 + +## 返回值 + +当 `` 为 DATE 类型时，返回类型为 DATE。 +当 `` 为 DATETIME 类型时，返回类型为 DATETIME。 +表示向上取整后的日期时间值。结果的时间部分将被设置为 00:00:00。 + +## 举例 + +从 '0001-01-01 00:00:00' 开始，每 5 / 4 个季度为一个周期，返回距离输入日期最近的下一个周期起点。 +```sql +SELECT QUARTER_CEIL("2023-07-13 22:28:18", 5), QUARTER_CEIL("2023-07-13 22:28:18", 4); +``` + +```text ++----------------------------------------+----------------------------------------+ +| QUARTER_CEIL("2023-07-13 22:28:18", 5) | QUARTER_CEIL("2023-07-13 22:28:18", 4) | ++----------------------------------------+----------------------------------------+ +| 2024-10-01 00:00:00.000000 | 2024-01-01 00:00:00.000000 | ++----------------------------------------+----------------------------------------+ +``` + +以 '2022-01-01 00:00:00' 为周期起点，分别以 2 / 4 个季度为一个周期，返回距离输入日期最近的下一个周期起点。 +```sql +SELECT QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++---------------------------------------------------------------+---------------------------------------------------------------+ +| QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2024-01-01 00:00:00 | ++---------------------------------------------------------------+---------------------------------------------------------------+ +``` + +## 最佳实践 + +还可参阅 [date_ceil](./date-ceil) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md new file mode 100644 index 0000000000000..064268255ddd7 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -0,0 +1,74 @@ +--- +{ + "title": "QUARTER_FLOOR", + "language": "zh-CN" +} +--- + +## 描述 + +将日期时间值向下取整到最近的指定季度周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 + +:::tip +QUARTER_FLOOR 支持从 3.0.8 和 3.1.0 版本开始。 +::: + +## 语法 + +```sql +QUARTER_FLOOR() +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, , ) +``` + +## 参数 + +| 参数 | 说明 | +| ---- | ---- | +| `` | 需要向下取整的日期时间值，类型为 DATE 或 DATETIME | +| `` | 季度周期值，类型为 INT，表示每个周期包含的季度数 | +| `` | 周期的起始时间点，类型为 DATE 或 DATETIME，默认值为 0001-01-01 00:00:00 | + +注意： +- 不指定 period 时，等价于以 1 个季度为周期 +- 当 period 不为正整数时，函数结果将为 NULL +- 结果总是向过去时间取整 +- 返回值的时间部分总是 00:00:00 + +## 返回值 + +当 `` 为 DATE 类型时，返回类型为 DATE。 +当 `` 为 DATETIME 类型时，返回类型为 DATETIME。 +结果的时间部分将被设置为 00:00:00。 + +## 举例 + +从 '0001-01-01 00:00:00' 开始，每 5 / 4 个季度为一个周期，返回距离输入日期最近的周期起点。 +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 5), QUARTER_FLOOR("2023-07-13 22:28:18", 4); +``` + +```text ++-----------------------------------------+-----------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 5) | QUARTER_FLOOR("2023-07-13 22:28:18", 4) | ++-----------------------------------------+-----------------------------------------+ +| 2021-01-01 00:00:00 | 2022-01-01 00:00:00 | ++-----------------------------------------+-----------------------------------------+ +``` + +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++----------------------------------------------------------------+----------------------------------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++----------------------------------------------------------------+----------------------------------------------------------------+ +| 2023-07-01 00:00:00.000000 | 2023-01-01 00:00:00.000000 | ++----------------------------------------------------------------+----------------------------------------------------------------+ +``` + +## 最佳实践 + +还可参阅 [date_floor](./date-floor) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md new file mode 100644 index 0000000000000..508f0980fb6af --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md @@ -0,0 +1,46 @@ +--- +{ + "title": "QUARTERS_DIFF", + "language": "zh-CN" +} +--- + +## 描述 + +`QUARTERS_DIFF` 函数用于计算两个日期之间相差的季度数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差季度数。相差季度数等价于相差月份数除以 3（向 0 取整）。 + +:::tip +QUARTERS_DIFF 支持从 3.0.8 和 3.1.0 版本开始。 +::: + +## 语法 + +```sql +QUARTERS_DIFF(, ) +``` + +## 参数 + +| 参数 | 说明 | +|---------------|---------------------------------------------------------| +| `` | 结束日期，表示计算差值时的较晚日期。支持 `DATE` 或 `DATETIME` 类型 | +| `` | 开始日期，表示计算差值时的较早日期。支持 `DATE` 或 `DATETIME` 类型 | + +## 返回值 + +返回 `` 减去 `` 所得季度数 +- 当 `` 与 `` 任意为 NULL 时，返回 NULL。 + +## 举例 + +```sql +select QUARTERS_DIFF('2021-03-25', '2020-10-25'), QUARTERS_DIFF('2020-10-25 10:00:00', '2022-12-25 11:00:00'); +``` + +```text ++------------------------------------------+------------------------------------------------------------+ +| QUARTERS_DIFF('2021-03-25','2020-10-25') | QUARTERS_DIFF('2020-10-25 10:00:00','2022-12-25 11:00:00') | ++------------------------------------------+------------------------------------------------------------+ +| 1 | -8 | ++------------------------------------------+------------------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md index b200c28d7ceaa..41976541c7201 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md @@ -35,8 +35,8 @@ SELECT COSINE_DISTANCE([1, 2], [2, 3]),COSINE_DISTANCE([3, 6], [4, 7]); ```text +---------------------------------+---------------------------------+ -| cosine_distance([1, 2], [2, 3]) | cosine_distance([3, 6], [4, 7]) | +| COSINE_DISTANCE([1, 2], [2, 3]) | COSINE_DISTANCE([3, 6], [4, 7]) | +---------------------------------+---------------------------------+ -| 0.007722123286332261 | 0.0015396467945875125 | +| 0.0077221394 | 0.0015397072 | +---------------------------------+---------------------------------+ ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md index 6a17a1b6f39fd..bf878782e4650 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md @@ -37,6 +37,6 @@ SELECT L2_DISTANCE([4, 5], [6, 8]),L2_DISTANCE([3, 6], [4, 5]); +-----------------------------+-----------------------------+ | l2_distance([4, 5], [6, 8]) | l2_distance([3, 6], [4, 5]) | +-----------------------------+-----------------------------+ -| 3.605551275463989 | 1.4142135623730951 | +| 3.605551 | 1.414214 | +-----------------------------+-----------------------------+ ``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md new file mode 100644 index 0000000000000..7ca292f3e235b --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md @@ -0,0 +1,106 @@ +--- +{ + "title": "COSINE_SIMILARITY", + "language": "zh-CN", + "description": "计算两个向量之间的余弦相似度。" +} +--- + +## 描述 + +计算两个向量之间的余弦相似度。 +函数按照向量的点积与模长计算相似度，结果范围为 `[-1, 1]`。 + +:::note 版本说明 +自 4.1.2 起支持。 +::: + +## 语法 + +```sql +COSINE_SIMILARITY(, ) +``` + +## 参数 + +| 参数 | 说明 | +| -- | -- | +| `` | 第一个向量。类型必须为 `ARRAY`。 | +| `` | 第二个向量。类型必须为 `ARRAY`，且元素个数需与 `` 一致。 | + +## 返回值 + +返回两个向量的余弦相似度，类型为 FLOAT。 +如果输入数组为 `NULL`，或者数组中包含 `NULL` 元素，则报错。 +如果两个数组的元素个数不一致，则报错。 +如果数组为空，或者任一向量为零向量，则返回 `0.0`。 + +## 举例 + +```sql +-- 两个向量完全相同，相似度为 1 +SELECT COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]) | ++-----------------------------------------+ +| 1 | ++-----------------------------------------+ +``` + +`[1, 2, 3]` 与 `[1, 2, 3]` 的方向完全一致，因此相似度为 `1`。 + +```sql +-- 两个向量正交，相似度为 0 +SELECT COSINE_SIMILARITY([1, 0], [0, 1]); +``` + +```text ++-----------------------------------+ +| COSINE_SIMILARITY([1, 0], [0, 1]) | ++-----------------------------------+ +| 0 | ++-----------------------------------+ +``` + +两个向量互相垂直，点积为 `0`，因此相似度为 `0`。 + +```sql +-- 任一向量为零向量时，返回 0 +SELECT COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]) | ++-----------------------------------------+ +| 0 | ++-----------------------------------------+ +``` + +零向量没有有效方向，因此结果为 `0`。 + +```sql +-- 空数组返回 0 +SELECT COSINE_SIMILARITY([], []); +``` + +```text ++---------------------------+ +| COSINE_SIMILARITY([], []) | ++---------------------------+ +| 0 | ++---------------------------+ +``` + +```sql +-- 输入数组中包含 NULL，会报错 +SELECT COSINE_SIMILARITY([1, NULL, 3], [1, 2, 3]); +``` + +```text +ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]First argument for function cosine_similarity cannot have null +``` + diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md new file mode 100644 index 0000000000000..53be877fdfa5e --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md @@ -0,0 +1,71 @@ +--- +{ + "title": "QUARTER_CEIL", + "language": "zh-CN" +} +--- + +## 描述 + +将日期时间值向上取整到最近的指定季度周期的下个周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 + +## 语法 + +```sql +QUARTER_CEIL() +QUARTER_CEIL(, ) +QUARTER_CEIL(, ) +QUARTER_CEIL(, , ) +``` + +## 参数 + +| 参数 | 说明 | +| ---- | ---- | +| `` | 需要向上取整的日期时间值，类型为 DATE 或 DATETIME | +| `` | 季度周期值，类型为 INT，表示每个周期包含的季度数 | +| `` | 周期的起始时间点，类型为 DATE 或 DATETIME，默认值为 0001-01-01 00:00:00 | + +注意： +- 不指定 period 时，等价于以 1 个季度为周期 +- 当 period 不为正整数时，函数结果将为 NULL +- 结果总是向未来时间取整 +- 返回值的时间部分总是 00:00:00 + +## 返回值 + +当 `` 为 DATE 类型时，返回类型为 DATE。 +当 `` 为 DATETIME 类型时，返回类型为 DATETIME。 +表示向上取整后的日期时间值。结果的时间部分将被设置为 00:00:00。 + +## 举例 + +从 '0001-01-01 00:00:00' 开始，每 5 / 4 个季度为一个周期，返回距离输入日期最近的下一个周期起点。 +```sql +SELECT QUARTER_CEIL("2023-07-13 22:28:18", 5), QUARTER_CEIL("2023-07-13 22:28:18", 4); +``` + +```text ++----------------------------------------+----------------------------------------+ +| QUARTER_CEIL("2023-07-13 22:28:18", 5) | QUARTER_CEIL("2023-07-13 22:28:18", 4) | ++----------------------------------------+----------------------------------------+ +| 2024-10-01 00:00:00.000000 | 2024-01-01 00:00:00.000000 | ++----------------------------------------+----------------------------------------+ +``` + +以 '2022-01-01 00:00:00' 为周期起点，分别以 2 / 4 个季度为一个周期，返回距离输入日期最近的下一个周期起点。 +```sql +SELECT QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++---------------------------------------------------------------+---------------------------------------------------------------+ +| QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2024-01-01 00:00:00 | ++---------------------------------------------------------------+---------------------------------------------------------------+ +``` + +## 最佳实践 + +还可参阅 [date_ceil](./date-ceil) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md new file mode 100644 index 0000000000000..3d84b6e531d37 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -0,0 +1,70 @@ +--- +{ + "title": "QUARTER_FLOOR", + "language": "zh-CN" +} +--- + +## 描述 + +将日期时间值向下取整到最近的指定季度周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 + +## 语法 + +```sql +QUARTER_FLOOR() +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, , ) +``` + +## 参数 + +| 参数 | 说明 | +| ---- | ---- | +| `` | 需要向下取整的日期时间值，类型为 DATE 或 DATETIME | +| `` | 季度周期值，类型为 INT，表示每个周期包含的季度数 | +| `` | 周期的起始时间点，类型为 DATE 或 DATETIME，默认值为 0001-01-01 00:00:00 | + +注意： +- 不指定 period 时，等价于以 1 个季度为周期 +- 当 period 不为正整数时，函数结果将为 NULL +- 结果总是向过去时间取整 +- 返回值的时间部分总是 00:00:00 + +## 返回值 + +当 `` 为 DATE 类型时，返回类型为 DATE。 +当 `` 为 DATETIME 类型时，返回类型为 DATETIME。 +结果的时间部分将被设置为 00:00:00。 + +## 举例 + +从 '0001-01-01 00:00:00' 开始，每 5 / 4 个季度为一个周期，返回距离输入日期最近的周期起点。 +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 5), QUARTER_FLOOR("2023-07-13 22:28:18", 4); +``` + +```text ++-----------------------------------------+-----------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 5) | QUARTER_FLOOR("2023-07-13 22:28:18", 4) | ++-----------------------------------------+-----------------------------------------+ +| 2023-07-01 00:00:00.000000 | 2023-01-01 00:00:00.000000 | ++-----------------------------------------+-----------------------------------------+ +``` + +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++----------------------------------------------------------------+----------------------------------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++----------------------------------------------------------------+----------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2023-01-01 00:00:00 | ++----------------------------------------------------------------+----------------------------------------------------------------+ +``` + +## 最佳实践 + +还可参阅 [date_floor](./date-floor) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md new file mode 100644 index 0000000000000..a23e650444dc7 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md @@ -0,0 +1,42 @@ +--- +{ + "title": "QUARTERS_DIFF", + "language": "zh-CN" +} +--- + +## 描述 + +`QUARTERS_DIFF` 函数用于计算两个日期之间相差的季度数。该函数接受两个日期参数，返回第一个日期减去第二个日期后的相差季度数。相差季度数等价于相差月份数除以 3（向 0 取整）。 + +## 语法 + +```sql +QUARTERS_DIFF(, ) +``` + +## 参数 + +| 参数 | 说明 | +|---------------|---------------------------------------------------------| +| `` | 结束日期，表示计算差值时的较晚日期。支持 `DATE` 或 `DATETIME` 类型 | +| `` | 开始日期，表示计算差值时的较早日期。支持 `DATE` 或 `DATETIME` 类型 | + +## 返回值 + +返回 `` 减去 `` 所得季度数 +- 当 `` 与 `` 任意为 NULL 时，返回 NULL。 + +## 举例 + +```sql +select QUARTERS_DIFF('2021-03-25', '2020-10-25'), QUARTERS_DIFF('2020-10-25 10:00:00', '2022-12-25 11:00:00'); +``` + +```text ++------------------------------------------+------------------------------------------------------------+ +| QUARTERS_DIFF('2021-03-25','2020-10-25') | QUARTERS_DIFF('2020-10-25 10:00:00','2022-12-25 11:00:00') | ++------------------------------------------+------------------------------------------------------------+ +| 1 | -8 | ++------------------------------------------+------------------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md new file mode 100644 index 0000000000000..d00e7ca5ad0dd --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md @@ -0,0 +1,135 @@ +--- +{ + "title": "ST_GEOMETRIES", + "language": "zh-CN", + "description": "返回几何集合中的子几何数组。" +} +--- + +## 描述 + +将几何对象拆分为其子几何组成的数组。对于集合类型（MultiPolygon），会将每个子多边形作为数组中的独立元素返回。对于非集合类型（Point、LineString、Polygon、Circle），会返回仅包含该几何对象本身的单元素数组。 + +:::note +Since 4.1.2 +::: + +## 语法 + +```sql +ST_GEOMETRIES( ) +``` + +## 参数 + +| 参数 | 描述 | +| :--- | :--- | +| `` | 输入几何，类型为 GEOMETRY 或 VARCHAR（WKT 格式），且可转换为 GEOMETRY。 | + +## 返回值 + +返回 `ARRAY`，其中每个元素都是一个编码后的几何对象，可与 `ST_AsText` 或 `ST_GeometryType` 等其他空间函数配合使用。 + +`ST_GEOMETRIES` 具有如下边界情况： +- 如果输入参数为 `NULL`，返回 `NULL`。 +- 如果输入参数无法解析为有效几何对象，返回 `NULL`。 +- 对于非集合类型（`POINT`、`LINESTRING`、`POLYGON`、`CIRCLE`），返回包含输入几何对象的单元素数组。 +- 对于 `MULTIPOLYGON`，返回一个数组，其中每个元素都是一个子多边形。 +- 数组元素可以继续传递给其他空间函数进行处理。 + +## 示例 + +**Point 的几何对象（单元素数组）** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]); +``` +```text ++------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]) | ++------------------------------------------------+ +| POINT (1 2) | ++------------------------------------------------+ +``` + +**Polygon 的几何对象（单元素数组）** +```sql +SELECT ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------+ +| ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]) | ++----------------------------------------------------------------------------------------------------+ +| ST_POLYGON | ++----------------------------------------------------------------------------------------------------+ +``` + +**MultiPolygon 的几何对象（多个元素）** +```sql +SELECT SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))); +``` +```text ++----------------------------------------------------------------------------------------------------------------------+ +| SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))))') | ++----------------------------------------------------------------------------------------------------------------------+ +| 2 | ++----------------------------------------------------------------------------------------------------------------------+ +``` + +**访问 MultiPolygon 的单个元素** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((3 2, 3 3, 2 3, 2 2, 3 2)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +**越界索引（返回 NULL）** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3]; +``` +```text ++----------------------------------------------------------------------------------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3] | ++----------------------------------------------------------------------------------------------------------------------------+ +| NULL | ++----------------------------------------------------------------------------------------------------------------------------+ +``` + +**NULL 参数** +```sql +SELECT ST_GEOMETRIES(NULL); +``` +```text ++----------------------+ +| ST_GEOMETRIES(NULL) | ++----------------------+ +| NULL | ++----------------------+ +``` + +**非法参数（返回 NULL）** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++----------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('INVALID')) | ++----------------------------------------------------+ +| NULL | ++----------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md new file mode 100644 index 0000000000000..0a7b01891eb61 --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md @@ -0,0 +1,111 @@ +--- +{ + "title": "ST_NUMGEOMETRIES", + "language": "zh-CN", + "description": "返回几何集合中的几何数量。" +} +--- + +## 描述 + +返回几何对象中包含的子几何数量。对于非集合类型（Point、LineString、Polygon、Circle），始终返回 1。对于集合类型（MultiPolygon），返回集合中的子几何数量。 + +:::note +Since 4.1.2 +::: + +## 语法 + +```sql +ST_NUMGEOMETRIES( ) +``` + +## 参数 + +| 参数 | 描述 | +| :--- | :--- | +| `` | 输入几何，类型为 GEOMETRY 或 VARCHAR（WKT 格式），且可转换为 GEOMETRY。 | + +## 返回值 + +返回一个 BIGINT 值，表示几何对象中的子几何数量。 + +`ST_NUMGEOMETRIES` 具有如下边界情况： +- 如果输入参数为 `NULL`，返回 `NULL`。 +- 如果输入参数无法解析为有效几何对象，返回 `NULL`。 +- 对于非集合类型（`POINT`、`LINESTRING`、`POLYGON`、`CIRCLE`），始终返回 `1`。 +- 对于 `MULTIPOLYGON`，返回集合中的多边形数量。 + +## 示例 + +**Point 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_Point(1, 2)); +``` +```text ++----------------------------------+ +| ST_NUMGEOMETRIES(ST_Point(1, 2)) | ++----------------------------------+ +| 1 | ++----------------------------------+ +``` + +**Polygon 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++------------------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------------------+ +``` + +**包含两个多边形的 MultiPolygon 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++------------------------------------------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++------------------------------------------------------------------------------------------------------------------+ +| 2 | ++------------------------------------------------------------------------------------------------------------------+ +``` + +**Circle 中的几何数量** +```sql +SELECT ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)); +``` +```text ++----------------------------------------+ +| ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)) | ++----------------------------------------+ +| 1 | ++----------------------------------------+ +``` + +**NULL 参数** +```sql +SELECT ST_NUMGEOMETRIES(NULL); +``` +```text ++------------------------+ +| ST_NUMGEOMETRIES(NULL) | ++------------------------+ +| NULL | ++------------------------+ +``` + +**非法参数（返回 NULL）** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++--------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')) | ++--------------------------------------------------+ +| NULL | ++--------------------------------------------------+ +``` diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md new file mode 100644 index 0000000000000..bc4585b3abdbc --- /dev/null +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md @@ -0,0 +1,138 @@ +--- +{ + "title": "ST_NUMPOINTS", + "language": "zh-CN", + "description": "返回几何对象中的点总数。" +} +--- + +## 描述 + +返回几何对象中的顶点（点）总数。不同几何类型的计数规则如下：Point 返回 1，LineString 返回顶点数，Polygon 返回所有环上的顶点总数（包含闭合点），MultiPolygon 返回所有子多边形点数之和。 + +:::note +Since 4.1.2 +::: + +## 语法 + +```sql +ST_NUMPOINTS( ) +``` + +## 参数 + +| 参数 | 描述 | +| :--- | :--- | +| `` | 输入几何，类型为 GEOMETRY 或 VARCHAR（WKT 格式），且可转换为 GEOMETRY。 | + +## 返回值 + +返回一个 BIGINT 值，表示几何对象中的点总数。 + +`ST_NUMPOINTS` 具有如下边界情况： +- 如果输入参数为 `NULL`，返回 `NULL`。 +- 如果输入参数无法解析为有效几何对象，返回 `NULL`。 +- 对于 `POINT`，返回 `1`。 +- 对于 `LINESTRING`，返回线上的顶点数。 +- 对于 `POLYGON`，返回所有环（外环 + 内环）的顶点总数。每个环都包含闭合点。 +- 对于 `MULTIPOLYGON`，返回所有子多边形点数之和。 +- 对于 `CIRCLE`，返回 `-1`（圆没有离散顶点）。 + +## 示例 + +**Point 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_Point(1, 2)); +``` +```text ++------------------------------+ +| ST_NUMPOINTS(ST_Point(1, 2)) | ++------------------------------+ +| 1 | ++------------------------------+ +``` + +**LineString 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')); +``` +```text ++-------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')) | ++-------------------------------------------------------------------+ +| 3 | ++-------------------------------------------------------------------+ +``` + +**方形 Polygon 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++----------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++----------------------------------------------------------------------------+ +| 5 | ++----------------------------------------------------------------------------+ +``` + +**带洞 Polygon 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')); +``` +```text ++-----------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')) | ++-----------------------------------------------------------------------------------------------------------+ +| 10 | ++-----------------------------------------------------------------------------------------------------------+ +``` + +**MultiPolygon 中的点数** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++--------------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++--------------------------------------------------------------------------------------------------------------+ +| 10 | ++--------------------------------------------------------------------------------------------------------------+ +``` + +**Circle 中的点数（返回 -1）** +```sql +SELECT ST_NUMPOINTS(ST_Circle(0, 0, 100)); +``` +```text ++--------------------------------------+ +| ST_NUMPOINTS(ST_Circle(0, 0, 100)) | ++--------------------------------------+ +| -1 | ++--------------------------------------+ +``` + +**NULL 参数** +```sql +SELECT ST_NUMPOINTS(NULL); +``` +```text ++---------------------+ +| ST_NUMPOINTS(NULL) | ++---------------------+ +| NULL | ++---------------------+ +``` + +**非法参数（返回 NULL）** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('INVALID')); +``` +```text ++------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('INVALID')) | ++------------------------------------------------+ +| NULL | ++------------------------------------------------+ +``` diff --git a/sidebars.ts b/sidebars.ts index 3edea9b659319..860f8d6907553 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1360,6 +1360,7 @@ const sidebars: SidebarsConfig = { label: 'Vector Distance Functions', items: [ 'sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance', + 'sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity', 'sql-manual/sql-functions/ai-functions/distance-functions/inner-product', 'sql-manual/sql-functions/ai-functions/distance-functions/l1-distance', 'sql-manual/sql-functions/ai-functions/distance-functions/l2-distance', diff --git a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md index b20937aca6c1e..fcf5ad4e411f1 100644 --- a/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md +++ b/versioned_docs/version-2.1/sql-manual/sql-functions/scalar-functions/numeric-functions/fmod.md @@ -36,11 +36,11 @@ select fmod(10.1, 3.2); ``` ```text -+-----------------+ -| fmod(10.1, 3.2) | -+-----------------+ -| 0.50000024 | -+-----------------+ ++--------------------+ +| fmod(10.1, 3.2) | ++--------------------+ +| 0.4999999999999991 | ++--------------------+ ``` ```sql @@ -53,4 +53,4 @@ select fmod(10.1, 0); +---------------+ | NULL | +---------------+ -``` \ No newline at end of file +``` diff --git a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md index 2752b45cffa24..9bff296f3e5b7 100644 --- a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md +++ b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil.md @@ -111,4 +111,4 @@ select date_ceil("2023-07-13 22:28:18",interval 5 year); +------------------------------------------------------------+ | 2026-01-01 00:00:00 | +------------------------------------------------------------+ -``` \ No newline at end of file +``` diff --git a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md new file mode 100644 index 0000000000000..7eedacf3fd2ec --- /dev/null +++ b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md @@ -0,0 +1,75 @@ +--- +{ + "title": "QUARTER_CEIL", + "language": "en" +} +--- + +## Description + +Rounds a datetime value up to the nearest specified quarter period boundary. If an origin time is specified, the period is calculated based on that time. + +:::tip +QUARTER_CEIL is supported since version 3.0.8 and 3.1.0. +::: + +## Syntax + +```sql +QUARTER_CEIL() +QUARTER_CEIL(, ) +QUARTER_CEIL(, ) +QUARTER_CEIL(, , ) +``` + +## Parameters + +| Parameter | Description | +| ---- | ---- | +| `` | The datetime value to round up, type is DATE or DATETIME | +| `` | Quarter period value, type is INT, representing the number of quarters contained in each period | +| `` | The starting point of the period, type is DATE or DATETIME, default value is 0001-01-01 00:00:00 | + +Notes: +- When period is not specified, it is equivalent to using 1 quarter as the period +- When period is not a positive integer, the function result will be NULL +- The result always rounds to the future time +- The time part of the return value is always 00:00:00 + +## Return Value + +When `` is of DATE type, the return type is DATE. +When `` is of DATETIME type, the return type is DATETIME. +Represents the rounded up datetime value. The time part of the result will be set to 00:00:00. + +## Examples + +Starting from '0001-01-01 00:00:00', with periods of 5 / 4 quarters each, return the next period start point closest to the input date. +```sql +SELECT QUARTER_CEIL("2023-07-13 22:28:18", 5), QUARTER_CEIL("2023-07-13 22:28:18", 4); +``` + +```text ++----------------------------------------+----------------------------------------+ +| QUARTER_CEIL("2023-07-13 22:28:18", 5) | QUARTER_CEIL("2023-07-13 22:28:18", 4) | ++----------------------------------------+----------------------------------------+ +| 2024-10-01 00:00:00.000000 | 2024-01-01 00:00:00.000000 | ++----------------------------------------+----------------------------------------+ +``` + +Using '2022-01-01 00:00:00' as the period start point, with periods of 2 / 4 quarters each, return the next period start point closest to the input date. +```sql +SELECT QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++---------------------------------------------------------------+---------------------------------------------------------------+ +| QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2024-01-01 00:00:00 | ++---------------------------------------------------------------+---------------------------------------------------------------+ +``` + +## Best Practices + +See also [date_ceil](./date-ceil) diff --git a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md new file mode 100644 index 0000000000000..def802622840e --- /dev/null +++ b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -0,0 +1,75 @@ +--- +{ + "title": "QUARTER_FLOOR", + "language": "en" +} +--- + +## Description + +Rounds a datetime value down to the nearest specified quarter period boundary. If an origin time is specified, the period is calculated based on that time. + +:::tip +QUARTER_FLOOR is supported since version 3.0.8 and 3.1.0. +::: + +## Syntax + +```sql +QUARTER_FLOOR() +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, , ) +``` + +## Parameters + +| Parameter | Description | +| ---- | ---- | +| `` | The datetime value to round down, type is DATE or DATETIME | +| `` | Quarter period value, type is INT, representing the number of quarters contained in each period | +| `` | The starting point of the period, type is DATE or DATETIME, default value is 0001-01-01 00:00:00 | + +Notes: +- When period is not specified, it is equivalent to using 1 quarter as the period +- When period is not a positive integer, the function result will be NULL +- The result always rounds to the past time +- The time part of the return value is always 00:00:00 + +## Return Value + +When `` is of DATE type, the return type is DATE. +When `` is of DATETIME type, the return type is DATETIME. +The time part of the result will be set to 00:00:00. + +## Examples + +Starting from '0001-01-01 00:00:00', with periods of 5 / 4 quarters each, return the period start point closest to the input date. +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 5), QUARTER_FLOOR("2023-07-13 22:28:18", 4); +``` + +```text ++-----------------------------------------+-----------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 5) | QUARTER_FLOOR("2023-07-13 22:28:18", 4) | ++-----------------------------------------+-----------------------------------------+ +| 2021-01-01 00:00:00 | 2022-01-01 00:00:00 | ++-----------------------------------------+-----------------------------------------+ +``` + +Using '2022-01-01 00:00:00' as the period start point, with periods of 2 / 4 quarters each, return the period start point closest to the input date. +```sql +SELECT QUARTER_FLOOR("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++----------------------------------------------------------------+----------------------------------------------------------------+ +| QUARTER_FLOOR("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++----------------------------------------------------------------+----------------------------------------------------------------+ +| 2023-01-01 00:00:00 | 2022-01-01 00:00:00 | ++----------------------------------------------------------------+----------------------------------------------------------------+ +``` + +## Best Practices + +See also [date_floor](./date-floor) diff --git a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md new file mode 100644 index 0000000000000..5bdffd0f445a0 --- /dev/null +++ b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md @@ -0,0 +1,46 @@ +--- +{ + "title": "QUARTERS_DIFF", + "language": "en" +} +--- + +## Description + +The `QUARTERS_DIFF` function calculates the number of quarters between two dates. This function accepts two date parameters and returns the difference in quarters after subtracting the second date from the first date. The difference in quarters is equivalent to the difference in months divided by 3 (rounded towards zero). + +:::tip +QUARTERS_DIFF is supported since version 3.0.8 and 3.1.0. +::: + +## Syntax + +```sql +QUARTERS_DIFF(, ) +``` + +## Parameters + +| Parameter | Description | +|---------------|--------------------------------------------------------------------------------------| +| `` | End date, represents the later date when calculating the difference. Supports `DATE` or `DATETIME` types | +| `` | Start date, represents the earlier date when calculating the difference. Supports `DATE` or `DATETIME` types | + +## Return Value + +Returns the number of quarters obtained by subtracting `` from `` +- When either `` or `` is NULL, returns NULL. + +## Examples + +```sql +select QUARTERS_DIFF('2021-03-25', '2020-10-25'), QUARTERS_DIFF('2020-10-25 10:00:00', '2022-12-25 11:00:00'); +``` + +```text ++------------------------------------------+------------------------------------------------------------+ +| QUARTERS_DIFF('2021-03-25','2020-10-25') | QUARTERS_DIFF('2020-10-25 10:00:00','2022-12-25 11:00:00') | ++------------------------------------------+------------------------------------------------------------+ +| 1 | -8 | ++------------------------------------------+------------------------------------------------------------+ +``` diff --git a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md index 97b8e751eb7d9..9f8187bab1336 100644 --- a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md +++ b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/cosine-distance.md @@ -35,8 +35,8 @@ SELECT COSINE_DISTANCE([1, 2], [2, 3]),COSINE_DISTANCE([3, 6], [4, 7]); ```text +---------------------------------+---------------------------------+ -| cosine_distance([1, 2], [2, 3]) | cosine_distance([3, 6], [4, 7]) | +| COSINE_DISTANCE([1, 2], [2, 3]) | COSINE_DISTANCE([3, 6], [4, 7]) | +---------------------------------+---------------------------------+ -| 0.007722123286332261 | 0.0015396467945875125 | +| 0.0077221394 | 0.0015397072 | +---------------------------------+---------------------------------+ ``` diff --git a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md index 82f823bf1bd9d..917f8ef883ec5 100644 --- a/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md +++ b/versioned_docs/version-3.x/sql-manual/sql-functions/scalar-functions/distance-functions/l2-distance.md @@ -37,6 +37,6 @@ SELECT L2_DISTANCE([4, 5], [6, 8]),L2_DISTANCE([3, 6], [4, 5]); +-----------------------------+-----------------------------+ | l2_distance([4, 5], [6, 8]) | l2_distance([3, 6], [4, 5]) | +-----------------------------+-----------------------------+ -| 3.605551275463989 | 1.4142135623730951 | +| 3.605551 | 1.414214 | +-----------------------------+-----------------------------+ ``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md new file mode 100644 index 0000000000000..9ea19c2aeb6f7 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity.md @@ -0,0 +1,106 @@ +--- +{ + "title": "COSINE_SIMILARITY", + "language": "en", + "description": "Calculates the cosine similarity between two vectors." +} +--- + +## Description + +Calculates the cosine similarity between two vectors. +The similarity is computed from the dot product and vector norms, and the result is in `[-1, 1]`. + +:::note Version Note +This function is supported since 4.1.2. +::: + +## Syntax + +```sql +COSINE_SIMILARITY(, ) +``` + +## Parameters + +| Parameter | Description | +|---|--| +| `` | The first vector. The input type must be `ARRAY`. | +| `` | The second vector. The input type must be `ARRAY`, and the number of elements must be the same as ``. | + +## Return Value + +Returns the cosine similarity between two vectors, in FLOAT type. +If the input array is `NULL`, or any element in the array is `NULL`, an error is returned. +If the two arrays have different numbers of elements, an error is returned. +If the array is empty, or either vector is a zero vector, `0.0` is returned. + +## Example + +```sql +-- Two identical vectors have similarity 1 +SELECT COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([1, 2, 3], [1, 2, 3]) | ++-----------------------------------------+ +| 1 | ++-----------------------------------------+ +``` + +`[1, 2, 3]` and `[1, 2, 3]` point in the same direction, so the similarity is `1`. + +```sql +-- Orthogonal vectors have similarity 0 +SELECT COSINE_SIMILARITY([1, 0], [0, 1]); +``` + +```text ++-----------------------------------+ +| COSINE_SIMILARITY([1, 0], [0, 1]) | ++-----------------------------------+ +| 0 | ++-----------------------------------+ +``` + +The vectors are orthogonal, so their dot product is `0` and the similarity is `0`. + +```sql +-- A zero vector returns 0 +SELECT COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]); +``` + +```text ++-----------------------------------------+ +| COSINE_SIMILARITY([0, 0, 0], [1, 2, 3]) | ++-----------------------------------------+ +| 0 | ++-----------------------------------------+ +``` + +A zero vector has no valid direction, so the result is `0`. + +```sql +-- An empty array returns 0 +SELECT COSINE_SIMILARITY([], []); +``` + +```text ++---------------------------+ +| COSINE_SIMILARITY([], []) | ++---------------------------+ +| 0 | ++---------------------------+ +``` + +```sql +-- NULL inside the input array raises an error +SELECT COSINE_SIMILARITY([1, NULL, 3], [1, 2, 3]); +``` + +```text +ERROR 1105 (HY000): errCode = 2, detailMessage = (127.0.0.1)[INVALID_ARGUMENT]First argument for function cosine_similarity cannot have null +``` + diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md new file mode 100644 index 0000000000000..4d09659028f72 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil.md @@ -0,0 +1,71 @@ +--- +{ + "title": "QUARTER_CEIL", + "language": "en" +} +--- + +## Description + +Rounds a datetime value up to the nearest specified quarter period boundary. If an origin time is specified, the period is calculated based on that time. + +## Syntax + +```sql +QUARTER_CEIL() +QUARTER_CEIL(, ) +QUARTER_CEIL(, ) +QUARTER_CEIL(, , ) +``` + +## Parameters + +| Parameter | Description | +| ---- | ---- | +| `` | The datetime value to round up, type is DATE or DATETIME | +| `` | Quarter period value, type is INT, representing the number of quarters contained in each period | +| `` | The starting point of the period, type is DATE or DATETIME, default value is 0001-01-01 00:00:00 | + +Notes: +- When period is not specified, it is equivalent to using 1 quarter as the period +- When period is not a positive integer, the function result will be NULL +- The result always rounds to the future time +- The time part of the return value is always 00:00:00 + +## Return Value + +When `` is of DATE type, the return type is DATE. +When `` is of DATETIME type, the return type is DATETIME. +Represents the rounded up datetime value. The time part of the result will be set to 00:00:00. + +## Examples + +Starting from '0001-01-01 00:00:00', with periods of 5 / 4 quarters each, return the next period start point closest to the input date. +```sql +SELECT QUARTER_CEIL("2023-07-13 22:28:18", 5), QUARTER_CEIL("2023-07-13 22:28:18", 4); +``` + +```text ++----------------------------------------+----------------------------------------+ +| QUARTER_CEIL("2023-07-13 22:28:18", 5) | QUARTER_CEIL("2023-07-13 22:28:18", 4) | ++----------------------------------------+----------------------------------------+ +| 2024-10-01 00:00:00.000000 | 2024-01-01 00:00:00.000000 | ++----------------------------------------+----------------------------------------+ +``` + +Using '2022-01-01 00:00:00' as the period start point, with periods of 2 / 4 quarters each, return the next period start point closest to the input date. +```sql +SELECT QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++---------------------------------------------------------------+---------------------------------------------------------------+ +| QUARTER_CEIL("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_CEIL("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++---------------------------------------------------------------+---------------------------------------------------------------+ +| 2023-07-01 00:00:00 | 2024-01-01 00:00:00 | ++---------------------------------------------------------------+---------------------------------------------------------------+ +``` + +## Best Practices + +See also [date_ceil](./date-ceil) diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md new file mode 100644 index 0000000000000..ec87ef601f42c --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -0,0 +1,71 @@ +--- +{ + "title": "QUARTER_FLOOR", + "language": "en" +} +--- + +## Description + +Rounds a datetime value down to the nearest specified quarter period boundary. If an origin time is specified, the period is calculated based on that time. + +## Syntax + +```sql +QUARTER_FLOOR() +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, ) +QUARTER_FLOOR(, , ) +``` + +## Parameters + +| Parameter | Description | +| ---- | ---- | +| `` | The datetime value to round down, type is DATE or DATETIME | +| `` | Quarter period value, type is INT, representing the number of quarters contained in each period | +| `` | The starting point of the period, type is DATE or DATETIME, default value is 0001-01-01 00:00:00 | + +Notes: +- When period is not specified, it is equivalent to using 1 quarter as the period +- When period is not a positive integer, the function result will be NULL +- The result always rounds to the past time +- The time part of the return value is always 00:00:00 + +## Return Value + +When `` is of DATE type, the return type is DATE. +When `` is of DATETIME type, the return type is DATETIME. +The time part of the result will be set to 00:00:00. + +## Examples + +Starting from '0001-01-01 00:00:00', with periods of 5 / 4 quarters each, return the period start point closest to the input date. +```sql +SELECT QUARTER_FLOOR("2023-07-13 22:28:18", 5), QUARTER_FLOOR("2023-07-13 22:28:18", 4); +``` + +```text ++-----------------------------------------+-----------------------------------------+ +| QUARTER_FLOOR("2023-07-13 22:28:18", 5) | QUARTER_FLOOR("2023-07-13 22:28:18", 4) | ++-----------------------------------------+-----------------------------------------+ +| 2021-01-01 00:00:00 | 2022-01-01 00:00:00 | ++-----------------------------------------+-----------------------------------------+ +``` + +Using '2022-01-01 00:00:00' as the period start point, with periods of 2 / 4 quarters each, return the period start point closest to the input date. +```sql +SELECT QUARTER_FLOOR("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00"), QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00"); +``` + +```text ++----------------------------------------------------------------+----------------------------------------------------------------+ +| QUARTER_FLOOR("2023-03-13 22:28:18", 2, "2022-01-01 00:00:00") | QUARTER_FLOOR("2023-07-13 22:28:18", 4, "2022-01-01 00:00:00") | ++----------------------------------------------------------------+----------------------------------------------------------------+ +| 2023-01-01 00:00:00 | 2022-01-01 00:00:00 | ++----------------------------------------------------------------+----------------------------------------------------------------+ +``` + +## Best Practices + +See also [date_floor](./date-floor) diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md new file mode 100644 index 0000000000000..0254834a3ef20 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff.md @@ -0,0 +1,42 @@ +--- +{ + "title": "QUARTERS_DIFF", + "language": "en" +} +--- + +## Description + +The `QUARTERS_DIFF` function calculates the number of quarters between two dates. This function accepts two date parameters and returns the difference in quarters after subtracting the second date from the first date. The difference in quarters is equivalent to the difference in months divided by 3 (rounded towards zero). + +## Syntax + +```sql +QUARTERS_DIFF(, ) +``` + +## Parameters + +| Parameter | Description | +|---------------|--------------------------------------------------------------------------------------| +| `` | End date, represents the later date when calculating the difference. Supports `DATE` or `DATETIME` types | +| `` | Start date, represents the earlier date when calculating the difference. Supports `DATE` or `DATETIME` types | + +## Return Value + +Returns the number of quarters obtained by subtracting `` from `` +- When either `` or `` is NULL, returns NULL + +## Examples + +```sql +select QUARTERS_DIFF('2021-03-25', '2020-10-25'), QUARTERS_DIFF('2020-10-25 10:00:00', '2022-12-25 11:00:00'); +``` + +```text ++------------------------------------------+------------------------------------------------------------+ +| QUARTERS_DIFF('2021-03-25','2020-10-25') | QUARTERS_DIFF('2020-10-25 10:00:00','2022-12-25 11:00:00') | ++------------------------------------------+------------------------------------------------------------+ +| 1 | -8 | ++------------------------------------------+------------------------------------------------------------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md new file mode 100644 index 0000000000000..fb5e52441779f --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-geometries.md @@ -0,0 +1,135 @@ +--- +{ + "title": "ST_GEOMETRIES", + "language": "en", + "description": "Returns an array of sub-geometries from a geometry collection." +} +--- + +## Description + +Decomposes a geometry object into an array of its sub-geometries. For collection types (MultiPolygon), it returns each sub-polygon as a separate element in the array. For non-collection types (Point, LineString, Polygon, Circle), it returns a single-element array containing the geometry itself. + +:::note +Since 4.1.2 +::: + +## Syntax + +```sql +ST_GEOMETRIES( ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The input geometry, of type GEOMETRY or VARCHAR (in WKT format) that can be converted to GEOMETRY. | + +## Return Value + +Returns an `ARRAY` where each element is an encoded geometry object that can be used with other spatial functions such as `ST_AsText` or `ST_GeometryType`. + +`ST_GEOMETRIES` has the following edge cases: +- If the input parameter is `NULL`, returns `NULL`. +- If the input parameter cannot be parsed into a valid geometry object, returns `NULL`. +- For non-collection types (`POINT`, `LINESTRING`, `POLYGON`, `CIRCLE`), returns a single-element array containing the input geometry. +- For `MULTIPOLYGON`, returns an array where each element is one of the sub-polygons. +- Array elements can be passed to other spatial functions for further processing. + +## Example + +**Geometries of a Point (single-element array)** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]); +``` +```text ++------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_Point(1, 2))[1]) | ++------------------------------------------------+ +| POINT (1 2) | ++------------------------------------------------+ +``` + +**Geometries of a Polygon (single-element array)** +```sql +SELECT ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------+ +| ST_GeometryType(ST_GEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))'))[1]) | ++----------------------------------------------------------------------------------------------------+ +| ST_POLYGON | ++----------------------------------------------------------------------------------------------------+ +``` + +**Geometries of a MultiPolygon (multiple elements)** +```sql +SELECT SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))); +``` +```text ++----------------------------------------------------------------------------------------------------------------------+ +| SIZE(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))))') | ++----------------------------------------------------------------------------------------------------------------------+ +| 2 | ++----------------------------------------------------------------------------------------------------------------------+ +``` + +**Accessing individual elements of a MultiPolygon** +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[1]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((1 0, 1 1, 0 1, 0 0, 1 0)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +```sql +SELECT ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]); +``` +```text ++----------------------------------------------------------------------------------------------------------------------------------+ +| ST_AsText(ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[2]) | ++----------------------------------------------------------------------------------------------------------------------------------+ +| POLYGON ((3 2, 3 3, 2 3, 2 2, 3 2)) | ++----------------------------------------------------------------------------------------------------------------------------------+ +``` + +**Out-of-bound index (Returns NULL)** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3]; +``` +```text ++----------------------------------------------------------------------------------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))'))[3] | ++----------------------------------------------------------------------------------------------------------------------------+ +| NULL | ++----------------------------------------------------------------------------------------------------------------------------+ +``` + +**NULL Parameter** +```sql +SELECT ST_GEOMETRIES(NULL); +``` +```text ++----------------------+ +| ST_GEOMETRIES(NULL) | ++----------------------+ +| NULL | ++----------------------+ +``` + +**Invalid Parameter (Returns NULL)** +```sql +SELECT ST_GEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++----------------------------------------------------+ +| ST_GEOMETRIES(ST_GeometryFromText('INVALID')) | ++----------------------------------------------------+ +| NULL | ++----------------------------------------------------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md new file mode 100644 index 0000000000000..26f0eb82ac567 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numgeometries.md @@ -0,0 +1,111 @@ +--- +{ + "title": "ST_NUMGEOMETRIES", + "language": "en", + "description": "Returns the number of geometries in a geometry collection." +} +--- + +## Description + +Returns the number of sub-geometries contained in a geometry object. For non-collection types (Point, LineString, Polygon, Circle), it always returns 1. For collection types (MultiPolygon), it returns the number of sub-geometries in the collection. + +:::note +Since 4.1.2 +::: + +## Syntax + +```sql +ST_NUMGEOMETRIES( ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The input geometry, of type GEOMETRY or VARCHAR (in WKT format) that can be converted to GEOMETRY. | + +## Return Value + +Returns a BIGINT value representing the number of sub-geometries in the geometry object. + +`ST_NUMGEOMETRIES` has the following edge cases: +- If the input parameter is `NULL`, returns `NULL`. +- If the input parameter cannot be parsed into a valid geometry object, returns `NULL`. +- For non-collection types (`POINT`, `LINESTRING`, `POLYGON`, `CIRCLE`), always returns `1`. +- For `MULTIPOLYGON`, returns the number of polygons in the collection. + +## Example + +**Number of geometries in a Point** +```sql +SELECT ST_NUMGEOMETRIES(ST_Point(1, 2)); +``` +```text ++----------------------------------+ +| ST_NUMGEOMETRIES(ST_Point(1, 2)) | ++----------------------------------+ +| 1 | ++----------------------------------+ +``` + +**Number of geometries in a Polygon** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++------------------------------------------------------------------------------+ +| 1 | ++------------------------------------------------------------------------------+ +``` + +**Number of geometries in a MultiPolygon with two polygons** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++------------------------------------------------------------------------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++------------------------------------------------------------------------------------------------------------------+ +| 2 | ++------------------------------------------------------------------------------------------------------------------+ +``` + +**Number of geometries in a Circle** +```sql +SELECT ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)); +``` +```text ++----------------------------------------+ +| ST_NUMGEOMETRIES(ST_Circle(0, 0, 100)) | ++----------------------------------------+ +| 1 | ++----------------------------------------+ +``` + +**NULL Parameter** +```sql +SELECT ST_NUMGEOMETRIES(NULL); +``` +```text ++------------------------+ +| ST_NUMGEOMETRIES(NULL) | ++------------------------+ +| NULL | ++------------------------+ +``` + +**Invalid Parameter (Returns NULL)** +```sql +SELECT ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')); +``` +```text ++--------------------------------------------------+ +| ST_NUMGEOMETRIES(ST_GeometryFromText('INVALID')) | ++--------------------------------------------------+ +| NULL | ++--------------------------------------------------+ +``` diff --git a/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md new file mode 100644 index 0000000000000..9dbfcaafd73d7 --- /dev/null +++ b/versioned_docs/version-4.x/sql-manual/sql-functions/scalar-functions/spatial-functions/st-numpoints.md @@ -0,0 +1,138 @@ +--- +{ + "title": "ST_NUMPOINTS", + "language": "en", + "description": "Returns the total number of points in a geometry object." +} +--- + +## Description + +Returns the total number of vertices (points) in a geometry object. For different geometry types, the counting rules are as follows: a Point returns 1, a LineString returns the number of vertices, a Polygon returns the total number of vertices across all rings (including the closing point), and a MultiPolygon returns the sum of all sub-polygon point counts. + +:::note +Since 4.1.2 +::: + +## Syntax + +```sql +ST_NUMPOINTS( ) +``` + +## Parameters + +| Parameter | Description | +| :--- | :--- | +| `` | The input geometry, of type GEOMETRY or VARCHAR (in WKT format) that can be converted to GEOMETRY. | + +## Return Value + +Returns a BIGINT value representing the total number of points in the geometry object. + +`ST_NUMPOINTS` has the following edge cases: +- If the input parameter is `NULL`, returns `NULL`. +- If the input parameter cannot be parsed into a valid geometry object, returns `NULL`. +- For `POINT`, returns `1`. +- For `LINESTRING`, returns the number of vertices in the line. +- For `POLYGON`, returns the total number of vertices across all rings (exterior ring + interior rings). Each ring includes the closing point. +- For `MULTIPOLYGON`, returns the sum of point counts of all sub-polygons. +- For `CIRCLE`, returns `-1` (circles do not have discrete vertices). + +## Example + +**Number of points in a Point** +```sql +SELECT ST_NUMPOINTS(ST_Point(1, 2)); +``` +```text ++------------------------------+ +| ST_NUMPOINTS(ST_Point(1, 2)) | ++------------------------------+ +| 1 | ++------------------------------+ +``` + +**Number of points in a LineString** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')); +``` +```text ++-------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('LINESTRING(0 0, 1 1, 2 2)')) | ++-------------------------------------------------------------------+ +| 3 | ++-------------------------------------------------------------------+ +``` + +**Number of points in a Polygon (square)** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')); +``` +```text ++----------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 1 0, 1 1, 0 1, 0 0))')) | ++----------------------------------------------------------------------------+ +| 5 | ++----------------------------------------------------------------------------+ +``` + +**Number of points in a Polygon with a hole** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')); +``` +```text ++-----------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('POLYGON((0 0, 10 0, 10 10, 0 10, 0 0),(1 1, 2 1, 2 2, 1 2, 1 1))')) | ++-----------------------------------------------------------------------------------------------------------+ +| 10 | ++-----------------------------------------------------------------------------------------------------------+ +``` + +**Number of points in a MultiPolygon** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')); +``` +```text ++--------------------------------------------------------------------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('MULTIPOLYGON(((0 0, 1 0, 1 1, 0 1, 0 0)),((2 2, 3 2, 3 3, 2 3, 2 2)))')) | ++--------------------------------------------------------------------------------------------------------------+ +| 10 | ++--------------------------------------------------------------------------------------------------------------+ +``` + +**Number of points in a Circle (returns -1)** +```sql +SELECT ST_NUMPOINTS(ST_Circle(0, 0, 100)); +``` +```text ++--------------------------------------+ +| ST_NUMPOINTS(ST_Circle(0, 0, 100)) | ++--------------------------------------+ +| -1 | ++--------------------------------------+ +``` + +**NULL Parameter** +```sql +SELECT ST_NUMPOINTS(NULL); +``` +```text ++---------------------+ +| ST_NUMPOINTS(NULL) | ++---------------------+ +| NULL | ++---------------------+ +``` + +**Invalid Parameter (Returns NULL)** +```sql +SELECT ST_NUMPOINTS(ST_GeometryFromText('INVALID')); +``` +```text ++------------------------------------------------+ +| ST_NUMPOINTS(ST_GeometryFromText('INVALID')) | ++------------------------------------------------+ +| NULL | ++------------------------------------------------+ +``` diff --git a/versioned_sidebars/version-3.x-sidebars.json b/versioned_sidebars/version-3.x-sidebars.json index 46cf7953677a6..d4de0ce6f0e26 100644 --- a/versioned_sidebars/version-3.x-sidebars.json +++ b/versioned_sidebars/version-3.x-sidebars.json @@ -1338,6 +1338,9 @@ "sql-manual/sql-functions/scalar-functions/date-time-functions/date-add", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-floor", + "sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil", + "sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor", + "sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-format", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-sub", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc", diff --git a/versioned_sidebars/version-4.x-sidebars.json b/versioned_sidebars/version-4.x-sidebars.json index 1c88549db0f62..a955703d2d581 100644 --- a/versioned_sidebars/version-4.x-sidebars.json +++ b/versioned_sidebars/version-4.x-sidebars.json @@ -1537,6 +1537,7 @@ "label": "Vector Distance Functions", "items": [ "sql-manual/sql-functions/ai-functions/distance-functions/cosine-distance", + "sql-manual/sql-functions/ai-functions/distance-functions/cosine-similarity", "sql-manual/sql-functions/ai-functions/distance-functions/inner-product", "sql-manual/sql-functions/ai-functions/distance-functions/l1-distance", "sql-manual/sql-functions/ai-functions/distance-functions/l2-distance", @@ -1738,6 +1739,9 @@ "sql-manual/sql-functions/scalar-functions/date-time-functions/date-add", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-ceil", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-floor", + "sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-ceil", + "sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor", + "sql-manual/sql-functions/scalar-functions/date-time-functions/quarters-diff", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-format", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-sub", "sql-manual/sql-functions/scalar-functions/date-time-functions/date-trunc", From 82b36a9b0e6d50623098c0562c8f75fa7ebfa3f2 Mon Sep 17 00:00:00 2001 From: linzhenqi Date: Thu, 25 Jun 2026 15:27:44 +0800 Subject: [PATCH 2/2] fix: delete dev version note --- .../scalar-functions/date-time-functions/quarter-floor.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md index 79271e5ed3065..0fa54f6f63a97 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/sql-manual/sql-functions/scalar-functions/date-time-functions/quarter-floor.md @@ -9,10 +9,6 @@ 将日期时间值向下取整到最近的指定季度周期起点。如果指定了起始时间（origin），则以该时间为基准计算周期。 -:::tip -QUARTER_FLOOR 支持从 3.0.8 和 3.1.0 版本开始。 -::: - ## 语法 ```sql