Add docs for Oracle operators (apache#30979)

* [oracle] Add docs for operators

* Rename operators doc file

* Move example code blocks to an example dag

airflow/providers/oracle/example_dags/__init__.py

@@ -0,0 +1,16 @@
+# 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/oracle/example_dags/example_oracle.py

@@ -0,0 +1,60 @@
+# 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 datetime import datetime
+
+from airflow import DAG
+from airflow.providers.oracle.operators.oracle import OracleOperator, OracleStoredProcedureOperator
+
+with DAG(
+    max_active_runs=1,
+    max_active_tasks=3,
+    catchup=False,
+    start_date=datetime(2023, 1, 1),
+    dag_id="example_oracle",
+) as dag:
+
+    # [START howto_oracle_operator]
+
+    opr_sql = OracleOperator(
+        task_id="task_sql", oracle_conn_id="oracle", sql="SELECT 1 FROM DUAL", autocommit=True
+    )
+
+    # [END howto_oracle_operator]
+
+    # [START howto_oracle_stored_procedure_operator_with_list_inout]
+
+    opr_stored_procedure_with_list_input_output = OracleStoredProcedureOperator(
+        task_id="opr_stored_procedure_with_list_input_output",
+        oracle_conn_id="oracle",
+        procedure="TEST_PROCEDURE",
+        parameters=[3, int],
+    )
+
+    # [END howto_oracle_stored_procedure_operator_with_list_inout]
+
+    # [START howto_oracle_stored_procedure_operator_with_dict_inout]
+
+    opr_stored_procedure_with_dict_input_output = OracleStoredProcedureOperator(
+        task_id="opr_stored_procedure_with_dict_input_output",
+        oracle_conn_id="oracle",
+        procedure="TEST_PROCEDURE",
+        parameters={"val_in": 3, "val_out": int},
+    )
+
+    # [END howto_oracle_stored_procedure_operator_with_dict_inout]

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

@@ -27,6 +27,7 @@ Content
     :caption: Guides
 
     Connection types <connections/oracle>
+    Operators <operators/index>
 
 .. toctree::
     :maxdepth: 1
@@ -38,6 +39,7 @@ Content
     :maxdepth: 1
     :caption: Resources
 
+    Example DAGs <https://github.com/apache/airflow/tree/providers-oracle/|version|/airflow/providers/oracle/example_dags>
     PyPI Repository <https://pypi.org/project/apache-airflow-providers-oracle/>
     Installing from sources <installing-providers-from-sources>
 

docs/apache-airflow-providers-oracle/operators/index.rst

@@ -0,0 +1,78 @@
+ .. 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.
+
+
+.. _howto/operators:oracle:
+
+Oracle Operators
+================
+The Oracle connection type provides connection to a Oracle database.
+
+Execute SQL in an Oracle database
+---------------------------------
+
+To execute arbitrary SQL in an Oracle database, use the
+:class:`~airflow.providers.oracle.operators.oracle.OracleOperator`.
+
+An example of executing a simple query is as follows:
+
+.. exampleinclude:: /../../airflow/providers/oracle/example_dags/example_oracle.py
+    :language: python
+    :start-after: [START howto_oracle_operator]
+    :end-before: [END howto_oracle_operator]
+
+
+Execute a Stored Procedure in an Oracle database
+------------------------------------------------
+
+To execute a Stored Procedure in an Oracle database, use the
+:class:`~airflow.providers.oracle.operators.oracle.OracleStoredProcedureOperator`.
+
+Assume a stored procedure exists in the database that looks like this:
+
+    .. code-block:: sql
+
+        CREATE OR REPLACE PROCEDURE
+        TEST_PROCEDURE (val_in IN INT, val_out OUT INT) AS
+        BEGIN
+        val_out := val_in * 2;
+        END;
+        /
+
+This stored procedure accepts a single integer argument, val_in, and outputs
+a single integer argument, val_out. This can be represented with the following
+call using :class:`~airflow.providers.oracle.operators.oracle.OracleStoredProcedureOperator`
+with parameters passed positionally as a list:
+
+.. exampleinclude:: /../../airflow/providers/oracle/example_dags/example_oracle.py
+    :language: python
+    :start-after: [START howto_oracle_stored_procedure_operator_with_list_inout]
+    :end-before: [END howto_oracle_stored_procedure_operator_with_list_inout]
+
+
+Alternatively, parameters can be passed as keyword arguments using a dictionary
+as well.
+
+.. exampleinclude:: /../../airflow/providers/oracle/example_dags/example_oracle.py
+    :language: python
+    :start-after: [START howto_oracle_stored_procedure_operator_with_dict_inout]
+    :end-before: [END howto_oracle_stored_procedure_operator_with_dict_inout]
+
+Both input and output will be passed to xcom provided that xcom push is requested.
+
+More on stored procedure execution can be found in `oracledb documentation
+<https://python-oracledb.readthedocs.io/en/latest/user_guide/plsql_execution.html#pl-sql-stored-procedures>`_.