Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 23 additions & 0 deletions docs/getting_started.rst
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,29 @@ 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::

**Avoid "Round-Tripping" data using string formatting.**

Never use f-strings or ``%`` to insert data — especially driver-returned collections (maps, sets, lists) — back into a CQL query.

**The Gotcha:** The driver's collection objects use Python's ``repr()`` formatting for nested values.
This automatically doubles backslashes (e.g., ``\`` becomes ``\\``).
Because CQL does not use backslashes as escape characters,
Cassandra will store those extra backslashes literally, **corrupting your data**.

**The Fix:** Always use **prepared statements**.
They transmit data in a binary format that bypasses Python's string serialization entirely.

.. code-block:: python

# BAD: f-strings cause double-escaping/corruption
session.execute(f"UPDATE t SET my_map={row.my_map} WHERE id=1")

# GOOD: Prepared statements preserve data exactly
stmt = session.prepare("UPDATE t SET my_map=? WHERE id=1")
session.execute(stmt, [row.my_map])

Positional parameters are used with a ``%s`` placeholder. For example,
when you execute:

Expand Down