docs: add-warning-about-backslash-corruption-when-building-CQL-with-string-formatting

Author: howiezhao

docs/getting_started.rst

@@ -215,6 +215,56 @@ Althought it is not recommended, you can also pass parameters to non-prepared
 statements. The driver supports two forms of parameter place-holders: positional
 and named.
 
+.. warning::
+
+    Never use Python string formatting (f-strings, ``str.format()``, the ``%``
+    operator) to interpolate query results directly into CQL strings.
+    Collection types such as ``map``, ``list``, and ``set`` are returned by the
+    driver as Python objects (e.g. :class:`~cassandra.util.OrderedMapSerializedKey`).
+    Their ``__str__`` representation uses Python's ``repr()`` format for nested
+    string values, which escapes backslashes (``\`` -> ``\\``).  Embedding this
+    representation in a CQL string will corrupt data containing backslashes or
+    other special characters because CQL does not treat backslash as an escape
+    character.
+
+    For example, suppose a row contains ``data = 'https:\/\/example.com'``
+    (one backslash before each slash) and
+    ``map_data = {'url': 'https:\/\/example.com'}``:
+
+    .. code-block:: python
+
+        row = session.execute("SELECT * FROM t WHERE id = 'id1';").one()
+
+        # row.data is a plain Python str – str() prints it as-is:
+        print(row.data)
+        # -> https:\/\/example.com          (1 backslash – correct)
+
+        # row.map_data is an OrderedMapSerializedKey – str() uses repr()
+        # format for nested strings, which escapes every backslash:
+        print(row.map_data)
+        # -> {'url': 'https:\\/\\/example.com'}   (2 backslashes – wrong!)
+
+        # Embedding str(row.map_data) in a CQL string sends the doubled
+        # backslashes to Cassandra, corrupting the stored value:
+        session.execute(                                           # WRONG
+            f"UPDATE t SET data='{row.data}', "
+            f"map_data={row.map_data} WHERE id='{row.id}'"
+        )
+        # The CQL Cassandra receives:
+        # UPDATE t SET map_data={'url': 'https:\\/\\/example.com'} ...
+        # Cassandra stores 2 backslashes instead of 1 – data is corrupted.
+
+    Use a prepared statement instead, values are passed via the binary
+    protocol and are never converted to CQL string literals:
+
+    .. code-block:: python
+
+        stmt = session.prepare(
+            "UPDATE t SET data=?, map_data=? WHERE id=?"
+        )
+        session.execute(stmt, (row.data, row.map_data, row.id))
+        # Cassandra receives the raw bytes – backslashes are preserved exactly.
+
 Positional parameters are used with a ``%s`` placeholder.  For example,
 when you execute: