From 31213977090b5433c64426a846ac376bfc6e6297 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jes=C3=BAs=20Arroyo=20Torrens?= <jarroyo@cartodb.com>
Date: Fri, 30 Apr 2021 14:45:34 +0200
Subject: [PATCH] Update sql-reference in spatial-extension-bq

---
 app/content/spatial-extension-bq/_index.md    |   5 +-
 .../sql-reference/clustering.md               |  48 +++++
 .../sql-reference/constructors.md             | 117 +++++++++++
 .../sql-reference/measurements.md             |  99 +++++++++
 .../sql-reference/overview.md                 |   2 +-
 .../sql-reference/transformation.md           |  50 -----
 .../sql-reference/transformations.md          | 195 ++++++++++++++++++
 repos/carto-advanced-spatial-extension        |   2 +-
 repos/carto-spatial-extension                 |   2 +-
 9 files changed, 466 insertions(+), 54 deletions(-)
 create mode 100644 app/content/spatial-extension-bq/sql-reference/clustering.md
 create mode 100644 app/content/spatial-extension-bq/sql-reference/constructors.md
 create mode 100644 app/content/spatial-extension-bq/sql-reference/measurements.md
 delete mode 100644 app/content/spatial-extension-bq/sql-reference/transformation.md
 create mode 100644 app/content/spatial-extension-bq/sql-reference/transformations.md

diff --git a/app/content/spatial-extension-bq/_index.md b/app/content/spatial-extension-bq/_index.md
index 0ce67ccd2..f900ad5ce 100644
--- a/app/content/spatial-extension-bq/_index.md
+++ b/app/content/spatial-extension-bq/_index.md
@@ -27,5 +27,8 @@ cascade:
         - "placekey"
         - "random"
         - "data"
-        - "transformation"
+        - "constructors"
+        - "transformations"
+        - "measurements"
+        - "clustering"
 ---
