diff --git a/source/connect.txt b/source/connect.txt index 6c983b01..526a3aae 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -30,6 +30,7 @@ Connect to MongoDB Customize Server Selection Stable API Limit Server Execution Time + Compression Overview -------- diff --git a/source/connect/compression.txt b/source/connect/compression.txt new file mode 100644 index 00000000..55946c83 --- /dev/null +++ b/source/connect/compression.txt @@ -0,0 +1,89 @@ +.. _pymongo-compression: + +=========== +Compression +=========== + +.. facet:: + :name: genre + :values: reference + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +Overview +-------- + +In this guide, you can learn how to use compression algorithms with +{+driver-short+}. + +You can use compression to reduce the size of messages sent between your application +and a MongoDB deployment. {+driver-short+} supports the following compression algorithms: + +- `Snappy `__: You can use Snappy compression + with MongoDB 3.4 and later by including the `python-snappy `__ + package in your application. +- `Zlib `__: You can use Zlib compression with MongoDB 3.6 and later + by including the `zlib `__ package + in your application. +- `Zstandard `__: You can use Zstandard compression + with MongoDB 4.2 and later by including the `zstandard `__ + package in your application. + +Specifying Compression By Using a Connection String +--------------------------------------------------- + +You can specify the compression algorithm to use by including the ``compressors`` option +in your connection string. The following example specifies the Snappy compression algorithm + +.. code-block:: python + + client = pymongo.MongoClient("mongodb://localhost/?compressors=snappy") + +You can also specify multiple compression algorithms by separating them with a comma, as +show in the following example: + +.. code-block:: python + + client = pymongo.MongoClient("mongodb://localhost/?compressors=snappy,zlib,zstd") + +.. note:: + + When you supply multiple compression algorithms to a connection string, + {+driver-short+} uses the first compression algorithm in the list that the + deployment supports. + +Specifying Compression to a MongoClient +--------------------------------------- + +You can also specify the compression algorithm to use by passing the algorithms to use +to the ``compressors`` parameter of the ``MongoClient`` constructor, as shown in the +following example: + +.. code-block:: python + + client = pymongo.MongoClient(compressors="snappy") + +You can also specify multiple compression algorithms by passing a list of algorithms to the +``MongoClient`` constructor, as shown in the following example: + +.. code-block:: python + + client = pymongo.MongoClient(compressors=["snappy", "zlib", "zstd"]) + +.. note:: + + When you supply multiple compression algorithms to a ``MongoClient``, + {+driver-short+} uses the first compression algorithm in the list that the + deployment supports. + +API Documentation +----------------- + +To learn more about any of the methods or types discussed in this +guide, see the following API documentation: + +- `MongoClient <{+api-root+}pymongo/mongo_client.html#pymongo.mongo_client.MongoClient>`__ \ No newline at end of file