DOCSP-46690: Compression

source/connect.txt

@@ -30,6 +30,7 @@ Connect to MongoDB
    Customize Server Selection </connect/server-selection>
    Stable API </connect/stable-api>
    Limit Server Execution Time </connect/csot>
+   Compression </connect/compression>
 
 Overview
 --------

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 <https://google.github.io/snappy/>`__: You can use Snappy compression
+  with MongoDB 3.4 and later by including the `python-snappy <https://pypi.org/project/python-snappy/>`__
+  package in your application.
+- `Zlib <https://zlib.net/>`__: You can use Zlib compression with MongoDB 3.6 and later
+   by including the `zlib <https://docs.python.org/3/library/zlib.html>`__ package
+   in your application.
+- `Zstandard <https://github.com/facebook/zstd/>`__: You can use Zstandard compression
+  with MongoDB 4.2 and later by including the `zstandard <https://pypi.org/project/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>`__