EVOLUTION-MANAGER

Edit File: drv_mongodb.html

<html>
<head>
<title>MongoDB</title>
</head>

<h1>MongoDB</h1>

(GDAL/OGR &gt;= 2.1.0)<p>

This driver can connect to the a MongoDB service.<p>
The driver supports read, creation, update and delete operations of documents/features
and collections/layers. The MongoDB database must exist before operating on it
with OGR.<p>

<h2>MongoDB vs OGR concepts</h2>

A MongoDB collection within a database is considered as a OGR layer. A MongoDB document is considered as a OGR feature.<p>

<h2>Dataset name syntax</h2>

There are two main possible syntaxes:
<ul>
<li>One using <a href="http://docs.mongodb.org/v2.6/reference/connection-string/">MongoDB URI</a>,
such as mongodb://[usr:pwd@]host1[:port1]...[,hostN[:portN]]][/[db][?options]]</a>
<li>On using just MongoDB: as the name and open options to specify host, port, user, password, database, etc...</li>
</ul>

The open options available are :
<ul>
<li><b>URI</b>=uri: <a href="http://docs.mongodb.org/v2.6/reference/connection-string/">Connection URI</a></li>
<li><b>HOST</b>=hostname: Server hostname. Default to localhost.</li>
<li><b>PORT</b>=port. Server port. Default to 27017.</li>
<li><b>DBNAME</b>=dbname. Database name. Should be specified when connecting to hosts with user authentication enabled.</li>
<li><b>AUTH_DBNAME</b>=dbname. Authentication database name, in case it is different from the database to work onto.</li>
<li><b>USER</b>=name. User name.</li>
<li><b>PASSWORD</b>=password. User password.</li>
<li><b>AUTH_JSON</b>=json_string. Authentication elements as JSon object. This is for advanced authentication.
The JSon fields to put in the dictionary are :
<ul>
<li>"mechanism": The string name of the sasl mechanism to use (MONGODB-CR, SCRAM-SHA-1 or DEFAULT).  Mandatory.</li>
<li>"user": The string name of the user to authenticate. Mandatory.</li>
<li>"db": The database target of the auth command, which identifies the location
of the credential information for the user.  May be "$external" if
credential information is stored outside of the mongo cluster.  Mandatory.</li>
<li>"pwd": The password data.</li>
<li>"digestPassword": Boolean, set to true if the "pwd" is undigested (default)</li>
<li>"pwd": The password data.</li>
<li>"serviceHostname": The GSSAPI hostname to use.  Defaults to the name of the remote host.</li>
</ul>
</li>
<li><b>SSL_PEM_KEY_FILE</b>=filename. SSL PEM certificate/key filename.</li>
<li><b>SSL_PEM_KEY_PASSWORD</b>=password. SSL PEM key password.</li>
<li><b>SSL_CA_FILE</b>=filename. SSL Certification Authority filename.</li>
<li><b>SSL_CRL_FILE</b>=filename. SSL Certification Revocation List filename.</li>
<li><b>SSL_ALLOW_INVALID_CERTIFICATES</b>=YES/NO. Whether to allow connections to servers with invalid certificates. Defaults to NO.</li>
<li><b>SSL_ALLOW_INVALID_HOSTNAMES</b>=YES/NO. Whether to allow connections to servers with non-matching hostnames. Defaults to NO.</li>
<li><b>FIPS_MODE</b>=YES/NO. Whether to activate FIPS 140-2 mode at startup. Defaults to NO.</li>
<li><b>BATCH_SIZE</b>=number. Number of features to retrieve per batch. For most queries, the first batch returns 101 documents or just enough documents to exceed 1 megabyte. Subsequent batch size is 4 megabytes.</li>
<li><b>FEATURE_COUNT_TO_ESTABLISH_FEATURE_DEFN</b>=number. Number of features to retrieve to establish feature definition. -1 = unlimited. Defaults to 100.</li>
<li><b>JSON_FIELD</b>=YES/NO. Whether to include a field called "_json" with the full document as JSON. Defaults to NO.</li>
<li><b>FLATTEN_NESTED_ATTRIBUTE</b>=YES/NO. Whether to recursively explore nested objects and produce flatten OGR attributes. Defaults to YES.</li>
<li><b>FID</b>=name. Field name, with integer values, to use as FID. Defaults to ogc_fid.</li>
<li><b>USE_OGR_METADATA</b>=YES/NO. Whether to use the _ogr_metadata collection to read layer metadata. Defaults to YES.</li>
<li><b>BULK_INSERT</b>=YES/NO. Whether to use bulk insert for feature creation. Defaults to YES.</li>
</ul>

