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