1.. _vector.mongodb: 2 3MongoDB 4======= 5 6.. versionadded:: 2.1 7 8.. shortname:: MongoDB 9 10.. build_dependencies:: Mongo C++ client legacy library 11 12This driver can connect to the a MongoDB service. 13 14The driver supports read, creation, update and delete operations of 15documents/features and collections/layers. The MongoDB database must 16exist before operating on it with OGR. 17 18This driver uses the legacy MongoDB C++ driver client library. To 19connect to MongoDB 3.0 or later servers, starting with GDAL 3.0, use the 20new :ref:`MongoDBv3 <vector.mongodbv3>` driver which uses the MongoDB C++ 21v3.4.0 client library. This driver will be eventually in favor of 22MongoDBv3 23 24Driver capabilities 25------------------- 26 27.. supports_create:: 28 29.. supports_georeferencing:: 30 31.. supports_virtualio:: 32 33MongoDB vs OGR concepts 34----------------------- 35 36A MongoDB collection within a database is considered as a OGR layer. A 37MongoDB document is considered as a OGR feature. 38 39Dataset name syntax 40------------------- 41 42There are two main possible syntaxes: 43 44- One using `MongoDB 45 URI <http://docs.mongodb.org/v2.6/reference/connection-string/>`__, 46 such as 47 mongodb://[usr:pwd@]host1[:port1]...[,hostN[:portN]]][/[db][?options]] 48- One using just MongoDB: as the name and open options to specify host, 49 port, user, password, database, etc... 50 51The open options available are : 52 53- **URI**\ =uri: `Connection 54 URI <http://docs.mongodb.org/v2.6/reference/connection-string/>`__ 55- **HOST**\ =hostname: Server hostname. Default to localhost. 56- **PORT**\ =port. Server port. Default to 27017. 57- **DBNAME**\ =dbname. Database name. Should be specified when 58 connecting to hosts with user authentication enabled. 59- **AUTH_DBNAME**\ =dbname. Authentication database name, in case it is 60 different from the database to work onto. 61- **USER**\ =name. User name. 62- **PASSWORD**\ =password. User password. 63- **AUTH_JSON**\ =json_string. Authentication elements as JSon object. 64 This is for advanced authentication. The JSon fields to put in the 65 dictionary are : 66 67 - "mechanism": The string name of the sasl mechanism to use 68 (MONGODB-CR, SCRAM-SHA-1 or DEFAULT). Mandatory. 69 - "user": The string name of the user to authenticate. Mandatory. 70 - "db": The database target of the auth command, which identifies 71 the location of the credential information for the user. May be 72 "$external" if credential information is stored outside of the 73 mongo cluster. Mandatory. 74 - "pwd": The password data. 75 - "digestPassword": Boolean, set to true if the "pwd" is undigested 76 (default) 77 - "pwd": The password data. 78 - "serviceHostname": The GSSAPI hostname to use. Defaults to the 79 name of the remote host. 80 81- **SSL_PEM_KEY_FILE**\ =filename. SSL PEM certificate/key filename. 82- **SSL_PEM_KEY_PASSWORD**\ =password. SSL PEM key password. 83- **SSL_CA_FILE**\ =filename. SSL Certification Authority filename. 84- **SSL_CRL_FILE**\ =filename. SSL Certification Revocation List 85 filename. 86- **SSL_ALLOW_INVALID_CERTIFICATES**\ =YES/NO. Whether to allow 87 connections to servers with invalid certificates. Defaults to NO. 88- **SSL_ALLOW_INVALID_HOSTNAMES**\ =YES/NO. Whether to allow 89 connections to servers with non-matching hostnames. Defaults to NO. 90- **FIPS_MODE**\ =YES/NO. Whether to activate FIPS 140-2 mode at 91 startup. Defaults to NO. 92- **BATCH_SIZE**\ =number. Number of features to retrieve per batch. 93 For most queries, the first batch returns 101 documents or just 94 enough documents to exceed 1 megabyte. Subsequent batch size is 4 95 megabytes. 96- **FEATURE_COUNT_TO_ESTABLISH_FEATURE_DEFN**\ =number. Number of 97 features to retrieve to establish feature definition. -1 = unlimited. 98 Defaults to 100. 99- **JSON_FIELD**\ =YES/NO. Whether to include a field called "_json" 100 with the full document as JSON. Defaults to NO. 101- **FLATTEN_NESTED_ATTRIBUTE**\ =YES/NO. Whether to recursively explore 102 nested objects and produce flatten OGR attributes. Defaults to YES. 103- **FID**\ =name. Field name, with integer values, to use as FID. 104 Defaults to ogc_fid. 105- **USE_OGR_METADATA**\ =YES/NO. Whether to use the \_ogr_metadata 106 collection to read layer metadata. Defaults to YES. 107- **BULK_INSERT**\ =YES/NO. Whether to use bulk insert for feature 108 creation. Defaults to YES. 109 110Note: the SSL\_\* and FIPS_MODE options must be set to the same values 111when opening multiple types MongoDB databases. This is a limitation of 112the Mongo C++ driver. 113 114Filtering 115--------- 116 117The driver will forward any spatial filter set with SetSpatialFilter() 118to the server when a "2d" or "2dsphere" spatial index is available on 119the geometry field. 120 121However, in the current state, SQL attribute filters set with 122SetAttributeFilter() are evaluated only on client-side. To enable 123server-side filtering, the string passed to SetAttributeFilter() must be 124a JSon object in the `MongoDB filter 125syntax <http://docs.mongodb.org/v2.6/reference/method/db.collection.find/>`__. 126 127Paging 128------ 129 130Features are retrieved from the server by chunks of 101 documents or 131just enough documents to exceed 1 megabyte. Subsequent batch size is 4 132megabytes. This can be altered with the BATCH_SIZE open option. 133 134Schema 135------ 136 137When reading a MongoDB collection, OGR must establish the schema of 138attribute and geometry fields, since, contrary to MongoDB collections 139which are schema-less, OGR has a fixed schema concept. 140 141In the general case, OGR will read the first 100 documents (can be 142altered with the FEATURE_COUNT_TO_ESTABLISH_FEATURE_DEFN open option) of 143the collection and build the schema that best fit to the found fields 144and values. 145 146If the collection/layer has been previously created with OGR, a 147\_ogr_metadata special collection contains the OGR schema, in which case 148it will be directly used. It might be possible to ignore the schema 149written in \_ogr_metadata by setting the USE_OGR_METADATA=NO open 150option. 151 152It is also possible to set the JSON_FIELD=YES open option so that a 153\_json special field is added to the OGR schema. When reading MongoDB 154documents as OGR features, the full JSon version of the document will be 155stored in the \_json field. This might be useful in case of complex 156documents or with data types that do not translate well in OGR data 157types. On creation/update of documents, if the \_json field is present 158and set, its content will be used directly (other fields will be 159ignored). 160 161Feature ID 162---------- 163 164MongoDB have a special \_id field that contains the unique ID of the 165document. This field is returned as an OGR field, but cannot be used as 166the OGR special FeatureID field, which must be of integer type. By 167default, OGR will try to read a potential 'ogc_fid' field to set the OGR 168FeatureID. The name of this field to look up can be set with the FID 169open option. If the field is not found, the FID returned by OGR will be 170a sequential number starting at 1, but it is not guaranteed to be stable 171at all. 172 173ExecuteSQL() interface 174---------------------- 175 176If specifying "MongoDB" as the dialect of ExecuteSQL(), a JSon string 177with a serialized `MongoDB 178command <http://docs.mongodb.org/v2.6/reference/command/>`__ can be 179passed. The result will be returned as a JSon string in a single OGR 180feature. 181 182Standard SQL requests will be executed on client-side. 183 184Write support 185------------- 186 187Layer/collection creation and deletion is possible. 188 189Write support is only enabled when the datasource is opened in update 190mode. 191 192When inserting a new feature with CreateFeature(), and if the command is 193successful, OGR will fetch the returned \_id and use it for the 194SetFeature() operation. 195 196Layer creation options 197---------------------- 198 199The following layer creation options are supported: 200 201- **OVERWRITE**\ =YES/NO. Whether to overwrite an existing collection 202 with the layer name to be created. Defaults to NO. 203- **GEOMETRY_NAME**\ =name. Name of geometry column. Defaults to 204 'geometry'. 205- **SPATIAL_INDEX**\ =YES/NO. Whether to create a spatial index 206 (2dsphere). Defaults to YES. 207- **FID**\ =string. Field name, with integer values, to use as FID. 208 Defaults to 'ogc_fid' 209- **WRITE_OGR_METADATA**\ =YES/NO. Whether to create a description of 210 layer fields in the \_ogr_metadata collection. Defaults to YES. 211- **DOT_AS_NESTED_FIELD**\ =YES/NO. Whether to consider dot character 212 in field name as sub-document. Defaults to YES. 213- **IGNORE_SOURCE_ID**\ =YES/NO. Whether to ignore \_id field in 214 features passed to CreateFeature(). Defaults to NO. 215 216Examples 217-------- 218 219Listing the tables of a MongoDB database: 220 221:: 222 223 ogrinfo -ro mongodb://user:password@ds047612.mongolab.com:47612/gdalautotest 224 225Filtering on a MongoDB field: 226 227:: 228 229 ogrinfo -ro mongodb://user:password@ds047612.mongolab.com:47612/gdalautotest -where '{ "field": 5 }' 230 231Creating and populating a collection from a shapefile: 232 233:: 234 235 ogr2ogr -update mongodb://user:password@ds047612.mongolab.com:47612/gdalautotest shapefile.shp 236 237Build instructions 238------------------ 239 240GDAL/OGR must be built against the `MongoDB C++ driver client 241library <https://github.com/mongodb/mongo-cxx-driver>`__, in its 242"legacy" version (tested with 1.0.2), in order to the MongoDB driver to 243be compiled. 244 245You must first follow `MongoDB C++ driver client build 246instructions <https://github.com/mongodb/mongo-cxx-driver/wiki/Download-and-Compile-the-Legacy-Driver>`__, 247which require to have Boost libraries available. 248 249Then: 250 251- On Linux/Unix, run ./configure 252 --with-mongocxx=/path/to/installation/root (if the driver is already 253 installed in /usr, this is not needed). If the Boost libraries are 254 not found in the system paths, the path to the directory when the 255 libraries are found can be specified 256 --with-boost-lib-path=/path/to/boost/libs . 257- On Windows, uncomment and adapt the following in nmake.opt (or add in 258 nmake.local): 259 260 :: 261 262 # Uncomment for MongoDB support 263 # This configuration is valid for a libmongoclient built as a DLL with: 264 # scons.bat --32 --dynamic-windows --sharedclient --prefix=c:\users\even\dev\mongo-client-install 265 # --cpppath=c:\users\even\dev\boost_1_55_0_32bit --libpath=c:\users\even\dev\boost_1_55_0_32bit\lib32-msvc-10.0 install 266 267 # Uncomment if plugin is preferred 268 #MONGODB_PLUGIN = YES 269 270 MONGODB_INC = c:/users/even/dev/mongo-client-install/include 271 # Boost library names must be edited to reflect the actual MSVC and Boost versions 272 BOOST_INC = c:/users/even/dev/boost_1_55_0_32bit 273 BOOST_LIB_PATH= c:\users\even\dev\boost_1_55_0_32bit\lib32-msvc-10.0 274 MONGODB_LIBS = c:/users/even/dev/mongo-client-install/lib/mongoclient.lib \ 275 $(BOOST_LIB_PATH)\libboost_thread-vc100-mt-1_55.lib \ 276 $(BOOST_LIB_PATH)\libboost_system-vc100-mt-1_55.lib \ 277 $(BOOST_LIB_PATH)\libboost_date_time-vc100-mt-1_55.lib \ 278 $(BOOST_LIB_PATH)\libboost_chrono-vc100-mt-1_55.lib 279 280See Also 281-------- 282 283- `MongoDB C++ Driver <https://github.com/mongodb/mongo-cxx-driver>`__ 284- `MongoDB 2.6 Manual <http://docs.mongodb.org/v2.6/reference/>`__ 285