Merge branch 'awsdocs:master' into patch-1

doc_source/AddBBox-function.md

@@ -0,0 +1,34 @@
+# AddBBox<a name="AddBBox-function"></a>
+
+AddBBox returns a copy of the input geometry that supports encoding with a precomputed bounding box\. For more information about support for bounding boxes, see [Bounding box](spatial-terminology.md#spatial-terminology-bounding-box)\.
+
+## Syntax<a name="AddBBox-function-syntax"></a>
+
+```
+AddBBox(geom)
+```
+
+## Arguments<a name="AddBBox-function-arguments"></a>
+
+ *geom*   
+A value of data type `GEOMETRY` or an expression that evaluates to a `GEOMETRY` type\.
+
+## Return type<a name="AddBBox-function-return"></a>
+
+`GEOMETRY`
+
+If *geom* is null, then null is returned\.
+
+## Examples<a name="AddBBox-function-examples"></a>
+
+The following SQL returns a copy of an input polygon geometry that supports being encoded with a bounding box\. 
+
+```
+SELECT ST_AsText(AddBBox(ST_GeomFromText('POLYGON((0 0,1 0,0 1,0 0))')));
+```
+
+```
+ st_astext
+----------
+ POLYGON((0 0,1 0,0 1,0 0))
+```

doc_source/CONVERT_TIMEZONE.md

@@ -42,6 +42,8 @@ select pg_timezone_names();
 select pg_timezone_abbrevs();
 ```
 
+See a list of each at [Appendix: Time zone names and abbreviations](appendix-timezone-names.md)\.
+
 ### Using a time zone name<a name="CONVERT_TIMEZONE-using-name"></a>
 
 If you specify a time zone using a time zone name, CONVERT\_TIMEZONE automatically adjusts for Daylight Saving Time \(DST\), or any other local seasonal protocol, such as Summer Time, Standard Time, or Winter Time, that is in force for that time zone during the date and time specified by '*timestamp*'\. For example, 'Europe/London' represents UTC in the winter and UTC\+1 in the summer\. 

doc_source/DropBBox-function.md

@@ -0,0 +1,34 @@
+# DropBBox<a name="DropBBox-function"></a>
+
+DropBBox returns a copy of the input geometry that doesn't support encoding with a precomputed bounding box\. For more information about support for bounding boxes, see [Bounding box](spatial-terminology.md#spatial-terminology-bounding-box)\.
+
+## Syntax<a name="DropBBox-function-syntax"></a>
+
+```
+DropBBox(geom)
+```
+
+## Arguments<a name="DropBBox-function-arguments"></a>
+
+ *geom*   
+A value of data type `GEOMETRY` or an expression that evaluates to a `GEOMETRY` type\.
+
+## Return type<a name="DropBBox-function-return"></a>
+
+`GEOMETRY`
+
+If *geom* is null, then null is returned\.
+
+## Examples<a name="DropBBox-function-examples"></a>
+
+The following SQL returns a copy of an input polygon geometry that doesn't support being encoded with a bounding box\. 
+
+```
+SELECT ST_AsText(DropBBox(ST_GeomFromText('POLYGON((0 0,1 0,0 1,0 0))')));
+```
+
+```
+ st_astext
+----------
+ POLYGON((0 0,1 0,0 1,0 0))
+```

doc_source/Examples__compression_encodings_in_CREATE_TABLE_statements.md

@@ -26,4 +26,4 @@ The following table shows the column encodings that were chosen for the CUSTOMER
 | CITY | varchar\(30\) | text255 | CITY is a large domain, with some repeated values\. Certain city names are used much more commonly than others\. Text255 is a good choice for the same reasons as ADDRESS\. | 
 | STATE | char\(2\) | raw | In the United States, STATE is a precise domain of 50 two\-character values\. Bytedict encoding would yield some compression, but because the column size is only two characters, compression might not be worth the overhead of uncompressing the data\. | 
 | ZIPCODE | char\(5\) | bytedict | ZIPCODE is a known domain of fewer than 50,000 unique values\. Certain zip codes occur much more commonly than others\. Bytedict encoding is very effective when a column contains a limited number of unique values\.  | 
-| START\_DATE | date | delta32k | Delta encodings are very useful for datetime columns, especially if the rows are loaded in date order\. | 
+| START\_DATE | date | delta32k | Delta encodings are very useful for date time columns, especially if the rows are loaded in date order\. | 

doc_source/GeometryType-function.md

@@ -22,15 +22,15 @@ If *geom* is null, then null is returned\.
 The values returned are as follows\.
 
 
-| Returned string value | Geometry subtype | 
-| --- | --- | 
-| `POINT` | Returned if *geom* is a `POINT` subtype  | 
-| `LINESTRING` | Returned if *geom* is a `LINESTRING` subtype  | 
-| `POLYGON` | Returned if *geom* is a `POLYGON` subtype  | 
-| `MULTIPOINT` | Returned if *geom* is a `MULTIPOINT` subtype  | 
-| `MULTILINESTRING` | Returned if *geom* is a `MULTILINESTRING` subtype  | 
-| `MULTIPOLYGON` | Returned if *geom* is a `MULTIPOLYGON` subtype  | 
-| `GEOMETRYCOLLECTION` | Returned if *geom* is a `GEOMETRYCOLLECTION` subtype  | 
+| Returned string value for 2D, 3DZ, 4D geometries | Returned string value for 3DM geometries | Geometry subtype | 
+| --- | --- | --- | 
+| `POINT` | `POINTM` | Returned if *geom* is a `POINT` subtype  | 
+| `LINESTRING` | `LINESTRINGM` | Returned if *geom* is a `LINESTRING` subtype  | 
+| `POLYGON` | `POLYGONM` | Returned if *geom* is a `POLYGON` subtype  | 
+| `MULTIPOINT` | `MULTIPOINTM` | Returned if *geom* is a `MULTIPOINT` subtype  | 
+| `MULTILINESTRING` | `MULTILINESTRINGM` | Returned if *geom* is a `MULTILINESTRING` subtype  | 
+| `MULTIPOLYGON` | `MULTIPOLYGONM` | Returned if *geom* is a `MULTIPOLYGON` subtype  | 
+| `GEOMETRYCOLLECTION` | `GEOMETRYCOLLECTIONM` | Returned if *geom* is a `GEOMETRYCOLLECTION` subtype  | 
 
 ## Examples<a name="GeometryType-function-examples"></a>
 

doc_source/JSON_PARSE.md

@@ -0,0 +1,40 @@
+# JSON\_PARSE function<a name="JSON_PARSE"></a>
+
+The JSON\_PARSE function parses data in JSON format and converts it into the SUPER representation\. 
+
+To ingest into SUPER data type using the INSERT or UPDATE command, use the JSON\_PARSE function\.
+
+## Syntax<a name="JSON_PARSE-synopsis"></a>
+
+```
+JSON_PARSE(json_string)
+```
+
+## Arguments<a name="JSON_PARSE-arguments"></a>
+
+ *json\_string*  
+An expression that returns serialized JSON in the varchar form\. 
+
+## Return type<a name="JSON_PARSE-return"></a>
+
+SUPER
+
+## Example<a name="JSON_PARSE-examples"></a>
+
+The following example is an example of the JSON\_PARSE function\.
+
+```
+SELECT JSON_PARSE('[10001,10002,"abc"]');
+     json_parse
+--------------------------
+ [10001,10002,"abc"]
+(1 row)
+```
+
+```
+SELECT JSON_TYPEOF(JSON_PARSE('[10001,10002,"abc"]'));
+ json_typeof
+----------------
+ array
+(1 row)
+```

doc_source/JSON_SERIALIZE.md

@@ -0,0 +1,32 @@
+# JSON\_SERIALIZE function<a name="JSON_SERIALIZE"></a>
+
+The JSON\_SERIALIZE function serializes a SUPER expression into textual JSON representation to follow RFC 8259\. For more information on that RFC, see [The JavaScript Object Notation \(JSON\) Data Interchange Format](https://docs.aws.amazon.com/https://tools.ietf.org/html/rfc8259)\.
+
+The SUPER size limit is approximately the same as the block limit, and the varchar limit is smaller than the SUPER size limit\. Therefore, the JSON\_SERIALIZE function returns an error when the JSON format exceeds the varchar limit of the system\.
+
+## Syntax<a name="JSON_SERIALIZE-synopsis"></a>
+
+```
+JSON_SERIALIZE(super_expression)
+```
+
+## Arguments<a name="JSON_SERIALIZE-arguments"></a>
+
+ *super\_expression*  
+A super expression or column\.
+
+## Return type<a name="JSON_SERIALIZE-return"></a>
+
+varchar
+
+## Example<a name="JSON_SERIALIZE-examples"></a>
+
+The following example serializes a SUPER value to a string\.
+
+```
+ SELECT JSON_SERIALIZE(JSON_PARSE('[10001,10002,"abc"]'));
+   json_serialize
+---------------------
+ [10001,10002,"abc"]
+(1 row)
+```

doc_source/ST_AddPoint-function.md

@@ -4,6 +4,8 @@ ST\_AddPoint returns a linestring geometry that is the same as the input geometr
 
 The index is zero\-based\. The spatial reference system identifier \(SRID\) of the result is the same as that of the input geometry\. 
 
+The dimension of the returned geometry is the same as that of the *geom1* value\. If *geom1* and *geom2* have different dimensions, *geom2* is projected to the dimension of *geom1*\.
+
 ## Syntax<a name="ST_AddPoint-function-syntax"></a>
 
 ```
@@ -20,7 +22,7 @@ ST_AddPoint(geom1, geom2, index)
 A value of data type `GEOMETRY` or an expression that evaluates to a `GEOMETRY` type\. The subtype must be `LINESTRING`\. 
 
  *geom2*   
-A value of data type `GEOMETRY` or an expression that evaluates to a `GEOMETRY` type\. The subtype must be `POINT`\. 
+A value of data type `GEOMETRY` or an expression that evaluates to a `GEOMETRY` type\. The subtype must be `POINT`\. The point can be the empty point\.
 
  *index*   
 A value of data type `INTEGER` that represents the position of a zero\-based index\. 
@@ -31,6 +33,8 @@ A value of data type `INTEGER` that represents the position of a zero\-based ind
 
 If *geom1*, *geom2*, or *index* is null, then null is returned\. 
 
+If *geom2* is the empty point, then a copy of *geom1* is returned\. 
+
 If *geom1* is not a `LINESTRING`, then an error is returned\. 
 
 If *geom2* is not a `POINT`, then an error is returned\. 

doc_source/ST_Angle-function.md

@@ -6,6 +6,8 @@ ST\_Angle returns the angle in radians between points measured clockwise as foll
 
 The return value is in radians and in the range \[0, 2π\)\. 
 
+ST\_Angle operates on 2D projections of the input geometries\.
+
 ## Syntax<a name="ST_Angle-function-syntax"></a>
 
 ```
@@ -38,9 +40,9 @@ If *geom1* equals *geom2*, or *geom2* equals *geom3*, then a null is returned\.
 
 If *geom1*, *geom2*, *geom3*, or *geom4* is null, then a null is returned\. 
 
-If *geom1*, *geom2*, *geom3*, *geom4* are not two\-dimensional points, then an error is returned\. 
+If any of *geom1*, *geom2*, *geom3*, or *geom4* is the empty point, then an error is returned\. 
 
-If *geom1*, *geom2*, *geom3*, *geom4* don't have the same value for the spatial reference system identifier \(SRID\), then an error is returned\. 
+If *geom1*, *geom2*, *geom3*, and *geom4* don't have the same value for the spatial reference system identifier \(SRID\), then an error is returned\. 
 
 ## Examples<a name="ST_Angle-function-examples"></a>
 

doc_source/ST_Area-function.md

@@ -1,6 +1,6 @@
 # ST\_Area<a name="ST_Area-function"></a>
 
-ST\_Area returns the Cartesian area of an input geometry\. The area units are the same as the units in which the coordinates of the input geometry are expressed\. For points, linestrings, multipoints, and multilinestrings, the function returns 0\. For geometry collections, it returns the sum of the areas of the geometries in the collection\. 
+ST\_Area returns the Cartesian area of the 2D projection of an input geometry\. The area units are the same as the units in which the coordinates of the input geometry are expressed\. For points, linestrings, multipoints, and multilinestrings, the function returns 0\. For geometry collections, it returns the sum of the areas of the geometries in the collection\. 
 
 ## Syntax<a name="ST_Area-function-syntax"></a>
 

doc_source/ST_AsBinary-function.md

@@ -1,6 +1,6 @@
 # ST\_AsBinary<a name="ST_AsBinary-function"></a>
 
-ST\_AsBinary returns the hexadecimal well\-known binary \(WKB\) representation of an input geometry using ASCII hexadecimal characters \(0–9, A–F\)\. 
+ST\_AsBinary returns the hexadecimal well\-known binary \(WKB\) representation of an input geometry using ASCII hexadecimal characters \(0–9, A–F\)\. For 3DZ, 3DM, and 4D geometries, ST\_AsBinary uses the Open Geospatial Consortium \(OGC\) standard value for the geometry type\. 
 
 ## Syntax<a name="ST_AsBinary-function-syntax"></a>
 

doc_source/ST_AsEWKB-function.md

@@ -1,6 +1,6 @@
 # ST\_AsEWKB<a name="ST_AsEWKB-function"></a>
 
-ST\_AsEWKB returns the extended well\-known binary \(EWKB\) representation of an input geometry using ASCII hexadecimal characters \(0–9, A–F\)\. 
+ST\_AsEWKB returns the extended well\-known binary \(EWKB\) representation of an input geometry using ASCII hexadecimal characters \(0–9, A–F\)\. For 3DZ, 3DM, and 4D geometries, ST\_AsEWKB uses the PostGIS extended WKB value for the geometry type\.
 
 ## Syntax<a name="ST_AsEWKB-function-syntax"></a>
 

doc_source/ST_AsEWKT-function.md

@@ -1,6 +1,6 @@
 # ST\_AsEWKT<a name="ST_AsEWKT-function"></a>
 
-ST\_AsEWKT returns the extended well\-known text \(EWKT\) representation of an input geometry\. 
+ST\_AsEWKT returns the extended well\-known text \(EWKT\) representation of an input geometry\. For 3DZ, 3DM, and 4D geometries, ST\_AsEWKT appends Z, M, or ZM to the WKT value for the geometry type\.
 
 ## Syntax<a name="ST_AsEWKT-function-syntax"></a>
 

doc_source/ST_AsGeoJSON-function.md

@@ -2,6 +2,8 @@
 
 ST\_AsGeoJSON returns the GeoJSON representation of an input geometry\. For more information about GeoJSON, see [GeoJSON](https://en.wikipedia.org/wiki/GeoJSON) in Wikipedia\.
 
+For 3DZ and 4D geometries, the output geometry is a 3DZ projection of the input 3DZ or 4D geometry\. That is, the `x`, `y`, and `z` coordinates are present in the output\. For 3DM geometries, the output geometry is a 2D projection of the input 3DM geometry\. That is, only `x` and `y` coordinates are present in the output\.
+
 ## Syntax<a name="ST_AsGeoJSON-function-syntax"></a>
 
 ```

doc_source/ST_AsText-function.md

@@ -1,6 +1,6 @@
 # ST\_AsText<a name="ST_AsText-function"></a>
 
-ST\_AsText returns the well\-known text \(WKT\) representation of an input geometry\. 
+ST\_AsText returns the well\-known text \(WKT\) representation of an input geometry\. For 3DZ, 3DM, and 4D geometries, ST\_AsEWKT appends Z, M, or ZM to the WKT value for the geometry type\.
 
 ## Syntax<a name="ST_AsText-function-syntax"></a>
 

doc_source/ST_Azimuth-function.md

@@ -1,6 +1,6 @@
 # ST\_Azimuth<a name="ST_Azimuth-function"></a>
 
-ST\_Azimuth returns the north\-based Cartesian azimuth of two input points\. 
+ST\_Azimuth returns the north\-based Cartesian azimuth using the 2D projections of the two input points\. 
 
 ## Syntax<a name="ST_Azimuth-function-syntax"></a>
 
@@ -20,6 +20,8 @@ A `POINT` value of data type `GEOMETRY`\. The SRID of *point2* must match the SR
 
 A number that is an angle in radians of `DOUBLE PRECISION` data type\. Values range from 0 \(inclusive\) to 2 pi \(exclusive\)\. 
 
+If *point1* or *point2* is the empty point, then an error is returned\. 
+
 If either *point1* or *point2* is null, then null is returned\. 
 
 If *point1* and *point2* are equal, then null is returned\. 

doc_source/ST_Boundary-function.md

@@ -7,6 +7,8 @@ ST\_Boundary returns the boundary of an input geometry as follows:
 + If the input is a polygon that does not have any interior rings, then a closed linestring representing its boundary is returned\.
 + If the input is a polygon that has interior rings, or is a multipolygon, then a multilinestring is returned\. The multilinestring contains all the boundaries of all the rings in the areal geometry as closed linestrings\.
 
+To determine point equality, ST\_Boundary operates on the 2D projection of the input geometry\. If the input geometry is empty, a copy of it is returned in the same dimension as the input\. For nonempty 3DM and 4D geometries, their `m` coordinates are dropped\. In the special case of 3DZ and 4D multilinestrings, the `z` coordinates of the multilinestring's boundary points are computed as the averages of the distinct z\-values of the linestring boundary points with the same 2D projection\.
+
 ## Syntax<a name="ST_Boundary-function-syntax"></a>
 
 ```

doc_source/ST_Collect-function.md

@@ -14,6 +14,8 @@ The second variant of ST\_Collect creates a geometry from geometries in a geomet
 + If all non\-NULL rows in the aggregate expression are polygons, the result is a multipolygon containing all the polygons in the aggregate expression is returned\. 
 + Otherwise, a `GEOMETRYCOLLECTION` containing all the geometries in the aggregate expression is returned\. 
 
+The ST\_Collect returns the geometry of the same dimension as the input geometries\. All input geometries must be of the same dimension\.
+
 ## Syntax<a name="ST_Collect-function-syntax"></a>
 
 ```
@@ -56,6 +58,10 @@ If two geometries in *aggregate\_expression* have different SRID values, then an
 
 If the returned geometry is larger than the maximum size of a `GEOMETRY`, then an error is returned\. 
 
+If *geom1* and *geom2* are of different dimensions, then an error is returned\. 
+
+If two geometries in *aggregate\_expression* are of different dimensions, then an error is returned\. 
+
 ## Examples<a name="ST_Collect-function-examples"></a>
 
 The following SQL returns a geometry collection that contains the two input geometries\. 

doc_source/ST_Contains-function.md

@@ -1,6 +1,6 @@
 # ST\_Contains<a name="ST_Contains-function"></a>
 
-ST\_Contains returns true if the first input geometry contains the second input geometry\. Geometry `A` contains geometry `B` if every point in `B` is a point in `A`, and their interiors have nonempty intersection\. 
+ST\_Contains returns true if the 2D projection of the first input geometry contains the 2D projection of the second input geometry\. Geometry `A` contains geometry `B` if every point in `B` is a point in `A`, and their interiors have nonempty intersection\. 
 
 ST\_Contains\(`A`, `B`\) is equivalent to ST\_Within\(`B`, `A`\)\. 
 

doc_source/ST_ContainsProperly-function.md

@@ -1,6 +1,6 @@
 # ST\_ContainsProperly<a name="ST_ContainsProperly-function"></a>
 
-ST\_ContainsProperly returns true if both input geometries are nonempty, and all points of the second geometry are interior points of the first geometry\. 
+ST\_ContainsProperly returns true if both input geometries are nonempty, and all points of the 2D projection of the second geometry are interior points of the 2D projection of the first geometry\. 
 
 ## Syntax<a name="ST_ContainsProperly-function-syntax"></a>
 

doc_source/ST_ConvexHull-function.md

@@ -2,6 +2,8 @@
 
 ST\_ConvexHull returns a geometry that represents the convex hull of the nonempty points contained in the input geometry\. 
 
+For empty input, the resulting geometry is the same as the input geometry\. For all nonempty input, the function operates on the 2D projection of the input geometry\. However, the dimension of the output geometry depends on the dimension of the input geometry\. More specifically, when the input geometry is a nonempty 3DM or 3D geometry, `m` coordinates are dropped\. That is, the dimension of the returned geometry is 2D or 3DZ, respectively\. If the input is a nonempty 2D or 3DZ geometry, the resulting geometry has the same dimension\.
+
 ## Syntax<a name="ST_ConvexHull-function-syntax"></a>
 
 ```

doc_source/ST_CoveredBy-function.md

@@ -1,6 +1,6 @@
 # ST\_CoveredBy<a name="ST_CoveredBy-function"></a>
 
-ST\_CoveredBy returns true if the first input geometry is covered by the second input geometry\. Geometry `A` is covered by geometry `B` if both are nonempty and every point in `A` is a point in `B`\. 
+ST\_CoveredBy returns true if the 2D projection of the first input geometry is covered by the 2D projection of the second input geometry\. Geometry `A` is covered by geometry `B` if both are nonempty and every point in `A` is a point in `B`\. 
 
 ST\_CoveredBy\(`A`, `B`\) is equivalent to ST\_Covers\(`B`, `A`\)\. 
 

doc_source/ST_Covers-function.md

@@ -1,6 +1,6 @@
 # ST\_Covers<a name="ST_Covers-function"></a>
 
-ST\_Covers returns true if the first input geometry covers the second input geometry\. Geometry `A` covers geometry `B` if both are nonempty and every point in `B` is a point in `A`\. 
+ST\_Covers returns true if the 2D projection of the first input geometry covers the 2D projection of the second input geometry\. Geometry `A` covers geometry `B` if both are nonempty and every point in `B` is a point in `A`\. 
 
 ST\_Covers\(`A`, `B`\) is equivalent to ST\_CoveredBy\(`B`, `A`\)\. 
 

doc_source/ST_Crosses-function.md

@@ -1,6 +1,6 @@
 # ST\_Crosses<a name="ST_Crosses-function"></a>
 
-ST\_Crosses returns true if the two input geometries cross each other\. 
+ST\_Crosses returns true if the 2D projections of the two input geometries cross each other\. 
 
 ## Syntax<a name="ST_Crosses-function-syntax"></a>
 

doc_source/ST_DWithin-function.md

@@ -1,6 +1,6 @@
 # ST\_DWithin<a name="ST_DWithin-function"></a>
 
-ST\_DWithin returns true if the Euclidean distance between two input geometry values is not larger than a threshold value\. 
+ST\_DWithin returns true if the Euclidean distance between the 2D projections of the two input geometry values is not larger than a threshold value\. 
 
 ## Syntax<a name="ST_DWithin-function-syntax"></a>
 

doc_source/ST_Dimension-function.md

@@ -2,6 +2,8 @@
 
 ST\_Dimension returns the inherent dimension of an input geometry\. The *inherent dimension* is the dimension value of the subtype that is defined in the geometry\. 
 
+For 3DM, 3DZ, and 4D geometry inputs, ST\_Dimension returns the same result as for 2D geometry inputs\.
+
 ## Syntax<a name="ST_Dimension-function-syntax"></a>
 
 ```