\ No newline at end of file
diff --git a/app/content/spatial-extension-bq/sql-reference/clustering.md b/app/content/spatial-extension-bq/sql-reference/clustering.md
new file mode 100644
index 000000000..b21f98f55
--- /dev/null
+++ b/app/content/spatial-extension-bq/sql-reference/clustering.md
@@ -0,0 +1,48 @@
+## clustering
+
+<div class="badge advanced"></div>
+
+### ST_CLUSTERKMEANS
+
+{{% bannerNote type="code" %}}
+clustering.ST_CLUSTERKMEANS(geog, numberOfClusters)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a set of points and partition them into clusters using the k-mean. It uses the k-means algorithm. Returns an array with the cluster index for each of the input features. https://turfjs.org/docs/#clustersKmeans
+
+* `geog`: `ARRAY<GEOGRAPHY>` points to be clustered.
+* `numberOfClusters`: `INT64`|`NULL` numberOfClusters that will be generated. If `NULL` the default value `Math.sqrt(<NUMBER OF POINTS>/2)` is used.
+
+**Return type**
+
+`ARRAY<INT64>`
+
+**Example**
+
+```sql
+SELECT bqcarto.clustering.ST_CLUSTERKMEANS([ST_GEOGPOINT(0, 0), ST_GEOGPOINT(0, 1), ST_GEOGPOINT(5, 0), ST_GEOGPOINT(1, 0)], 2);
+-- [1, 1, 0, 1]
+```
+
+### VERSION
+
+{{% bannerNote type="code" %}}
+clustering.VERSION()
+{{%/ bannerNote %}}
+
+**Description**
+
+Returns the current version of the clustering module.
+
+**Return type**
+
+`STRING`
+
+**Example**
+
+```sql
+SELECT bqcarto.clustering.VERSION();
+-- 1.0.0
+```
diff --git a/app/content/spatial-extension-bq/sql-reference/constructors.md b/app/content/spatial-extension-bq/sql-reference/constructors.md
new file mode 100644
index 000000000..ea525ac30
--- /dev/null
+++ b/app/content/spatial-extension-bq/sql-reference/constructors.md
@@ -0,0 +1,117 @@
+## constructors
+
+<div class="badge core"></div>
+
+This module contains functions that create geographies from coordinates or already existing geographies.
+
+### ST_BEZIERSPLINE
+
+{{% bannerNote type="code" %}}
+constructors.ST_BEZIERSPLINE(geog, resolution, sharpness)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a line and returns a curved version by applying a Bezier spline algorithm. https://turfjs.org/docs/#bezierSpline
+
+* `geog`: `GEOGRAPHY` input LineString.
+* `resolution`: `INT64`|`NULL` time in milliseconds between points. If `NULL` the default value `10000` is used.
+* `sharpness`: `FLOAT64`|`NULL` a measure of how curvy the path should be between splines. If `NULL` the default value `0.85` is used.
+
+```sql
+SELECT bqcarto.constructors.ST_BEZIERSPLINE(ST_GEOGFROMTEXT("LINESTRING (-76.091308 18.427501,-76.695556 18.729501,-76.552734 19.40443,-74.61914 19.134789,-73.652343 20.07657,-73.157958 20.210656)"), 10000, 0.9);
+-- LINESTRING(-76.091308 18.427501, -76.0916216712943 ... 
+```
+
+### ST_MAKEELLIPSE
+
+{{% bannerNote type="code" %}}
+constructors.ST_MAKEELLIPSE(geog, xSemiAxis, ySemiAxis, angle, units, steps)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a Point and calculates the ellipse polygon given two semi-axes expressed in variable units and steps for precision. https://github.com/Turfjs/turf/tree/master/packages/turf-ellipse
+
+* `center`: `GEOGRAPHY` center point.
+* `xSemiAxis`: `FLOAT64` semi (major) axis of the ellipse along the x-axis.
+* `ySemiAxis`: `FLOAT64` semi (minor) axis of the ellipse along the y-axis.
+* `angle`: `FLOAT64`|`NULL` angle of rotation (along the vertical axis), from North in decimal degrees, negative clockwise. If `NULL` the default value `0` is used.
+* `units`: `STRING`|`NULL` any of the options supported by turf units: miles, kilometers, and degrees. If `NULL`the default value `kilometers` is used.
+* `steps`: `INT64`|`NULL` number of steps. If `NULL` the default value `64` is used.
+
+```sql
+SELECT bqcarto.constructors.ST_MAKEELLIPSE(ST_GEOGPOINT(-73.9385,40.6643), 5, 3, -30, "miles", 80);
+-- POLYGON((-73.8558575786687 40.7004828957859 ... 
+```
+
+### ST_MAKEENVELOPE
+
+{{% bannerNote type="code" %}}
+constructors.ST_MAKEENVELOPE(xmin, ymin, xma, ymax)
+{{%/ bannerNote %}}
+
+**Description**
+Creates a rectangular Polygon from the minimum and maximum values for X and Y.
+
+
+* `xmin`: `FLOAT64` minimum value for X.
+* `ymin`: `FLOAT64` minimum value for Y.
+* `xmax`: `FLOAT64` maximum value for X.
+* `ymax`: `FLOAT64` maximum value for Y.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.constructors.ST_MAKEENVELOPE(0,0,1,1);
+-- POLYGON((1 0, 1 1, 0 1, 0 0, 1 0)) 
+```
+
+### ST_TILEENVELOPE
+
+{{% bannerNote type="code" %}}
+constructors.ST_TILEENVELOPE(zoomLevel, xTile, yTile)
+{{%/ bannerNote %}}
+
+**Description**
+Returns the boundary polygon of a tile given its zoom level and its X and Y indices.
+
+* `zoomLevel`: `INT64` zoom level of the tile.
+* `xTile`: `INT64` X index of the tile.
+* `yTile`: `INT64` Y index of the tile.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.constructors.ST_TILEENVELOPE(10,384,368);
+-- POLYGON((-45 45.089035564831, -45 44.840290651398, -44.82421875 44.840290651398, -44.6484375 44.840290651398, -44.6484375 45.089035564831, -44.82421875 45.089035564831, -45 45.089035564831))
+```
+
+### VERSION
+
+{{% bannerNote type="code" %}}
+constructors.VERSION()
+{{%/ bannerNote %}}
+
+**Description**
+
+Returns the current version of the constructors module.
+
+**Return type**
+
+`STRING`
+
+**Example**
+
+```sql
+SELECT bqcarto.constructors.VERSION();
+-- 1.1.0
+```
\ No newline at end of file
diff --git a/app/content/spatial-extension-bq/sql-reference/measurements.md b/app/content/spatial-extension-bq/sql-reference/measurements.md
new file mode 100644
index 000000000..90d4a0f0d
--- /dev/null
+++ b/app/content/spatial-extension-bq/sql-reference/measurements.md
@@ -0,0 +1,99 @@
+## measurements
+
+<div class="badge core"></div>
+
+### ST_ANGLE
+
+{{% bannerNote type="code" %}}
+measurements.ST_ANGLE(startPoint, midPoint, endPoint, mercator)
+{{%/ bannerNote %}}
+
+**Description**
+
+Finds the angle formed by two adjacent segments defined by 3 points. The result will be the (positive clockwise) angle with origin on the startPoint-midPoint segment, or its explementary angle if required. https://github.com/Turfjs/turf/tree/master/packages/turf-angle
+
+* `startPoint`: `GEOGRAPHY` start Point Coordinates.
+* `midPoint`: `GEOGRAPHY` mid Point Coordinates.
+* `endPoint`: `GEOGRAPHY` end Point Coordinates.
+* `mercator`: `BOOLEAN`|`NULL` if calculations should be performed over Mercator or WGS84 projection. If `NULL` the default value `false` is used.
+
+**Return type**
+
+`FLOAT64`
+
+**Example**
+
+``` sql
+SELECT bqcarto.measurements.ST_ANGLE(ST_GEOGPOINT(-3.70325 ,40.4167), ST_GEOGPOINT(-4.70325 ,10.4167), ST_GEOGPOINT(-5.70325 ,40.4167), false);
+-- 3.933094586038578
+```
+
+### ST_AZIMUTH
+
+{{% bannerNote type="code" %}}
+measurements.ST_AZIMUTH(startPoint, endPoint)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes two points and finds the geographic bearing between them, i.e. the angle measured in degrees from the north line (0 degrees). https://turfjs.org/docs/#bearing
+
+* `startPoint`: `GEOGRAPHY` starting Point.
+* `endPoint`: `GEOGRAPHY` ending Point.
+
+**Return type**
+
+`FLOAT64`
+
+**Example**
+
+``` sql
+SELECT bqcarto.measurements.ST_AZIMUTH(ST_GEOGPOINT(-3.70325 ,40.4167), ST_GEOGPOINT(-4.70325 ,41.4167));
+-- -36.75052908494255
+```
+
+### ST_MINKOWSKIDISTANCE
+
+{{% bannerNote type="code" %}}
+measurements.ST_MINKOWSKIDISTANCE(geog, p)
+{{%/ bannerNote %}}
+
+**Description**
+
+Calculate the Minkowski p-norm distance between two features. https://github.com/Turfjs/turf/tree/master/packages/turf-distance-weight
+
+* `geog`: `ARRAY<GEOGRAPHY>` featureCollection.
+* `p`: `FLOAT64` minkowski p-norm distance parameter. 1: Manhattan distance. 2: Euclidean distance. 1 =< p <= infinity. If `NULL` the default value `2` is used.
+
+**Return type**
+
+`ARRAY<STRING>`
+
+**Example**
+
+``` sql
+SELECT bqcarto.measurements.ST_MINKOWSKIDISTANCE([ST_GEOGPOINT(10,10),ST_GEOGPOINT(13,10)],2);
+-- ["0,0.3333333333333333","0.3333333333333333,0"]
+```
+
+
+### VERSION
+
+{{% bannerNote type="code" %}}
+measurements.VERSION()
+{{%/ bannerNote %}}
+
+**Description**
+
+Returns the current version of the measurements module.
+
+**Return type**
+
+`STRING`
+
+**Example**
+
+```sql
+SELECT bqcarto.measurements.VERSION();
+-- 1.0.0
+```
diff --git a/app/content/spatial-extension-bq/sql-reference/overview.md b/app/content/spatial-extension-bq/sql-reference/overview.md
index 5b0fb6a31..6bb2498b3 100644
--- a/app/content/spatial-extension-bq/sql-reference/overview.md
+++ b/app/content/spatial-extension-bq/sql-reference/overview.md
@@ -13,7 +13,7 @@ The CARTO Spatial Extension's procedures and functions are organized in modules
 | Placekey | Core | <ul style="list-style:none"><li><a href="../placekey/#h3_asplacekey">H3_ASPLACEKEY</a></li><li><a href="../placekey/#placekey_ash3">PLACEKEY_ASH3</a></li><li><a href="../placekey/#isvalid">ISVALID</a></li><li><a href="../placekey/#version">VERSION</a></li></ul>|
 | Random | Advanced | <ul style="list-style:none"><li><a href="../random/#st_generatepoints">ST_GENERATEPOINTS</a></li></li><li><a href="../random/#version">VERSION</a></li></ul>|
 | Data | Advanced | <ul style="list-style:none"><li><a href="../data/#st_getpopulationdensity">ST_GETPOPULATIONDENSITY</a></li></li><li><a href="../data/#version">VERSION</a></li></ul>|