Note: the SSL_* and FIPS_MODE options must be set to the same values when opening
multiple types MongoDB databases. This is a limitation of the Mongo C++ driver.<p>

<h2>Filtering</h2>

The driver will forward any spatial filter set with SetSpatialFilter() to the server when
a "2d" or "2dsphere" spatial index is available on the geometry field.<p>

However, in the current state, SQL attribute filters set with SetAttributeFilter()
are evaluated only on client-side. To enable server-side filtering, the string
passed to SetAttributeFilter() must be a JSon object in the
<a href="http://docs.mongodb.org/v2.6/reference/method/db.collection.find/">MongoDB filter syntax</a>.<p>

<h2>Paging</h2>

Features are retrieved from the server by chunks of 101 documents or just enough
documents to exceed 1 megabyte. Subsequent batch size is 4 megabytes. This can be
altered with the BATCH_SIZE open option.<p>

<h2>Schema</h2>

When reading a MongoDB collection, OGR must establish the schema of attribute and geometry
fields, since, contrary to MongoDB collections which are schema-less, OGR has a fixed schema concept.<p>

In the general case, OGR will read the first 100 documents (can be altered with
the FEATURE_COUNT_TO_ESTABLISH_FEATURE_DEFN open option) of the collection and build
the schema that best fit to the found fields and values.<p>

If the collection/layer has been previously created with OGR, a _ogr_metadata special
collection contains the OGR schema, in which case it will be directly used. It might
be possible to ignore the schema written in _ogr_metadata by setting the USE_OGR_METADATA=NO
open option.<p>

It is also possible to set the JSON_FIELD=YES open option so that a _json special
field is added to the OGR schema. When reading MongoDB documents as OGR features,
the full JSon version of the document will be stored in the _json field. This might
be useful in case of complex documents or with data types that do not translate well
in OGR data types. On creation/update of documents, if the _json field is present
and set, its content will be used directly (other fields will be ignored).<p>

<h2>Feature ID</h2>

MongoDB have a special _id field that contains the unique ID of the document. This
field is returned as an OGR field, but cannot be used as the OGR special FeatureID
field, which must be of integer type. By default, OGR will try to read a potential
'ogc_fid' field to set the OGR FeatureID. The name of this field to look up can
be set with the FID open option. If the field is not found, the FID returned by
OGR will be a sequential number starting at 1, but it is not guaranteed to be
stable at all.<p>

<h2>ExecuteSQL() interface</h2>

If specifying "MongoDB" as the dialect of ExecuteSQL(), a JSon string with a
serialized <a href="http://docs.mongodb.org/v2.6/reference/command/">MongoDB command</a>
can be passed. The result will be returned as a
JSon string in a single OGR feature.<p>

Standard SQL requests will be executed on client-side.<p>

<h2>Write support</h2>

Layer/collection creation and deletion is possible.<p>

Write support is only enabled when the datasource is opened in update mode.<p>

When inserting a new feature with CreateFeature(), and if the command is successful, OGR will fetch the
returned _id and use it for the SetFeature() operation.<p>

<h2>Layer creation options</h2>

