From 07e87989445f1d5d37449384fa03747228b59102 Mon Sep 17 00:00:00 2001
From: Vincent Beck <vincbeck@amazon.com>
Date: Wed, 2 Mar 2022 16:13:19 -0500
Subject: [PATCH] Cleanup RedshiftSQLOperator documentation

---
 ...le_redshift.py => example_redshift_sql.py} | 51 ++++++-----
 .../operators/redshift_sql.rst                | 88 ++++++-------------
 2 files changed, 57 insertions(+), 82 deletions(-)
 rename airflow/providers/amazon/aws/example_dags/{example_redshift.py => example_redshift_sql.py} (60%)

diff --git a/airflow/providers/amazon/aws/example_dags/example_redshift.py b/airflow/providers/amazon/aws/example_dags/example_redshift_sql.py
similarity index 60%
rename from airflow/providers/amazon/aws/example_dags/example_redshift.py
rename to airflow/providers/amazon/aws/example_dags/example_redshift_sql.py
index 51f9f1462f61b..a71ef71934edc 100644
--- a/airflow/providers/amazon/aws/example_dags/example_redshift.py
+++ b/airflow/providers/amazon/aws/example_dags/example_redshift_sql.py
@@ -15,24 +15,20 @@
 # KIND, either express or implied.  See the License for the
 # specific language governing permissions and limitations
 # under the License.
-"""
-This is an example dag for using `RedshiftSQLOperator` to authenticate with Amazon Redshift
-then execute a simple select statement
-"""
+
 from datetime import datetime
 
-# [START redshift_operator_howto_guide]
 from airflow import DAG
+from airflow.models.baseoperator import chain
 from airflow.providers.amazon.aws.operators.redshift_sql import RedshiftSQLOperator
 
 with DAG(
-    dag_id="redshift",
+    dag_id="example_redshift_sql",
     start_date=datetime(2021, 1, 1),
     schedule_interval=None,
     catchup=False,
     tags=['example'],
 ) as dag:
-    # [START howto_operator_redshift_create_table]
     setup__task_create_table = RedshiftSQLOperator(
         task_id='setup__create_table',
         sql="""
@@ -43,10 +39,9 @@
             );
         """,
     )
