This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new f76883c95d3 Added documentation for the SqlThresholdCheckOperator
(#44787)
f76883c95d3 is described below
commit f76883c95d3894e9c6cd2fa736d0c4579c4b82b4
Author: dominikhei <[email protected]>
AuthorDate: Mon Dec 9 20:52:10 2024 +0100
Added documentation for the SqlThresholdCheckOperator (#44787)
* Added documentation for the SqlThresholdCheckOperator
* Resolved doc errors
* Corrected last spelling mistake in docs
---
.../operators.rst | 27 ++++++++++
.../airflow/providers/common/sql/operators/sql.py | 4 ++
.../common/sql/example_sql_threshold_check.py | 62 ++++++++++++++++++++++
3 files changed, 93 insertions(+)
diff --git a/docs/apache-airflow-providers-common-sql/operators.rst
b/docs/apache-airflow-providers-common-sql/operators.rst
index e6e24eefb00..577f92fb7b2 100644
--- a/docs/apache-airflow-providers-common-sql/operators.rst
+++ b/docs/apache-airflow-providers-common-sql/operators.rst
@@ -146,3 +146,30 @@ The below example demonstrates how to instantiate the
SQLTableCheckOperator task
:dedent: 4
:start-after: [START howto_operator_sql_table_check]
:end-before: [END howto_operator_sql_table_check]
+
+
+.. _howto/operator:SQLThresholdCheckOperator:
+
+Check values against a threshold
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the
:class:`~airflow.providers.common.sql.operators.sql.SQLThresholdCheckOperator`
to compare a specific SQL query result against defined minimum and maximum
thresholds.
+Both thresholds can either be a numeric value or another SQL query that
evaluates to a numeric value.
+This operator requires a connection ID, along with the SQL query to execute,
and allows optional specification of a database, if the one from the
connection_id should be overridden.
+The parameters are:
+- ``sql`` - the sql query to be executed, as a templated string.
+- ``min_threshold`` The minimum threshold that is checked against. Either as a
numeric value or templated sql query.
+- ``max_threshold`` The maximum threshold that is checked against. Either as a
numeric value or templated sql query.
+- ``conn_id`` (optional) The connection ID used to connect to the database.
+- ``database`` (optional) name of the database which overwrites the one from
the connection.
+
+
+The below example demonstrates how to instantiate the
SQLThresholdCheckOperator task.
+
+.. exampleinclude::
/../../providers/tests/system/common/sql/example_sql_threshold_check.py
+ :language: python
+ :dedent: 4
+ :start-after: [START howto_operator_sql_threshold_check]
+ :end-before: [END howto_operator_sql_threshold_check]
+
+If the value returned by the query, is within the thresholds, the task passes.
Otherwise, it fails.
diff --git a/providers/src/airflow/providers/common/sql/operators/sql.py
b/providers/src/airflow/providers/common/sql/operators/sql.py
index 3643d01b28e..56b14fe66b2 100644
--- a/providers/src/airflow/providers/common/sql/operators/sql.py
+++ b/providers/src/airflow/providers/common/sql/operators/sql.py
@@ -1041,6 +1041,10 @@ class SQLThresholdCheckOperator(BaseSQLOperator):
:param database: name of database which overwrite the defined one in
connection
:param min_threshold: numerical value or min threshold sql to be executed
(templated)
:param max_threshold: numerical value or max threshold sql to be executed
(templated)
+
+ .. seealso::
+ For more information on how to use this operator, take a look at the
guide:
+ :ref:`howto/operator:SQLThresholdCheckOperator`
"""
template_fields: Sequence[str] = (
diff --git a/providers/tests/system/common/sql/example_sql_threshold_check.py
b/providers/tests/system/common/sql/example_sql_threshold_check.py
new file mode 100644
index 00000000000..ab65a73a789
--- /dev/null
+++ b/providers/tests/system/common/sql/example_sql_threshold_check.py
@@ -0,0 +1,62 @@
+#
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+from __future__ import annotations
+
+from airflow import DAG
+from airflow.providers.common.sql.operators.sql import
SQLThresholdCheckOperator
+from airflow.utils.timezone import datetime
+
+connection_args = {
+ "conn_id": "sales_db",
+ "conn_type": "Postgres",
+ "host": "postgres",
+ "schema": "postgres",
+ "login": "postgres",
+ "password": "postgres",
+ "port": 5432,
+}
+
+with DAG(
+ "example_sql_threshold_check_query",
+ description="Example DAG for SQLThresholdCheckOperator.",
+ default_args=connection_args,
+ start_date=datetime(2024, 12, 12),
+ schedule=None,
+ catchup=False,
+) as dag:
+ """
+ ### Example SQL threshold check DAG
+
+ Runs the SQLThresholdCheckOperator against the Airflow metadata DB.
+ """
+
+ # [START howto_operator_sql_threshold_check]
+ threshhold_check = SQLThresholdCheckOperator(
+ task_id="threshhold_check",
+ conn_id="sales_db",
+ sql="SELECT count(distinct(customer_id)) FROM sales;",
+ min_threshold=1,
+ max_threshold=1000,
+ )
+ # [END howto_operator_sql_threshold_check]
+
+
+from tests_common.test_utils.system_tests import get_test_run # noqa: E402
+
+# Needed to run the example DAG with pytest (see:
tests/system/README.md#run_via_pytest)
+test_run = get_test_run(dag)