The following layer creation options are supported:
<ul>
<li><b>OVERWRITE</b>=YES/NO. Whether to overwrite an existing collection with the layer name to be created. Defaults to NO.</li>
<li><b>GEOMETRY_NAME</b>=name. Name of geometry column. Defaults to 'geometry'.</li>
<li><b>SPATIAL_INDEX</b>=YES/NO. Whether to create a spatial index (2dsphere). Defaults to YES.</li>
<li><b>FID</b>=string. Field name, with integer values, to use as FID. Defaults to 'ogc_fid'</li>
<li><b>WRITE_OGR_METADATA</b>=YES/NO. Whether to create a description of layer fields in the _ogr_metadata collection. Defaults to YES.</li>
<li><b>DOT_AS_NESTED_FIELD</b>=YES/NO. Whether to consider dot character in field name as sub-document. Defaults to YES.</li>
<li><b>IGNORE_SOURCE_ID</b>=YES/NO. Whether to ignore _id field in features passed to CreateFeature(). Defaults to NO.</li>
</ul>

<h2>Examples</h2>

<li>
Listing the tables of a MongoDB database:
<pre>
ogrinfo -ro mongodb://user:password@ds047612.mongolab.com:47612/gdalautotest
</pre>
<p>

<li>
Filtering on a MongoDB field:
<pre>
ogrinfo -ro mongodb://user:password@ds047612.mongolab.com:47612/gdalautotest -where '{ "field": 5 }'
</pre>
<p>

<li>
Creating and populating a collection from a shapefile:
<pre>
ogr2ogr -update mongodb://user:password@ds047612.mongolab.com:47612/gdalautotest shapefile.shp
</pre>
<p>

<h2>Build instructions</h2>

GDAL/OGR must be built against the <a href="https://github.com/mongodb/mongo-cxx-driver">MongoDB C++ driver client library</a>,
in its "legacy" version (tested with 1.0.2), in order to the MongoDB driver to be compiled.<p>

You must first follow <a href="https://github.com/mongodb/mongo-cxx-driver/wiki/Download-and-Compile-the-Legacy-Driver">MongoDB C++ driver client build instructions</a>,
which require to have Boost libraries available.
<p>
Then:
<ul>
<li>
On Linux/Unix, run ./configure --with-mongocxx=/path/to/installation/root (if the
driver is already installed in /usr, this is not needed).
If the Boost libraries are not found in the system paths, the path to the directory
when the libraries are found can be specified --with-boost-lib-path=/path/to/boost/libs .
<p>
</li>
<li>
On Windows, uncomment and adapt the following in nmake.opt (or add in nmake.local):
<pre>
# Uncomment for MongoDB support
# This configuration is valid for a libmongoclient built as a DLL with:
# scons.bat --32 --dynamic-windows --sharedclient --prefix=c:\users\even\dev\mongo-client-install
#           --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

# Uncomment if plugin is preferred
#MONGODB_PLUGIN = YES

MONGODB_INC = c:/users/even/dev/mongo-client-install/include
# Boost library names must be edited to reflect the actual MSVC and Boost versions
BOOST_INC = c:/users/even/dev/boost_1_55_0_32bit
BOOST_LIB_PATH= c:\users\even\dev\boost_1_55_0_32bit\lib32-msvc-10.0
MONGODB_LIBS = c:/users/even/dev/mongo-client-install/lib/mongoclient.lib \
               $(BOOST_LIB_PATH)\libboost_thread-vc100-mt-1_55.lib \
               $(BOOST_LIB_PATH)\libboost_system-vc100-mt-1_55.lib \
               $(BOOST_LIB_PATH)\libboost_date_time-vc100-mt-1_55.lib \
               $(BOOST_LIB_PATH)\libboost_chrono-vc100-mt-1_55.lib
</pre>
</li>
</ul>

<ul>
<li> <a href="https://github.com/mongodb/mongo-cxx-driver">MongoDB C++ Driver</a><p>
<li> <a href="http://docs.mongodb.org/v2.6/reference/">MongoDB 2.6 Manual</a><p>
</ul>

</body>
</html>