-    # [END howto_operator_redshift_create_table]
-    # [START howto_operator_redshift_populate_table]
-    task_insert_data = RedshiftSQLOperator(
-        task_id='task_insert_data',
+
+    setup__task_insert_data = RedshiftSQLOperator(
+        task_id='setup__task_insert_data',
         sql=[
             "INSERT INTO fruit VALUES ( 1, 'Banana', 'Yellow');",
             "INSERT INTO fruit VALUES ( 2, 'Apple', 'Red');",
@@ -56,19 +51,29 @@
             "INSERT INTO fruit VALUES ( 6, 'Strawberry', 'Red');",
         ],
     )
-    # [END howto_operator_redshift_populate_table]
-    # [START howto_operator_redshift_get_all_rows]
-    task_get_all_table_data = RedshiftSQLOperator(
-        task_id='task_get_all_table_data', sql="CREATE TABLE more_fruit AS SELECT * FROM fruit;"
+
+    # [START howto_operator_redshift_sql]
+    task_select_data = RedshiftSQLOperator(
+        task_id='task_get_all_table_data', sql="""CREATE TABLE more_fruit AS SELECT * FROM fruit;"""
     )
-    # [END howto_operator_redshift_get_all_rows]
-    # [START howto_operator_redshift_get_with_filter]
-    task_get_with_filter = RedshiftSQLOperator(
-        task_id='task_get_with_filter',
-        sql="CREATE TABLE filtered_fruit AS SELECT * FROM fruit WHERE color = '{{ params.color }}';",
+    # [END howto_operator_redshift_sql]
+
+    # [START howto_operator_redshift_sql_with_params]
+    task_select_filtered_data = RedshiftSQLOperator(
+        task_id='task_get_filtered_table_data',
+        sql="""CREATE TABLE filtered_fruit AS SELECT * FROM fruit WHERE color = '{{ params.color }}';""",
         params={'color': 'Red'},
     )
-    # [END howto_operator_redshift_get_with_filter]
+    # [END howto_operator_redshift_sql_with_params]
 
-    setup__task_create_table >> task_insert_data >> task_get_all_table_data >> task_get_with_filter
-# [END redshift_operator_howto_guide]
+    teardown__task_drop_table = RedshiftSQLOperator(
+        task_id='teardown__drop_table',
+        sql='DROP TABLE IF EXISTS fruit',
+    )
+
+    chain(
+        setup__task_create_table,
+        setup__task_insert_data,
+        [task_select_data, task_select_filtered_data],
+        teardown__task_drop_table,
+    )
diff --git a/docs/apache-airflow-providers-amazon/operators/redshift_sql.rst b/docs/apache-airflow-providers-amazon/operators/redshift_sql.rst
index c53a4b95ac223..2363ec4b4a911 100644
--- a/docs/apache-airflow-providers-amazon/operators/redshift_sql.rst
+++ b/docs/apache-airflow-providers-amazon/operators/redshift_sql.rst
@@ -17,80 +17,50 @@
 
 .. _howto/operator:RedshiftSQLOperator:
 
-RedshiftSQLOperator
-===================
+Amazon Redshift Operators
+=========================
 
-.. contents::
-  :depth: 1
-  :local:
+`Amazon Redshift <https://aws.amazon.com/redshift/>`__ manages all the work of setting up, operating, and scaling a data warehouse:
+provisioning capacity, monitoring and backing up the cluster, and applying patches and upgrades to
+the Amazon Redshift engine. You can focus on using your data to acquire new insights for your
+business and customers.
 
-Overview
---------
+Airflow provides an operator to execute queries against an Amazon Redshift cluster.
 
-Use the :class:`RedshiftSQLOperator <airflow.providers.amazon.aws.operators.redshift_sql>` to execute
-statements against an Amazon Redshift cluster.
+Prerequisite Tasks
+^^^^^^^^^^^^^^^^^^
 
-:class:`RedshiftSQLOperator <airflow.providers.amazon.aws.operators.redshift_sql.RedshiftSQLOperator>` works together with
-:class:`RedshiftSQLHook <airflow.providers.amazon.aws.hooks.redshift.RedshiftSQLHook>` to establish
-connections with Amazon Redshift.
+.. include:: _partials/prerequisite_tasks.rst
 
+Redshift SQL
+^^^^^^^^^^^^
 
-example_redshift.py
--------------------
+This operator executes a SQL query against an Amazon Redshift cluster.
 
-Purpose
-"""""""
+Execute a SQL query
+"""""""""""""""""""
 
-This is a basic example dag for using :class:`RedshiftSQLOperator <airflow.providers.amazon.aws.operators.redshift_sql>`
-to execute statements against an Amazon Redshift cluster.
-
-Create a table
-""""""""""""""
-
-In the following code we are creating a table called "fruit".
-
-.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift.py
-    :language: python
-    :start-after: [START howto_operator_redshift_create_table]
-    :end-before: [END howto_operator_redshift_create_table]
-
-Insert data into a table
-""""""""""""""""""""""""
-
-In the following code we insert a few sample rows into the "fruit" table.
-
-.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift.py
-    :language: python
-    :start-after: [START howto_operator_redshift_populate_table]
-    :end-before: [END howto_operator_redshift_populate_table]
-
-Fetching records from a table
-"""""""""""""""""""""""""""""
-
-Creating a new table, "more_fruit" from the "fruit" table.
-
-.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift.py
+.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift_sql.py
     :language: python
-    :start-after: [START howto_operator_redshift_get_all_rows]
-    :end-before: [END howto_operator_redshift_get_all_rows]
+    :dedent: 4
+    :start-after: [START howto_operator_redshift_sql]
+    :end-before: [END howto_operator_redshift_sql]
 
-Passing Parameters into RedshiftSQLOperator
-"""""""""""""""""""""""""""""""""""""""""""
+Execute a SQL query with parameters
+"""""""""""""""""""""""""""""""""""
 
 RedshiftSQLOperator supports the ``parameters`` attribute which allows us to dynamically pass
 parameters into SQL statements.
 
-.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift.py
+.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift_sql.py
     :language: python
-    :start-after: [START howto_operator_redshift_get_with_filter]
-    :end-before: [END howto_operator_redshift_get_with_filter]
+    :dedent: 4
+    :start-after: [START howto_operator_redshift_sql_with_params]
+    :end-before: [END howto_operator_redshift_sql_with_params]
 
-The complete RedshiftSQLOperator DAG
-------------------------------------
+Reference
+^^^^^^^^^
 
-All together, here is our DAG:
+For further information, look at:
 
-.. exampleinclude:: /../../airflow/providers/amazon/aws/example_dags/example_redshift.py
-    :language: python
-    :start-after: [START redshift_operator_howto_guide]
-    :end-before: [END redshift_operator_howto_guide]
+* `Amazon Redshift Python connector <https://docs.aws.amazon.com/redshift/latest/mgmt/python-connect-examples.html>`__
