dstandish commented on code in PR #27966:
URL: https://github.com/apache/airflow/pull/27966#discussion_r1033910357
##########
airflow/providers/common/sql/hooks/sql.py:
##########
@@ -272,33 +273,33 @@ def run(
where each element in the list are results of one of the queries
(typically list of list of rows :D)
For compatibility reasons, the behaviour of the DBAPIHook is somewhat
confusing.
- In cases, when multiple queries are run, the return values will be an
iterable (list) of results
- - one for each query. However, in certain cases, when single query is
run - the results will be just
- the results of that query without wrapping the results in a list.
+ In some cases, when multiple queries are run, the return value will be
an iterable (list) of results
+ -- one for each query. However, in other cases, when single query is
run, the return value will be just
+ the result of that single query without wrapping the results in a list.
- The cases when single query results are returned without wrapping them
in a list are when:
+ The cases when single query results are returned without wrapping them
in a list are as follows:
- a) sql is string and last_statement is True (regardless what
split_statement value is)
- b) sql is string and split_statement is False
+ a) sql is string and ``return_last`` is True (regardless what
``split_statements`` value is)
+ b) sql is string and ``split_statements`` is False
- In all other cases, the results are wrapped in a list, even if there
is only one statement to process:
+ In all other cases, the results are wrapped in a list, even if there
is only one statement to process.
+ In particular, the return value will be a list of query results in the
following circumstances:
- a) always when sql is an iterable of string statements (regardless
what last_statement value is)
- b) when sql is string, split_statement is True and last_statement is
False
+ a) when ``sql`` is an iterable of string statements (regardless what
``return_last`` value is)
+ b) when ``sql`` is string, ``split_statements`` is True and
``return_last`` is False
+ After ``run`` is called, you may access the following properties on
the hook object:
- In any of those cases, however you can access the following properties
of the Hook after running it:
+ * ``descriptions``: an array of cursor descriptions. If
``return_last`` is True, this will be
+ a one-element array containing the cursor ``description`` for the
last statement.
+ Otherwise, it will contain the cursor description for each
statement executed.
+ * ``last_description``: the description for the last statement
executed
- * descriptions - has an array of cursor descriptions - each
statement executed contain the list
- of descriptions executed. If ``return_last`` is used, this is
always a one-element array
- * last_description - description of the last statement executed
-
- Note that return value from the hook will ONLY be actually returned
when handler is provided. Setting
- the ``handler`` to None, results in this method returning None.
+ Note that query result will ONLY be actually returned when a handler
is provided; if
+ ``handler`` is None, this method will return None.
Handler is a way to process the rows from cursor (Iterator) into a
value that is suitable to be
- returned to XCom and generally fit in memory. As an optimization,
handler is usually not executed
- by the SQLExecuteQuery operator if `do_xcom_push` is not specified.
Review Comment:
this bit about sql execute operator, i thought isn't really relevant to
hook.run docstring.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
