1.. _vector.ngw: 2 3NGW -- NextGIS Web 4================== 5 6.. versionadded:: 2.4 7 8.. shortname:: NGW 9 10.. build_dependencies:: libcurl 11 12NextGIS Web - is a server GIS, which allows storing and editing geodata 13and to display maps in web browser. Also NextGIS Web can share geodata 14with other NextGIS software. 15 16NextGIS Web has the following features: 17 18- Display maps in a web browser (different maps with different layers 19 and styles) 20- Flexible permissions management 21- Load geodata from PostGIS or import from GIS formats (ESRI Shape, 22 GeoJSON or GeoTIFF) 23- Load vector geodata in the following formats: GeoJSON, CSV, ESRI 24 Shape, Mapinfo tab 25- Import map styles from QGIS project or set them manually 26- Act as a server for TMS, WMS, MVT, WFS 27- Act as a client for WMS 28- User can add photos to records, change record attributes via web 29 interface or WFS-T protocol 30 31NextGIS Web - is an open source software (license GPL v2+, see `GNU 32General Public License, version 332 <https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html>`__). 34 35Driver capabilities 36------------------- 37 38.. supports_georeferencing:: 39 40Driver 41------ 42 43The driver can connect to the services implementing the NextGIS Web REST API. 44NGW driver requires cURL support in GDAL. The driver supports read and write 45operations. 46 47Dataset name syntax 48------------------- 49 50The minimal syntax to open a NGW datasource is: NGW:[NextGIS Web 51URL][/resource/][resource identifier] 52 53- **NextGIS Web URL** may be an URL to nextgis.com cloud service (for 54 example, https://demo.nextgis.com), or some other URL including port 55 and additional path (for example, http://192.168.1.1:8000/test). 56- **resource** is mandatory keyword dividing resource identifier from 57 the rest of URL. 58- **resource identifier** this is positive number from 0 and above. 59 This may be a resource group, vector, PostGIS or raster layer, style. 60 61All vector layers, PostGIS, raster layers, styles will list as child resources 62if identifier is resource group. In other case this will be a separate layer. 63 64Configuration options 65--------------------- 66 67The following configuration options are available: 68 69- **NGW_USERPWD**: User name and password separated with colon. 70 Optional and can be set using open options. 71- **NGW_BATCH_SIZE**: Size of feature insert and update operations 72 cache before send to server. If batch size is -1 batch mode is 73 disabled. Delete operation will execute immediately. 74- **NGW_PAGE_SIZE**: If supported by server, fetch features from remote 75 server will use paging. The -1 value disables paging even it 76 supported by server. 77- **NGW_NATIVE_DATA**: Whether to store the json *extensions* key in 78 feature native data. 79- **NGW_JSON_DEPTH**: The depth of json response that can be parsed. If 80 depth is greater than this value, parse error occurs. 81- **NGW_EXTENSIONS**: Comma separated extensions list. Available values are 82 `description` and `attachment`. This needed to fill native data. 83 84Authentication 85-------------- 86 87Any operations (read, write, get metadata, change properties, etc.) may 88require an authenticated access. Authenticated access is obtained by 89specifying user name and password in open, create or configuration 90options. 91 92Feature 93------- 94 95If the NATIVE_DATA open option is set to YES, the *extensions* json 96object will store as a serialized json object in the NativeData 97property of the OGRFeature object (and "application/json" in the 98NativeMediaType property). If writing OGRFeature has NativeMediaType property 99set to "application/json" and its NativeData property set to serialized json 100object the new NGW feature *extensions* json object will fill from this json 101object. 102 103Extensions json object structure see in `NextGIS Web API 104documentation <http://docs.nextgis.comu/docs_ngweb_dev/doc/developer/resource.html#feature>`__ 105 106Geometry 107-------- 108 109NextGIS Web supports only one geometry column. Default spatial reference 110is Web Mercator (EPSG:3857). The following geometry types are available: 111 112- POINT 113- LINESTRING 114- POLYGON 115- MULTIPOINT 116- MULTILINESTRING 117- MULTIPOLYGON 118 119Geometry with Z value also supported. 120 121Field data types 122---------------- 123 124NextWeb supports only following field types: 125 126- OFTInteger 127- OFTInteger64 128- OFTReal 129- OFTString 130- OFTDate 131- OFTTime 132- OFTDateTime 133 134Paging 135------ 136 137Features can retrieved from NextGIS Web by chunks if supported by server 138(available since NextGIS Web 3.1). The chunk size can be altered with 139the NGW_PAGE_SIZE configuration option or PAGE_SIZE open option. 140 141Write support 142------------- 143 144Datasource and layers creation and deletion is possible. Write support 145is only enabled when the datasource is opened in update mode and user 146has appropriate permissions. Vector and PostGIS layers insert and update operations 147are cached if BATCH_SIZE is greater 0. Delete operation executes 148immediately. 149 150Open options 151------------ 152 153The following open options are available: 154 155- USERPWD - Username and password, separated by colon. 156- PAGE_SIZE=-1 - Limit feature count while fetching from server. 157 Default value is -1 - no limit. 158- BATCH_SIZE=-1 - Size of feature insert and update operations cache 159 before send to server. If batch size is -1 batch mode is disabled. 160 Default value is -1. 161- NATIVE_DATA=NO - Whether to store the json *extensions* key in 162 feature native data. Default value is NO. 163- JSON_DEPTH=32 - The depth of json response that can be parsed. If 164 depth is greater than this value, parse error occurs. 165- EXTENSIONS - Comma separated extensions list. Available values are 166 `description` and `attachment`. This needed to fill native data. 167 168Dataset creation options 169------------------------ 170 171The following dataset/datasource creation options are available: 172 173- KEY - Key value. Must be unique in whole NextGIS Web instance. 174 Optional. 175- DESCRIPTION - Resource description. Optional. 176- USERPWD - Username and password, separated by colon. 177- PAGE_SIZE=-1 - Limit feature count while fetching from server. 178 Default value is -1 - no limit. 179- BATCH_SIZE=-1 - Size of feature insert and update operations cache 180 before send to server. If batch size is -1 batch mode is disable. 181 Default value is -1. 182- NATIVE_DATA=NO - Whether to store the json *extensions* key in 183 feature native data. Default value is NO. 184- JSON_DEPTH=32 - The depth of json response that can be parsed. If 185 depth is greater than this value, parse error occurs. 186- EXTENSIONS - Comma separated extensions list. Available values are 187 `description` and `attachment`. This needed to fill native data. 188 189Layer creation options 190---------------------- 191 192The following layer creation options are available: 193 194- OVERWRITE - Whether to overwrite an existing table with the layer 195 name to be created. The resource will delete and new one will 196 created. This leads that resource identifier will change. Defaults to 197 NO. Optional. 198- KEY - Key value. Must be unique in whole NextGIS Web instance. 199 Optional. 200- DESCRIPTION - Resource description. Optional. 201 202Metadata 203-------- 204 205NextGIS Web metadata are supported in datasource, vector, PostGIS, 206raster layers and styles. Metadata are stored at specific domain "NGW". 207NextGIS Web supported metadata are strings and numbers. Metadata keys 208with decimal numbers will have suffix **.d** and for real numbers - 209**.f**. To create new metadata item, add new key=value pair in NGW 210domain using the *SetMetadataItem* function and appropriate suffix. During 211transferring to NextGIS Web, suffix will be omitted. You must ensure 212that numbers correctly transform from string to number. 213 214Resource description and key map to appropriate *description* and 215*keyname* metadata items in default domain. Changing those metadata 216items will cause an update of resource properties. 217 218Resource creation date, type and parent identifier map to appropriate 219read-only metadata items *creation_date*, *resource_type* and 220*parent_id* in default domain. 221 222Vector layer field properties (alias, identifier, label field, grid 223visibility) map to layer metadata the following way: 224 225- field alias -> FIELD_{field number}_ALIAS (for example FIELD_0_ALIAS) 226- identifier -> FIELD_{field number}_ID (for example FIELD_0_ID) 227- label field -> FIELD_{field number}_LABEL_FIELD (for example 228 FIELD_0_LABEL_FIELD) 229- grid visibility -> FIELD_{field number}_GRID_VISIBILITY (for example 230 FIELD_0_GRID_VISIBILITY) 231 232Starting from GDAL 3.3 field alias can be set/get via `SetAlternativeName` 233and `GetAlternativeNameRef`. 234 235Filters 236------- 237 238Vector and PostGIS layers support SetIgnoredFields method. When this method 239executes any cached features will be freed. 240 241Vector and PostGIS layers support SetAttributeFilter and 242SetSpatialFilter methods. The attribute filter will evaluate at server side 243if condition is one of following comparison operators: 244 245 - greater (>) 246 - lower (<) 247 - greater or equal (>=) 248 - lower or equal (<=) 249 - equal (=) 250 - not equal (!=) 251 - LIKE SQL statement (for strings compare) 252 - ILIKE SQL statement (for strings compare) 253 254Also only AND operator without brackets supported between comparison. For example, 255 256:: 257 258 FIELD_1 = 'Value 1' 259 260:: 261 262 FIELD_1 = 'Value 1' AND FIELD_2 > Value 2 263 264In other cases attribute filter will evaluate on client side. 265 266You can set attribute filter using NextGIS Web native format. For 267example, 268 269:: 270 271 NGW:fld_FIELD_1=Value 1&fld_FIELD_2__gt=Value 2 272 273Don't forget to add 'NGW:' perefix to where clause and 'fld\_' prefix to 274field name. 275 276Dataset supports ExecuteSQL method. Only the following queries are 277supported: 278 279- DELLAYER: layer_name; - delete layer with layer_name. 280- DELETE FROM layer_name; - delete any features from layer with 281 layer_name. 282- DROP TABLE layer_name; - delete layer with layer_name. 283- ALTER TABLE src_layer RENAME TO dst_layer; - rename layer. 284- SELECT field_1,field_2 FROM src_layer WHERE field_1 = 'Value 1' AND 285 field_2 = 'Value 2'; 286 287In SELECT statement field list or asterisk can be provided. The WHERE 288clause has same limitations as SetAttributeFilter method input. 289 290Examples 291-------- 292 293Read datasource contents (1730 is resource group identifier): 294 295:: 296 297 ogrinfo -ro NGW:https://demo.nextgis.com/resource/1730 298 299Read layer details (`1730` is resource group identifier, `Parks` is vecror layer 300name): 301 302:: 303 304 ogrinfo -ro -so NGW:https://demo.nextgis.com/resource/1730 Parks 305 306Creating and populating a vector layer from a shapefile in existing resource 307group with identifier 1730. New vector layer name will be "some new name": 308 309:: 310 311 ogr2ogr -f NGW -nln "some new name" -update -doo "BATCH_SIZE=100" -t_srs EPSG:3857 "NGW:https://demo.nextgis.com/resource/1730" myshapefile.shp 312 313.. warning:: 314 The `-update` key is mandatory, otherwise the destination datasource will 315 silently delete. The `-t_srs EPSG:3857` key is mandatory because vector 316 layers spatial reference in NextGIS Web can be only in EPSG:3857. 317 318.. note:: 319 The `-doo "BATCH_SIZE=100"` key is recommended for speed up feature transferring. 320 321Creating and populating a vector layer from a shapefile in new resource 322group with name "new group" and parent identifier 1730. New vector layer name 323will be "some new name": 324 325:: 326 327 ogr2ogr -f NGW -nln "Название на русском языке" -dsco "BATCH_SIZE=100" -t_srs EPSG:3857 "NGW:https://demo.nextgis.com/resource/1730/new group" myshapefile.shp 328 329See also 330-------- 331 332- :ref:`Raster side of the driver <raster.ngw>` 333- `NextGIS Web 334 documentation <http://docs.nextgis.com/docs_ngweb/source/toc.html>`__ 335- `NextGIS Web for 336 developers <http://docs.nextgis.com/docs_ngweb_dev/doc/toc.html>`__ 337