-| Transformation | Core | <ul style="list-style:none"><li><a href="../transformation/#st_buffer">ST_BUFFER</a></li></li><li><a href="../transformation/#version">VERSION</a></li></ul>|
+| Transformations | Core | <ul style="list-style:none"><li><a href="../transformations/#st_buffer">ST_BUFFER</a></li></li><li><a href="../transformations/#version">VERSION</a></li></ul>|
 
 ### Release notes
 
diff --git a/app/content/spatial-extension-bq/sql-reference/transformation.md b/app/content/spatial-extension-bq/sql-reference/transformation.md
deleted file mode 100644
index 10a960af6..000000000
--- a/app/content/spatial-extension-bq/sql-reference/transformation.md
+++ /dev/null
@@ -1,50 +0,0 @@
-## transformation
-
-<div class="badge core"></div>
-
-### ST_BUFFER
-
-{{% bannerNote type="code" %}}
-transformation.ST_BUFFER(geog, radius, units, steps)
-{{%/ bannerNote %}}
-
-**Description**
-
-Calculates a Geography buffer for input features for a given radius. Units supported are miles, kilometers, and degrees. https://turfjs.org/docs/#buffer
-
-* `geog`: `GEOGRAPHY` input to be buffered.
-* `radius`: `FLOAT64` distance to draw the buffer (negative values are allowed).
-* `units`: `STRING` any of the options supported by turf units: miles, kilometers, and degrees.
-* `steps`: `INT64` number of steps.
-
-**Return type**
-
-`GEOGRAPHY`
-
-**Example**
-
-``` sql
-SELECT bqcarto.transformation.ST_BUFFER(ST_GEOGPOINT(-74.00, 40.7128), 1, 'kilometers', 10);
--- POLYGON((-73.9881354374691 40.7127993926494 ... 
-```
-
-### VERSION
-
-{{% bannerNote type="code" %}}
-transformation.VERSION()
-{{%/ bannerNote %}}
-
-**Description**
-
-Returns the current version of the transformation module.
-
-**Return type**
-
-`STRING`
-
-**Example**
-
-```sql
-SELECT bqcarto.transformation.VERSION();
--- 1.0.0
-```
diff --git a/app/content/spatial-extension-bq/sql-reference/transformations.md b/app/content/spatial-extension-bq/sql-reference/transformations.md
new file mode 100644
index 000000000..203a8a276
--- /dev/null
+++ b/app/content/spatial-extension-bq/sql-reference/transformations.md
@@ -0,0 +1,195 @@
+## transformations
+
+<div class="badge core"></div>
+
+### ST_BUFFER
+
+{{% bannerNote type="code" %}}
+transformations.ST_BUFFER(geog, radius, units, steps)
+{{%/ bannerNote %}}
+
+**Description**
+
+Calculates a Geography buffer for input features for a given radius. Units supported are miles, kilometers, and degrees. https://turfjs.org/docs/#buffer
+
+* `geog`: `GEOGRAPHY` input to be buffered.
+* `radius`: `FLOAT64` distance to draw the buffer (negative values are allowed).
+* `units`: `STRING`|`NULL` any of the options supported by turf units: miles, kilometers, and degrees. If `NULL`the default value `kilometers` is used.
+* `steps`: `INT64`|`NULL` number of steps. If `NULL` the default value `8` is used.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_BUFFER(ST_GEOGPOINT(-74.00, 40.7128), 1, "kilometers", 10);
+-- POLYGON((-73.9881354374691 40.7127993926494 ... 
+```
+
+### ST_CENTERMEAN
+
+{{% bannerNote type="code" %}}
+transformations.ST_CENTERMEAN(geog)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a Feature or FeatureCollection and returns the mean center. https://github.com/Turfjs/turf/tree/master/packages/turf-center-mean
+
+* `geog`: `GEOGRAPHY` feature to be centered.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_CENTERMEAN(ST_GEOGFROMTEXT("POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"));
+-- POINT(25.3890912155939 29.7916831655627)
+```
+
+### ST_CENTERMEDIAN
+
+{{% bannerNote type="code" %}}
+transformations.ST_CENTERMEDIAN(geog)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a FeatureCollection of points and calculates the median center, algorithimically. The median center is understood as the point that is requires the least total travel from all other points. https://github.com/Turfjs/turf/tree/master/packages/turf-center-median
+
+* `geog`: `GEOGRAPHY` feature to be centered.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_CENTERMEDIAN(ST_GEOGFROMTEXT("POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"));
+-- POINT(25.3783930513609 29.8376035441371)
+```
+
+### ST_CENTEROFMASS
+
+{{% bannerNote type="code" %}}
+transformations.ST_CENTEROFMASS(geog)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes any Feature or a FeatureCollection and returns its center of mass using this formula: Centroid of Polygon. https://turfjs.org/docs/#centerOfMass
+
+* `geog`: `GEOGRAPHY` feature to be centered.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_CENTEROFMASS(ST_GEOGFROMTEXT("POLYGON ((30 10, 40 40, 20 40, 10 20, 30 10))"));
+-- POINT(25.1730977433239 27.2789529273059) 
+```
+
+### ST_DESTINATION
+
+{{% bannerNote type="code" %}}
+transformations.ST_DESTINATION(startPoint, distance, bearing, units)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a Point and calculates the location of a destination point given a distance in degrees, radians, miles, or kilometers; and bearing in degrees. This uses the Haversine formula to account for global curvature. https://turfjs.org/docs/#destination
+
+* `origin`: `GEOGRAPHY` starting point.
+* `distance`: `FLOAT64` distance from the origin point.
+* `bearing`: `FLOAT64` ranging from -180 to 180.
+* `units`: `STRING`|`NULL` any of the options supported by turf units: miles, kilometers, degrees or radians. If `NULL`the default value `kilometers` is used.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_DESTINATION(ST_GEOGPOINT(-3.70325,40.4167), 10, 45, "miles");
+-- POINT(-3.56862505487045 40.5189626777536)
+```
+
+### ST_GREATCIRCLE
+
+{{% bannerNote type="code" %}}
+transformations.ST_GREATCIRCLE(startPoint, endPoint, npoints)
+{{%/ bannerNote %}}
+
+**Description**
+
+Calculate great circles routes as LineString or MultiLineString. If the start and end points span the antimeridian, the resulting feature will be split into a MultiLineString. https://turfjs.org/docs/#greatCircle
+
+* `startPoint`: `GEOGRAPHY` source point feature.
+* `endPoint`: `GEOGRAPHY` destination point feature.
+* `npoints`: `INT64`|`NULL` number of points. If `NULL` the default value `100` is used.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_GREATCIRCLE(ST_GEOGPOINT(-3.70325,40.4167), ST_GEOGPOINT(-73.9385,40.6643), 20);
+-- LINESTRING(-3.70325 40.4167 ... 
+```
+
+### ST_LINE_INTERPOLATE_POINT
+
+{{% bannerNote type="code" %}}
+transformations.ST_LINE_INTERPOLATE_POINT(geog, distance, units)
+{{%/ bannerNote %}}
+
+**Description**
+
+Takes a LineString and returns a Point at a specified distance along the line. https://turfjs.org/docs/#along
+
+* `geog`: `GEOGRAPHY` input line.
+* `distance`: `FLOAT64` distance along the line.
+* `units`: `STRING`|`NULL` any of the options supported by turf units: miles, kilometers, degrees and radians. If `NULL`the default value `kilometers` is used.
+
+**Return type**
+
+`GEOGRAPHY`
+
+**Example**
+
+``` sql
+SELECT bqcarto.transformations.ST_LINE_INTERPOLATE_POINT(ST_GEOGFROMTEXT("LINESTRING (-76.091308 18.427501,-76.695556 18.729501,-76.552734 19.40443,-74.61914 19.134789,-73.652343 20.07657,-73.157958 20.210656)"), 250, 'miles');
+-- POINT(-74.297592068938 19.4498107103156) 
+```
+
+### VERSION
+
+{{% bannerNote type="code" %}}
+transformations.VERSION()
+{{%/ bannerNote %}}
+
+**Description**
+
+Returns the current version of the transformations module.
+
+**Return type**
+
+`STRING`
+
+**Example**
+
+```sql
+SELECT bqcarto.transformations.VERSION();
+-- 1.1.0
+```
diff --git a/repos/carto-advanced-spatial-extension b/repos/carto-advanced-spatial-extension
index 3b298aa3b..d53cd960c 160000
--- a/repos/carto-advanced-spatial-extension
+++ b/repos/carto-advanced-spatial-extension
@@ -1 +1 @@
-Subproject commit 3b298aa3b34fd607961a97e103445610ad421f47
+Subproject commit d53cd960ce77f5c9c770ed4bc232fc2d9d021127
diff --git a/repos/carto-spatial-extension b/repos/carto-spatial-extension
index 352d94abd..af463a287 160000
--- a/repos/carto-spatial-extension
+++ b/repos/carto-spatial-extension
@@ -1 +1 @@
-Subproject commit 352d94abd3e2d12f3c21997dfeab66ee8cfb0738
+Subproject commit af463a28722da3aca0d7a6984832c16b43a19084