Add guide for Apache Druid operators (#18527)

airflow/providers/apache/druid/example_dags/__init__.py

@@ -0,0 +1,17 @@
+#
+# 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.

airflow/providers/apache/druid/example_dags/example_druid_dag.py

@@ -0,0 +1,52 @@
+#
+# 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.
+
+"""
+Example Airflow DAG to submit Apache Druid json index file using `DruidOperator`
+"""
+from airflow.models import DAG
+from airflow.providers.apache.druid.operators.druid import DruidOperator
+from airflow.utils.dates import days_ago
+
+with DAG(
+    dag_id='example_druid_operator',
+    schedule_interval=None,
+    start_date=days_ago(2),
+    tags=['example'],
+) as dag:
+    # [START howto_operator_druid_submit]
+    submit_job = DruidOperator(
+        task_id='spark_submit_job',
+        json_index_file='json_index.json',
+        druid_ingest_conn_id='druid_ingest_default',
+    )
+    # Example content of json_index.json:
+    JSON_INDEX_STR = """
+        {
+            "type": "index_hadoop",
+            "datasource": "datasource_prd",
+            "spec": {
+                "dataSchema": {
+                    "granularitySpec": {
+                        "intervals": ["2021-09-01/2021-09-02"]
+                    }
+                }
+            }
+        }
+    """
+    # [END howto_operator_druid_submit]

airflow/providers/apache/druid/provider.yaml

@@ -19,7 +19,7 @@
 package-name: apache-airflow-providers-apache-druid
 name: Apache Druid
 description: |
-    `Apache Druid <https://druid.apache.org/>`__.
+  `Apache Druid <https://druid.apache.org/>`__.
 
 versions:
   - 2.0.2
@@ -36,6 +36,8 @@ integrations:
   - integration-name: Apache Druid
     external-doc-url: https://druid.apache.org/
     logo: /integration-logos/apache/druid-1.png
+    how-to-guide:
+      - /docs/apache-airflow-providers-apache-druid/operators.rst
     tags: [apache]
 
 operators:

docs/apache-airflow-providers-apache-druid/index.rst

@@ -21,13 +21,20 @@
 Content
 -------
 
+.. toctree::
+    :maxdepth: 1
+    :caption: Guides
+
+    Operators <operators>
+
 .. toctree::
     :maxdepth: 1
     :caption: References
 
     Python API <_api/airflow/providers/apache/druid/index>
     PyPI Repository <https://pypi.org/project/apache-airflow-providers-apache-druid/>
     Installing from sources <installing-providers-from-sources>
+    Example DAGs <https://github.com/apache/airflow/tree/main/airflow/providers/apache/druid/example_dags>
 
 .. THE REMAINDER OF THE FILE IS AUTOMATICALLY GENERATED. IT WILL BE OVERWRITTEN AT RELEASE TIME!
 

docs/apache-airflow-providers-apache-druid/operators.rst

@@ -0,0 +1,52 @@
+ .. 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.
+
+
+Apache Druid Operators
+======================
+
+.. contents::
+  :depth: 1
+  :local:
+
+Prerequisite
+------------
+
+To use ``DruidOperator``, you must configure a Druid Connection first.
+
+DruidOperator
+-------------------
+
+Submit a task directly to Druid, you need to provide the filepath to the Druid index specification ``json_index_file``, and the connection id of the Druid overlord ``druid_ingest_conn_id`` which accepts index jobs in Airflow Connections.
+
+There is also a example content of the Druid Ingestion specification below.
+
+For parameter definition take a look at :class:`~airflow.providers.apache.druid.operators.druid.DruidOperator`.
+
+Using the operator
+""""""""""""""""""
+
+.. exampleinclude:: /../../airflow/providers/apache/druid/example_dags/example_druid_dag.py
+    :language: python
+    :dedent: 4
+    :start-after: [START howto_operator_druid_submit]
+    :end-before: [END howto_operator_druid_submit]
+
+Reference
+"""""""""
+
+For more information, please refer to `Apache Druid Ingestion spec reference <https://druid.apache.org/docs/latest/ingestion/ingestion-spec.html>`_.