SA14/Tests: Declare column expressions for _score as literal_column

With the original code, SA14 would croak like::

    sqlalchemy.exc.ArgumentError: Textual column expression '_score' should be
    explicitly declared with text('_score'), or use column('_score') for more
    specificity

However, when using the `sa.text` type, as suggested, older SQLAlchemy
versions will croak in this manner::

    sqlalchemy.exc.InvalidRequestError: SQL expression, column, or mapped entity expected - got '<sqlalchemy.sql.elements.TextClause object at 0x10c0f7460>'

The `sa.column` type also will not work, because it would get rendered
with quotes as `"_score"`.

> `literal_column()` is similar to `column()`, except that it is more
> often used as a “standalone” column expression that renders exactly
> as stated.
>
> -- https://docs.sqlalchemy.org/en/14/core/sqlelement.html#sqlalchemy.sql.expression.literal_column

::

    - SELECT characters.name AS characters_name, _score FROM characters WHERE match(characters.name, ?)
    + SELECT characters.name AS characters_name, "_score" FROM characters WHERE match(characters.name, ?)

Settling with the `sa.literal_column` type resolved any woes.

Author: amotl

CHANGES.txt

@@ -18,6 +18,40 @@ Unreleased
 
 - Add support for SQLAlchemy 1.4
 
+
+Breaking changes
+----------------
+
+Textual column expressions
+''''''''''''''''''''''''''
+
+On the update to SQLAlchemy 1.4, some test cases had to be adjusted in order
+to compensate for apparent additional strictness of SQLAlchemy on some details.
+
+Where it was ok to use a textual column expression in plain text beforehand,
+a `SQLAlchemy literal_column`_ type should be used now. Otherwise, for example
+when accessing `CrateDB system columns`_ like ``_score``, the engine might
+complain like::
+
+    sqlalchemy.exc.ArgumentError: Textual column expression '_score' should be
+    explicitly declared with text('_score'), or use column('_score') for more
+    specificity
+
+The changes to be made look like this::
+
+    old: session.query(Character.name, '_score')
+    new: session.query(Character.name, sa.literal_column('_score'))
+
+::
+
+    old: .order_by(sa.desc(sa.text('_score')))
+    new: .order_by(sa.desc(sa.literal_column('_score')))
+
+
+.. _SQLAlchemy literal_column: https://docs.sqlalchemy.org/en/14/core/sqlelement.html#sqlalchemy.sql.expression.literal_column
+.. _CrateDB system columns: https://crate.io/docs/crate/reference/en/4.8/general/ddl/system-columns.html
+
+
 2020/09/28 0.26.0
 =================
 

src/crate/client/doctests/sqlalchemy.txt

@@ -289,7 +289,7 @@ the other rows. The higher the score value, the more relevant the row.
 In most cases ``_score`` is not part of the SQLAlchemy Table definition,
 so it must be passed as a string::
 
-    >>> session.query(Character.name, '_score') \
+    >>> session.query(Character.name, sa.literal_column('_score')) \
     ...     .filter(match(Character.quote_ft, 'space')) \
     ...     .all()
     [('Tricia McMillan', ...)]
@@ -298,11 +298,10 @@ To search on multiple columns you have to pass a dictionary with columns
 and ``boost`` attached. ``boost`` is a factor that increases the
 relevance of a column in respect to the other columns::
 
-    >>> from sqlalchemy.sql import text
     >>> session.query(Character.name) \
     ...           .filter(match({Character.name_ft: 1.5, Character.quote_ft: 0.1},
     ...                         'Arthur')) \
-    ...     .order_by(sa.desc(text('_score'))) \
+    ...     .order_by(sa.desc(sa.literal_column('_score'))) \
     ...     .all()
     [('Arthur Dent',), ('Tricia McMillan',)]
 

src/crate/client/sqlalchemy/tests/match_test.py

@@ -109,7 +109,8 @@ def test_match_type_options(self):
         )
 
     def test_score(self):
-        query = self.session.query(self.Character.name, '_score') \
+        query = self.session.query(self.Character.name,
+                                   sa.literal_column('_score')) \
                     .filter(match(self.Character.name, 'Trillian'))
         self.assertSQL(
             "SELECT characters.name AS characters_name, _score " +