diff --git a/gpdb-doc/dita/analytics/postGIS.xml b/gpdb-doc/dita/analytics/postGIS.xml index 5b176755fc98ff6b885d34947bc0e4e5b43e3dee..df5ea8d7022efd3aad8642d0806fdb44050312f2 100644 --- a/gpdb-doc/dita/analytics/postGIS.xml +++ b/gpdb-doc/dita/analytics/postGIS.xml @@ -20,23 +20,20 @@
    • -
  • - -
    • About PostGIS

    PostGIS is a spatial database extension for PostgreSQL that allows GIS (Geographic - Information Systems) objects to be stored in the database. The Greenplum Database PostGIS - extension includes support for GiST-based R-Tree spatial indexes and functions for analysis - and processing of GIS objects.

    -

    The Greenplum Database PostGIS extension supports the optional PostGIS - raster data type and most PostGIS Raster functions. With the PostGIS - Raster objects, PostGIS geometry data type offers a single set of overlay - SQL functions (such as ST_Intersects) operating seamlessly on vector and - raster geospatial data. PostGIS Raster uses the GDAL (Geospatial Data Abstraction Library) + Information Systems) objects to be stored in the database. The Greenplum PostGIS extension + includes support for GiST-based R-Tree spatial indexes and functions for analysis and + processing of GIS objects.

    +

    The Greenplum PostGIS extension supports some PostGIS optional extensions and includes + support for the PostGIS raster data type. With the PostGIS Raster objects, + PostGIS geometry data type offers a single set of overlay SQL functions + (such as ST_Intersects) operating seamlessly on vector and raster + geospatial data. PostGIS Raster uses the GDAL (Geospatial Data Abstraction Library) translator library for raster geospatial data formats that presents a single raster abstract data model to a calling application.

    @@ -52,11 +49,11 @@ Greenplum PostGIS Extension -

    The Greenplum Database PostGIS extension package is available from - VMware Tanzu Network. You can install the package using the - Greenplum Package Manager (gppkg). For details, see gppkg - in the Greenplum Database Utility Guide.

    +

    The Greenplum PostGIS extension package is available from VMware Tanzu Network. You can install the package using the Greenplum + Package Manager (gppkg). For details, see gppkg in the + Greenplum Database Utility Guide.

    Greenplum Database supports the PostGIS extension with these component versions.

    -

    For the information about supported extension packages and software - versions, see the Greenplum Database Release Notes.

    +

    For the information about supported Greenplum extension packages and + software versions, see .

    There have been significant changes in PostGIS 2.5.4 compared with the previously supported version of 2.1.5. For a list of new and enhanced functions in PostGIS 2.5, see the PostGIS documentation For a comprehensive list of PostGIS changes in PostGIS 2.5.4 and earlier, see PostGIS 2.5 Appendix A Release 2.5.4.

    + If you installed Greenplum PostGIS 2.1.5, you cannot upgrade from PostGIS 2.1.5 to + 2.5.4. You must uninstall PostGIS 2.1.5 and install PostGIS 2.5.4. +

    This table lists the PostGIS extensions support by Greenplum PostGIS.

    + + Greenplum PostGIS Extensions + + + + + + PostGIS Extension + Greenplum PostGIS Notes + + + + + postgis

    PostGIS and PostGIS Raster + support

     + Supported. Both PostGIS and PostGIS Raster are enabled when the Greenplum + postgis extension is enabled. +     + + postgis_tiger_geocoder

    The US TIGER geocoder

     + Supported. Installed with Greenplum PostGIS.

    Requires the + postgis and fuzzystrmatch + extensions.

    The US TIGER geocoder converts addresses (like a street address) + to geographic coordinates.

     +     + + address_standardizer

    Rule-based address + standardizer

     + Supported. Installed but not enabled with Greenplum PostGIS.

    Can be used + with TIGER geocoder.

    A single line address parser that takes an input + address and normalizes it based on a set of rules stored in a table and helper + lex and gaz tables.

     +     + + address_standardizer_data_us

    Sample rules tables for US + address data

     + Supported. Installed but not enabled with Greenplum PostGIS.

    Can be used with + the address standardizer.

    The extension contains gaz, + lex, and rules tables for US address data. If + you are using other types of tables, see .

     +     + + fuzzystrmatch

    Fuzzy string matching

     + Supported. This extension is bundled but not enabled with Greenplum + Database.

    Required for the PostGIS TIGER geocoder.

     +     + + +
    + The PostGIS topology extension postgis_topology and the PostGIS 3D and + geoprocessing extension postgis_sfcgal are not supported by Greenplum + PostGIS and are not included in the Greenplum PostGIS extension package. +

    For information about the PostGIS extensions, see the PostGIS 2.5 + documentation.

    +

    For information about Greenplum PostGIS feature support, see .

    - - Greenplum Database PostGIS Limitations - -

    The Greenplum Database PostGIS extension does not support the following features:

    -
      -
    • Topology
      • -
    • A small number of user defined functions and aggregates
      • -
    • PostGIS long transaction support
      • -
    -

    For information about Greenplum Database PostGIS support, see .

    - -     Enabling and Removing PostGIS Support -

    The Greenplum Database PostGIS extension contains the postgis_manager.sh - script that installs or removes both the PostGIS and PostGIS Raster features in a database. - After the PostGIS extension package is installed, the script is in - $GPHOME/share/postgresql/contrib/postgis-2.5/. The - postgis_manager.sh script runs SQL scripts that install or remove PostGIS - and PostGIS Raster from a database.

    -

    For information about the PostGIS and PostGIS Raster SQL scripts, and required PostGIS - Raster environment variables, see .

    +

    This section describes how to enable and remove PostGIS and the supported PostGIS + extensions, and how to configure PostGIS Raster.

    Enabling PostGIS Support -

    Run the postgis_manager.sh script specifying the database, an optional - schema, and the install option to install PostGIS and PostGIS Raster. If - you do not specify a schema, the script installs PostGIS in the default - schema.postgis_manager.sh <dbname> [<schema_name>] install


    -

    This example installs PostGIS and PostGIS Raster objects in the database - mydatabase in the default - schema.postgis_manager.sh mydatabase install

    -

    The script runs all the PostGIS SQL scripts that enable PostGIS in a database: - install/postgis.sql, install/rtpostgis.sql - install/spatial_ref_sys.sql, - install/postgis_comments.sql, and - install/raster_comments.sql.

    -

    The postGIS package installation adds these lines to the - greenplum_path.sh file for PostGIS Raster support.

    - export GDAL_DATA=$GPHOME/share/gdal +

    To enable PostGIS support, install the Greenplum PostGIS extension package into the + Greenplum Database system, and then use the CREATE EXTENSION command to + enable PostGIS support for an individual database.

    +
    + Installing the Greenplum PostGIS Extension Package +

    Install Greenplum PostGIS extension package with the gppkg utility. + For example, this command installs the package for RHEL 7. + gppkg -i postgis-2.5.4+pivotal.2.build.1-gp6-rhel7-x86_64.gppkg

    +

    After installing the package, source the greenplum_path.sh file and + restart Greenplum Database. This command restarts Greenplum Database.

    + gpstop -ra +

    Installing the Greenplum PostGIS extension package updates the Greenplum + Database system, including installing the supported PostGIS extensions to the system and + updating greenplum_path.sh file with these lines for PostGIS Raster + support.

    + export GDAL_DATA=$GPHOME/share/gdal export POSTGIS_ENABLE_OUTDB_RASTERS=0 export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL +
    +
    + Using the CREATE EXTENSION Command +

    These steps enable the PostGIS extension and the extensions that are used + with PostGIS.

    +
      +
    1. To enable PostGIS and PostGIS Raster in a database, run this command after logging + into the database.CREATE EXTENSION postgis ;

      To + enable PostGIS and PostGIS Raster in a specific schema, create the schema, set the + search_path to the PostGIS schema, and then enable the + postgis extension with the WITH SCHEMA clause. +

      SHOW search_path ; -- display the current search_path +CREATE SCHEMA <schema_name> ; +SET search_path TO <schema_name> ; +CREATE EXTENSION postgis WITH SCHEMA <schema_name> ;

      After + enabling the extension, reset the search_path and include the + PostGIS schema in the search_path if needed.

      2. +
    2. If needed, enable the PostGIS TIGER geocoder after enabling the + postgis extension.

      To enable the PostGIS TIGER geocoder, you + must enable the fuzzystrmatch extension before enabling + postgis_tiger_geocoder. These two commands enable the + extensions.

      CREATE EXTENSION fuzzystrmatch ; +CREATE EXTENSION postgis_tiger_geocoder ;
      3. +
    3. If needed, enable the rules-based address standardizer and add rules tables for the + standardizer. These commands enable the + extensions.CREATE EXTENSION address_standardizer ; +CREATE EXTENSION address_standardizer_data_us ;
      4. +
    +
    @@ -181,22 +255,48 @@ export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL Removing PostGIS Support -

    Run the postgis_manager.sh script specifying the database, a schema name - (if necessary), and with the uninstall option to remove PostGIS and - PostGIS Raster. You specify the schema if you specified a schema when you installed - PostGIS.postgis_manager.sh <dbname> [<schema_name>] uninstall

    -

    This example removes PostGIS and PostGIS Raster support from the database - mydatabase that was installed in the default - schema.postgis_manager.sh mydatabase uninstall

    -

    The script runs both the PostGIS SQL scripts that remove PostGIS and PostGIS Raster from - a database: uninstall_rtpostgis.sql and - uninstall_postgis.sql.

    -

    The postgis_manager.sh script does not remove these PostGIS Raster - environment variables the greenplum_path.sh file: - GDAL_DATA, POSTGIS_ENABLE_OUTDB_RASTERS, +

    You use the DROP EXTENSION command to remove support for the + PostGIS extension and the extensions that are used with PostGIS.

    +

    Removing PostGIS support from a database does not remove these PostGIS Raster environment + variables from the greenplum_path.sh file: GDAL_DATA, + POSTGIS_ENABLE_OUTDB_RASTERS, POSTGIS_GDAL_ENABLED_DRIVERS. The environment variables are removed - when you uninstall the PostGIS extension package with the gppkg utility. -

    + when you uninstall the PostGIS extension package.

    +
    + Using the DROP EXTENSION Command +

    Depending on the extensions you enabled for PostGIS, drop support for the extensions in + the database.

    +
      +
    1. If you enabled the address standardizer and sample rules tables, these commands drop + support for those extensions from the current + database.DROP EXTENSION address_standardizer_data_us IF EXISTS; +DROP EXTENSION address_standardizer IF EXISTS ;
      2. +
    2. If you enabled the TIGER geocoder and the fuzzystrmatch extension + to use the TIGER geocoder, these commands drop support for those + extensions.DROP EXTENSION postgis_tiger_geocoder IF EXISTS ; +DROP EXTENSION fuzzystrmatch IF EXISTS ;
      3. +
    3. Drop support for PostGIS and PostGIS Raster. This command drops support for those + extensions.DROP EXTENSION postgis IF EXISTS ;

      If you + enabled support for PostGIS and specified a specific schema with the CREATE + EXTENSION command, you can update the search_path and + drop the PostGIS schema if required.

      4. +
    +
    +
    + Uninstalling the Greenplum PostGIS Extension Package +

    After PostGIS support has been removed from all databases in the Greenplum Database + system, you can remove the PostGIS extension package. For example, this + gppkg command removes the PostGIS extension package. + gppkg -r postgis-2.5.4+pivotal.2

    +

    After removing the package, ensure that these lines for PostGIS Raster + support are removed from the greenplum_path.sh file.

    + export GDAL_DATA=$GPHOME/share/gdal +export POSTGIS_ENABLE_OUTDB_RASTERS=0 +export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL +

    Source the greenplum_path.sh file and restart Greenplum Database. This + command restarts Greenplum Database.

    + gpstop -ra +
    @@ -207,24 +307,28 @@ export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL The following example SQL statements create non-OpenGIS tables and geometries.

    CREATE TABLE geom_test ( gid int4, geom geometry, -  name varchar(25) ); + name varchar(25) ); + INSERT INTO geom_test ( gid, geom, name ) -  VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square'); + VALUES ( 1, 'POLYGON((0 0 0,0 5 0,5 5 0,5 0 0,0 0 0))', '3D Square'); INSERT INTO geom_test ( gid, geom, name ) -  VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' ); + VALUES ( 2, 'LINESTRING(1 1 1,5 5 5,7 7 5)', '3D Line' ); INSERT INTO geom_test ( gid, geom, name ) -  VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' ); + VALUES ( 3, 'MULTIPOINT(3 4,8 9)', '2D Aggregate Point' ); + SELECT * from geom_test WHERE geom && -  Box3D(ST_GeomFromEWKT('LINESTRING(2 2 0, 3 3 0)')); + Box3D(ST_GeomFromEWKT('LINESTRING(2 2 0, 3 3 0)'));

    The following example SQL statements create a table and add a geometry column to the table with a SRID integer value that references an entry in the SPATIAL_REF_SYS table. The INSERT statements add two geopoints to the table.

    CREATE TABLE geotest (id INT4, name VARCHAR(32) ); SELECT AddGeometryColumn('geotest','geopoint', 4326,'POINT',2); + +INSERT INTO geotest (id, name, geopoint) + VALUES (1, 'Olympia', ST_GeometryFromText('POINT(-122.90 46.97)', 4326)); INSERT INTO geotest (id, name, geopoint) -  VALUES (1, 'Olympia', ST_GeometryFromText('POINT(-122.90 46.97)', 4326)); -INSERT INTO geotest (id, name, geopoint)| -  VALUES (2, 'Renton', ST_GeometryFromText('POINT(-122.22 47.50)', 4326)); + VALUES (2, 'Renton', ST_GeometryFromText('POINT(-122.22 47.50)', 4326)); + SELECT name,ST_AsText(geopoint) FROM geotest; @@ -263,16 +367,20 @@ SELECT name,ST_AsText(geopoint) FROM geotest; -

    The Greenplum Database PostGIS extension does not support the following features:

    -
      -
    • Topology
      • -
    • Some Raster Functions
      • +

      In general, the Greenplum PostGIS extension does not support the following features:

      +
        +
      • The PostGIS topology extension postgis_topology
        • +
      • The PostGIS 3D and geoprocessing extension postgis_sfcgal
        • +
      • A small number of user defined functions and aggregates
        • +
      • PostGIS long transactions
      +

      For the PostGIS extensions supported by Greenplum PostGIS, see .

      Supported PostGIS Data Types -

      Greenplum Database PostGIS extension supports these PostGIS data types:

      +

      Greenplum PostGIS extension supports these PostGIS data types:

      • box2d
      • box3d
        • @@ -287,7 +395,7 @@ SELECT name,ST_AsText(geopoint) FROM geotest; Supported PostGIS Raster Data Types -

        Greenplum Database PostGIS supports these PostGIS Raster data types.

        +

        Greenplum PostGIS supports these PostGIS Raster data types.

        • geomval
        • addbandarg
          • @@ -309,15 +417,14 @@ SELECT name,ST_AsText(geopoint) FROM geotest; Supported PostGIS Index -

          Greenplum Database PostGIS extension supports the GiST (Generalized Search Tree) - index.

          +

          Greenplum PostGIS extension supports the GiST (Generalized Search Tree) index.

           PostGIS Extension Limitations -

          This section lists the Greenplum Database PostGIS extension limitations for user-defined - functions (UDFs), data types, and aggregates.

          +

          This section lists the Greenplum PostGIS extension limitations for user-defined functions + (UDFs), data types, and aggregates.

          • Data types and functions related to PostGIS topology functionality, such as TopoGeometry, are not supported by Greenplum Database.
            • @@ -349,116 +456,22 @@ SELECT AddGeometryColumn('public', 'geometries', 'geom', 0, 'LINESTRING', 2);The <-> operator (geometry <-> geometry) returns the centroid/centroid distance for Greenplum Database 6. +
          • The following PostGIS functions are not currently supported because Greenplum PostGIS + is compiled with Geos 3.4.2:
              +
            • ST_Subdivide
              • +
            • ​ST_ClipByBox2D
              • +
            • ST_VoronoiLines
              • +
            • ST_VoronoiPolygons
              • +
            • +
          • The TIGER geocoder extension is supported. However, upgrading the TIGER geocoder + extension is not supported.
            • +
          • The standardize_address() function uses lex, + gaz or rules tables as parameters. If you are using + tables apart from us_lex, us_gaz or + us_rules, you should create them with the distribution policy + DISTRIBUTED REPLICATED to work for Greenplum.
          - - PostGIS Support Scripts - -

          After installing the PostGIS extension package, you enable PostGIS support for each - database that requires its use. To enable or remove PostGIS support in your database, you - can run SQL scripts that are supplied with the PostGIS package in - $GPHOME/share/postgresql/contrib/postgis-2.5/.

            -
            • -
            • -

          -

          Instead of running the scripts individually, you can use the - postgis_manager.sh script to run SQL scripts that enable or remove - PostGIS support. See .

          -

          You can run the PostGIS SQL scripts individually to enable or remove PostGIS support. For - example, these commands run the SQL scripts postgis.sql, - rtpostgis.sql, and spatial_ref_sys.sql in the database - mydatabase.

          - psql -d mydatabase -f - $GPHOME/share/postgresql/contrib/postgis-2.5/install/postgis.sql -psql -d mydatabase -f - $GPHOME/share/postgresql/contrib/postgis-2.5/install/rtpostgis.sql -psql -d mydatabase -f - $GPHOME/share/postgresql/contrib/postgis-2.5/install/spatial_ref_sys.sql -

          After running the scripts, the database is enabled with both PostGIS and PostGIS - Raster.

          - - - Scripts that Enable PostGIS and PostGIS Raster Support - -

          These scripts enable PostGIS, and the optional PostGIS Raster in a database.

            -
          • install/postgis.sql - Load the PostGIS objects and function - definitions.
            • -
          • install/rtpostgis.sql - Load the PostGIS raster - object and function definitions.
            • -

          - If you are installing PostGIS Raster, PostGIS objects must be installed before PostGIS - Raster. PostGIS Raster depends on PostGIS objects. Greenplum Database returns an error if - rtpostgis.sql is run before postgis.sql. -

          These SQL scripts add data and comments to a PostGIS enabled database.

            -
          • install/spatial_ref_sys.sql - Populate the - spatial_ref_sys table with a complete set of EPSG coordinate system - definition identifiers. With the definition identifiers you can perform - ST_Transform() operations on geometries. - If you have overridden standard entries and want to use those - overrides, do not load the spatial_ref_sys.sql file when creating - the new database.
            • -
          • install/postgis_comments.sql - Add comments to the PostGIS - functions.
            • -
          • install/raster_comments.sql - Add comments to the PostGIS Raster - functions.
            • -

          -

          You can view comments with the pslq meta-command \dd - function_name or from any tool that can show Greenplum - Database function comments.

          - - - PostGIS Raster Environment Variables - -

          The postGIS package installation adds these lines to the - greenplum_path.sh file for PostGIS Raster support.

          - export GDAL_DATA=$GPHOME/share/gdal -export POSTGIS_ENABLE_OUTDB_RASTERS=0 -export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL -

          GDAL_DATA specifies the location of GDAL utilities and support files - used by the GDAL library. For example, the directory contains EPSG support files such as - gcs.csv​ and pcs.csv (so called dictionaries, mostly - in ​CSV format). The GDAL library requires the support files to properly evaluate EPSG - codes.

          -

          POSTGIS_GDAL_ENABLED_DRIVERS sets the enabled GDAL drivers in the - PostGIS environment.

          -

          POSTGIS_ENABLE_OUTDB_RASTERS is a boolean configuration option to - enable access to out of database raster bands.

          - -           -           - - Scripts that Remove PostGIS and PostGIS Raster Support - -

          To remove PostGIS support from a database, run SQL scripts that are supplied with the - PostGIS extension package in - $GPHOME/share/postgresql/contrib/postgis-2.5/ -

          - If you installed PostGIS Raster, you must uninstall PostGIS Raster before you - uninstall the PostGIS objects. PostGIS Raster depends on PostGIS objects. Greenplum - Database returns an error if PostGIS objects are removed before PostGIS Raster. -

          These scripts remove PostGIS and PostGIS Raster objects from a database.

            -
          • uninstall/uninstall_rtpostgis.sql - Removes the PostGIS Raster - object and function definitions.
            • -
          • uninstall/uninstall_postgis.sql - Removes the PostGIS objects and - function definitions.
            • -

          -

          After PostGIS support has been removed from all databases in the Greenplum Database - system, you can remove the PostGIS extension package. For example this - gppkg command removes the PostGIS extension package. - gppkg -r postgis-2.5.4+pivotal.1

          -

          Restart Greenplum Database after removing the package.

          - gpstop -r -

          Ensure that these lines for PostGIS Raster support are removed from the - greenplum_path.sh file.

          - export GDAL_DATA=$GPHOME/share/gdal -export POSTGIS_ENABLE_OUTDB_RASTERS=0 -export POSTGIS_GDAL_ENABLED_DRIVERS=DISABLE_ALL - -           -           diff --git a/gpdb-doc/dita/install_guide/platform-requirements.xml b/gpdb-doc/dita/install_guide/platform-requirements.xml index 327f5b080f58fa6e6e3443f1bbd8ff5f0b1b667f..233e0a5c780680c5f509de4caa4b80bb80a200fe 100644 --- a/gpdb-doc/dita/install_guide/platform-requirements.xml +++ b/gpdb-doc/dita/install_guide/platform-requirements.xml @@ -378,9 +378,9 @@ R 3.4.4 - GreenplumR Beta - 1.0.0-beta + GreenplumR + 1.0.0 Supports R 3.6+. @@ -394,13 +394,13 @@ PostGIS Spatial and Geographic Objects - 2.5.4+pivotal.1,

          2.1.5+pivotal.2-2

           - + 2.5.4+pivotal.2, + 2.5.4+pivotal.1,

          2.1.5+pivotal.2-2

           +           -

          For information about the Oracle Compatibility Functions, see Oracle Compatibility Functions.