Add docs on spatial indexes

Fixes #8563. Addresses #7835, #7900, #7901, #7902, #7903, #8172, #8356, #8377, #8513, #8567. Summary of changes: - Add a new page 'Spatial Indexes' that: - Describes what they are and how they work at high and lower(ish) levels - Provides some examples of usage, including how to tune them to generate tighter or looser coverings with 'CREATE INDEX', as well as exploring potential coverings with 'st_s2covering'. - Add links to/from 'CREATE INDEX', 'Indexes', and 'Inverted Indexes' pages. - Also, add lots of cross-linking among various spatial pages, esp. where indexing is mentioned in the text thereof.
cockroachdb · Oct 12, 2020 · 5494887 · 5494887
1 parent 56fa3d2
commit 5494887
Show file tree

Hide file tree

Showing 20 changed files with 343 additions and 35 deletions.
diff --git a/_includes/sidebar-data-v20.2.json b/_includes/sidebar-data-v20.2.json
@@ -118,10 +118,10 @@
                 ]
               },
               {
-              		"title": "Working with Spatial Data",
-              		"urls": [
-              		  "/${VERSION}/spatial-data.html"
-              		]
+                "title": "Working with Spatial Data",
+                "urls": [
+                    "/${VERSION}/spatial-data.html"
+                ]
               }
             ]
           }
