From 654d01e5f3ef1eb3e71fd9a9c1beb1a3b6f2f117 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Thu, 8 Apr 2021 10:14:44 -0400 Subject: [PATCH] FAQ for render_postcompile Change-Id: If0231623491d7901046c76af3461f33ba504ff53 References: #6230 --- doc/build/faq/sqlexpressions.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/build/faq/sqlexpressions.rst b/doc/build/faq/sqlexpressions.rst index 31757f5471..93653a10ce 100644 --- a/doc/build/faq/sqlexpressions.rst +++ b/doc/build/faq/sqlexpressions.rst @@ -136,6 +136,37 @@ producing output like:: WHERE mytable.x > my_fancy_formatting(5) + +Rendering "POSTCOMPILE" Parameters as Bound Parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +SQLAlchemy includes a variant on a bound parameter known as +:paramref:`_sql.BindParameter.expanding`, which is a "late evaluated" parameter +that is rendered in an intermediary state when a SQL construct is compiled, +which is then further processed at statement execution time when the actual +known values are passed. "Expanding" parameters are used for +:meth:`_sql.ColumnOperators.in_` expressions by default so that the SQL +string can be safely cached independently of the actual lists of values +being passed to a particular invocation of :meth:`_sql.ColumnOperators.in_`:: + + >>> from sqlalchemy import column + >>> expr = column('x').in_([1, 2, 3]) + >>> print(expr) + x IN ([POSTCOMPILE_x_1]) + +To render the IN clause with real bound parameter symbols, use the +``render_postcompile=True`` flag with :meth:`_sql.ClauseElement.compile`:: + + >>> print(expr.compile(compile_kwargs={"render_postcompile": True})) + x IN (:x_1_1, :x_1_2, :x_1_3) + +As described in the previous section, the ``literal_binds`` flag works here +by automatically setting ``render_postcompile`` to True:: + + >>> print(expr.compile(compile_kwargs={"literal_binds": True})) + x IN (1, 2, 3) + + .. _faq_sql_expression_percent_signs: Why are percent signs being doubled up when stringifying SQL statements? -- 2.47.2