@@ -2009,21 +2009,27 @@
     		]
       },
       {
-    		"title": "Spatial Features",
-    		  "items": [
-    		      {
-    			  "title": "Overview",
-    			  "urls": [
-    			      "/${VERSION}/spatial-features.html"
-    			  ]
-	      },
-	      {
-  			  "title": "Spatial and GIS Glossary of Terms",
-  			  "urls": [
-  			      "/${VERSION}/spatial-glossary.html"
-  			  ]
-	      }
-	]
+          "title": "Spatial Features",
+          "items": [
+              {
+                  "title": "Overview",
+                  "urls": [
+                      "/${VERSION}/spatial-features.html"
+                  ]
+              },
+              {
+                  "title": "Spatial and GIS Glossary of Terms",
+                  "urls": [
+                      "/${VERSION}/spatial-glossary.html"
+                  ]
+              },
+              {
+                  "title": "Spatial Indexes",
+                  "urls": [
+                      "/${VERSION}/spatial-indexes.html"
+                  ]
+              }
+          ]
       },
       {
     		"title": "Performance Optimization",

diff --git a/_includes/v20.2/sql/spatial-support-new.md b/_includes/v20.2/sql/spatial-support-new.md
@@ -0,0 +1 @@
+<span class="version-tag">New in v20.2</span>: CockroachDB supports efficiently storing and querying spatial data.
diff --git a/images/v20.2/geospatial/quadtree.png b/images/v20.2/geospatial/quadtree.png
diff --git a/images/v20.2/geospatial/s2-coverings-tiled.png b/images/v20.2/geospatial/s2-coverings-tiled.png
diff --git a/images/v20.2/geospatial/s2-coverings.gif b/images/v20.2/geospatial/s2-coverings.gif
diff --git a/images/v20.2/geospatial/s2-cubed-sphere-2d.png b/images/v20.2/geospatial/s2-cubed-sphere-2d.png
diff --git a/images/v20.2/geospatial/s2-cubed-sphere-3d.png b/images/v20.2/geospatial/s2-cubed-sphere-3d.png
diff --git a/images/v20.2/geospatial/s2-linestring-example-covering.png b/images/v20.2/geospatial/s2-linestring-example-covering.png
diff --git a/v20.2/create-index.md b/v20.2/create-index.md
@@ -122,6 +122,10 @@ The above example is equivalent to the following PostgreSQL-compatible syntax:
 > CREATE INDEX ON promo_codes USING GIN (rules);
 ~~~
 
+### Create spatial indexes
+
+For examples showing how to create spatial indexes, see [Spatial Indexes](spatial-indexes.html#examples).
+
 ### Store columns
 
 Storing a column improves the performance of queries that retrieve (but do not filter) its values.

diff --git a/v20.2/indexes.md b/v20.2/indexes.md
@@ -23,6 +23,8 @@ Each table automatically has an index created called `primary`, which indexes ei
 
 The `primary` index helps filter a table's primary key but doesn't help SQL find values in any other columns. However, you can use secondary indexes to improve the performance of queries using columns not in a table's primary key. You can create them:
 
+<a name="unique-secondary-indexes"></a>
+
 - At the same time as the table with the `INDEX` clause of [`CREATE TABLE`](create-table.html#create-a-table-with-secondary-and-inverted-indexes). In addition to explicitly defined indexes, CockroachDB automatically creates secondary indexes for columns with the [`UNIQUE` constraint](unique.html).
 - For existing tables with [`CREATE INDEX`](create-index.html).
 - By applying the `UNIQUE` constraint to columns with [`ALTER TABLE`](alter-table.html), which automatically creates an index of the constrained columns.
@@ -63,6 +65,12 @@ To create a hash-sharded index, set the `experimental_enable_hash_sharded_indexe
 Hash-sharded indexes cannot be [interleaved](interleave-in-parent.html).
 {{site.data.alerts.end}}
 
+## Spatial indexes
+
+{% include {{page.version.version}}/sql/spatial-support-new.md %}
+
+For more information about spatial indexes, see [Spatial Indexes](spatial-indexes.html).
+
 ## Best practices
 
 We recommend creating indexes for all of your common queries. To design the most useful indexes, look at each query's `WHERE` and `SELECT` clauses, and create indexes that:
@@ -145,6 +153,7 @@ However, if we store `col3` in the index, the index join is no longer necessary.
 ## See also
 
 - [Inverted Indexes](inverted-indexes.html)
+- [Spatial Indexes](spatial-indexes.html)
 - [SQL Performance Best Practices](performance-best-practices-overview.html)
 - [Select from a specific index](select-clause.html#select-from-a-specific-index)
 - [`CREATE INDEX`](create-index.html)

diff --git a/v20.2/install-cockroachdb-spatial.md b/v20.2/install-cockroachdb-spatial.md
@@ -6,7 +6,8 @@ toc: true
 
 <a name="linux"></a>
 <a name="mac"></a>
-<span class="version-tag">New in v20.2</span>: CockroachDB has special support for efficiently storing and querying spatial data.
+
+{% include {{page.version.version}}/sql/spatial-support-new.md %}
 
 This page has instructions for installing CockroachDB Spatial on Mac and Linux.
 
@@ -258,6 +259,11 @@ If you are having difficulties installing CockroachDB Spatial, please see our [S
 ## See also
 
 - [Working with Spatial Data](spatial-data.html)
+- [Migrate from Shapefiles](migrate-from-shapefiles.html)
+- [Migrate from GeoJSON](migrate-from-geojson.html)
+- [Migrate from GeoPackage](migrate-from-geopackage.html)
+- [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Spatial Features](spatial-features.html)
 - [Spatial & GIS Glossary of Terms](spatial-glossary.html)
 - [Geospatial functions](functions-and-operators.html#geospatial-functions)

diff --git a/v20.2/inverted-indexes.md b/v20.2/inverted-indexes.md
@@ -9,7 +9,8 @@ Inverted indexes store mappings from values within a container column (such as a
 CockroachDB stores the contents of the following data types in inverted indexes:
 
 - [JSONB](jsonb.html)
--  [Arrays](array.html)
+- [Arrays](array.html)
+- [Spatial data (`GEOMETRY` and `GEOGRAPHY` types)](spatial-indexes.html)
 
 {{site.data.alerts.callout_success}}For a hands-on demonstration of using an inverted index to improve query performance on a <code>JSONB</code> column, see the <a href="demo-json-support.html">JSON tutorial</a>.{{site.data.alerts.end}}
 

diff --git a/v20.2/migrate-from-geojson.md b/v20.2/migrate-from-geojson.md
@@ -81,10 +81,12 @@ IMPORT PGDUMP ('http://localhost:3000/tanks.sql');
 ## See also
 
 - [`IMPORT`][import]
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
 - [Working with Spatial Data](spatial-data.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Migration Overview](migration-overview.html)
 - [Migrate from MySQL][mysql]
 - [Migrate from Postgres][postgres]

diff --git a/v20.2/migrate-from-geopackage.md b/v20.2/migrate-from-geopackage.md
@@ -94,6 +94,9 @@ IMPORT PGDUMP ('http://localhost:3000/springs.sql');
 ## See also
 
 - [`IMPORT`][import]
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
+- [Working with Spatial Data](spatial-data.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migration Overview](migration-overview.html)

diff --git a/v20.2/migrate-from-openstreetmap.md b/v20.2/migrate-from-openstreetmap.md
@@ -122,7 +122,9 @@ Osm2pgsql took 2879s overall
 ## See also
 
 - [`IMPORT`][import]
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
 - [Working with Spatial Data](spatial-data.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Migrate from GeoPackages](migrate-from-geopackage.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)

diff --git a/v20.2/migrate-from-shapefiles.md b/v20.2/migrate-from-shapefiles.md
@@ -100,7 +100,9 @@ IMPORT PGDUMP ('http://localhost:3000/tornado-points.sql');
 ## See also
 
 - [`IMPORT`][import]
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
 - [Working with Spatial Data](spatial-data.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)

diff --git a/v20.2/spatial-data.md b/v20.2/spatial-data.md
@@ -4,7 +4,9 @@ summary: CockroachDB has special support for efficiently storing and querying sp
 toc: true
 ---
 
-<span class="version-tag">New in v20.2</span>: CockroachDB has special support for efficiently storing and querying spatial data. Supported spatial data types include:
+{% include {{page.version.version}}/sql/spatial-support-new.md %}
+
+Supported spatial data types include:
 
 - Geometric objects such as points, lines, paths, and polygons in 2-dimensional space. These are projected onto the flat surface of a plane and are represented in SQL by the `GEOMETRY` data type.
 
@@ -237,7 +239,7 @@ SELECT ST_AsText(geom) FROM tornadoes WHERE yr = 1999 AND st = 'OK' AND mo = 5 A
 
 We can see that almost half of all of the tornadoes in this outbreak began in Oklahoma.
 
-It might be interesting to draw these points on a map. The image below shows the points from the query above drawn as a simple polygon on a map of Oklahoma. The boxes around the polygon show the spatial index coverings for the polygon.
+It might be interesting to draw these points on a map. The image below shows the points from the query above drawn as a simple polygon on a map of Oklahoma. The boxes around the polygon show the [spatial index](spatial-indexes.html) coverings for the polygon.
 
 <img width="100%" src="{{ 'images/v20.2/geospatial/1999-oklahoma-tornado-outbreak-map.png' | relative_url }}" alt="1999 Oklahoma tornado outbreak map view">
 
@@ -286,7 +288,7 @@ cockroach sql --insecure --host=localhost --port=26257
 
 Just as CockroachDB strives for [Postgres compatibility](postgresql-compatibility.html), our spatial data support is designed to be as compatible as possible with the functionality provided by the [PostGIS](https://postgis.net) extension.
 
-However, we do not yet implement the full list of PostGIS built-in functions and operators. Also, our indexing works differently (see the [Performance](#performance) section below). For a list of the spatial functions we support, see [Geospatial functions](functions-and-operators.html#geospatial-functions).
+However, we do not yet implement the full list of PostGIS built-in functions and operators. Also, our [spatial indexing works differently](spatial-indexes.html) (see the [Performance](#performance) section below). For a list of the spatial functions we support, see [Geospatial functions](functions-and-operators.html#geospatial-functions).
 
 If your application needs support for functions that are not yet implemented, please check out [our meta-issue for built-in function support on GitHub](https://github.com/cockroachdb/cockroach/issues/49203), which describes how to find an issue for the built-in function(s) you need.
 
@@ -298,7 +300,7 @@ If you need help troubleshooting an issue with our spatial support, please get i
 
 ## Performance
 
-In order to avoid full table scans, make sure to add indexes to any columns that are accessed as part of a predicate in the [`WHERE`](select-clause.html#filter-on-a-single-condition) clause. For geospatial columns, the index will only be used if the column is accessed using an index-accelerated geospatial function from the list below (all of these functions work on `GEOMETRY` data types; a `*` means that a function also works on `GEOGRAPHY` data types):
+In order to avoid full table scans, make sure to add [indexes](spatial-indexes.html) to any columns that are accessed as part of a predicate in the [`WHERE`](select-clause.html#filter-on-a-single-condition) clause. For geospatial columns, the index will only be used if the column is accessed using an index-accelerated geospatial function from the list below (all of these functions work on `GEOMETRY` data types; a `*` means that a function also works on `GEOGRAPHY` data types):
 
 - `st_covers` (*)
 - `st_coveredby` (*)
@@ -317,25 +319,29 @@ To use a version of a function from the list above that will explicitly *not* us
 
 You can check which queries are using which indexes using the [`EXPLAIN`](explain.html) statement. For more information about general query tuning (including index usage), see [Make queries fast](make-queries-fast.html).
 
-The syntax for adding an index to a geometry column is:
+The syntax for adding an [index](spatial-indexes.html) to a geometry column is:
 
 {% include copy-clipboard.html %}
 ~~~ sql
 CREATE INDEX tornado_geom_idx ON tornadoes USING GIST (geom);
 ~~~
 
-This creates an inverted index on the `geom` column. For more information about how inverted indexes work, see [Inverted indexes](inverted-indexes.html).
+This creates a (spatial) [inverted index](inverted-indexes.html) on the `geom` column.
 
 Because CockroachDB is a scale-out, multi-node database, our spatial indexing strategy is based on a [space-filling curve](https://en.wikipedia.org/wiki/Space-filling_curve)/quad-tree design (also known as "divide the space"), rather than the [R-Tree](https://en.wikipedia.org/wiki/R-tree) data structure used by some other spatial databases (also known as "divide the objects"). Other databases that use a "divide the space" strategy include Microsoft SQL Server and MongoDB.
 
+For more detailed information about how CockroachDB's spatial indexes work, see [Spatial indexes](spatial-indexes.html).
+
 If you encounter behavior that you think is due to a performance issue, please get in touch using our [Support resources](support-resources.html).
 
 ## See also
 
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Spatial and GIS Glossary of Terms](spatial-glossary.html)
 - [Spatial functions](functions-and-operators.html#geospatial-functions)
 - [Troubleshooting overview](troubleshooting-overview.html)

diff --git a/v20.2/spatial-features.md b/v20.2/spatial-features.md
@@ -6,16 +6,22 @@ toc: true
 
 <span class="version-tag">New in v20.2</span>: CockroachDB supports efficiently storing and querying spatial data.
 
-{{site.data.alerts.callout_info}}
-This documentation is still being worked on for the 20.2 release. For now, see the getting started tutorial in [Working with Spatial Data](spatial-data.html).
-{{site.data.alerts.end}}
+See the links below for more information about how to use CockroachDB for spatial use cases.
 
-## See also
+## Getting Started
 
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
 - [Working with Spatial Data](spatial-data.html)
-- [Spatial and GIS Glossary of Terms](spatial-glossary.html)
-- [Spatial functions](functions-and-operators.html#geospatial-functions)
+
+## Migrating spatial data into CockroachDB
+
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
+
+## Reference
+
+- [Spatial indexes](spatial-indexes.html)
+- [Spatial and GIS Glossary of Terms](spatial-glossary.html)
+- [Spatial functions](functions-and-operators.html#geospatial-functions)
diff --git a/v20.2/spatial-glossary.md b/v20.2/spatial-glossary.md
@@ -26,6 +26,10 @@ This page is provided for reference purposes only. The inclusion of a term in th
 
 - _Cartographic projection_: A cartographic projection, or map projection, is the process used to represent 3-dimensional (or higher) data on a 2-dimensional surface. This is usually related to how we might display 3-dimensional shapes represented in a database by the [`GEOGRAPHY` data type](#geography) on the surface of a map, which is a flat plane. For more information, see the GIS Lounge article [What is a Map Projection?](https://www.gislounge.com/map-projection/) by Caitlin Dempsey.
 
+<a name="covering"></a>
+
+- _Covering_: The covering of a shape _A_ is a set of locations (in CockroachDB, [S2 cell IDs](#s2)) that comprise another shape _B_ such that no points of _A_ lie to the outside of _B_.
+
 <a name="geocoder"></a>
 
 - _Geocoder_: Takes an address or the name of a place, and returns latitude and longitude coordinates. For more information, see [the wikipedia article on Geocoding](https://en.wikipedia.org/wiki/Geocoding).
@@ -168,6 +172,10 @@ This page is provided for reference purposes only. The inclusion of a term in th
 
 - _TIGER_: The "Topographically Integrated Geographic Encoding and Referencing System" released by the [U.S. Census Bureau](https://www.census.gov/programs-surveys/geography/guidance/tiger-data-products-guide.html).
 
+<a name="s2"></a>
+
+- _S2_: The [S2 Geometry Library](http://s2geometry.io) is a C++ code library for doing spherical geometry.  It models a sphere using a [quadtree](https://en.wikipedia.org/wiki/Quadtree) "divide the space" approach, and is used by CockroachDB.
+
 ## Spatial objects
 
 This section has information about the representation of geometric and geographic "shapes" according to the [SQL/MM](#sql-mm) standard.
@@ -208,11 +216,12 @@ This section has information about the representation of geometric and geographi
 
 ## See also
 
+- [Spatial Features](spatial-features.html)
+- [Install CockroachDB Spatial](install-cockroachdb-spatial.html)
 - [Working with Spatial Data](spatial-data.html)
+- [Spatial indexes](spatial-indexes.html)
 - [Spatial functions](functions-and-operators.html#geospatial-functions)
-- [Spatial Features Overview](spatial-features.html)
 - [Migrate from Shapefiles](migrate-from-shapefiles.html)
 - [Migrate from GeoJSON](migrate-from-geojson.html)
 - [Migrate from GeoPackage](migrate-from-geopackage.html)
 - [Migrate from OpenStreetMap](migrate-from-openstreetmap.html)
-- [Spatial and GIS Glossary of Terms](spatial-glossary.html)