api changes

README.md

@@ -33,32 +33,72 @@ The sensor assumes the `Conn Id` is set to `fivetran`, however if you are managi
 
 ### [Fivetran Operator Async](https://github.com/astronomer/airflow-provider-fivetran-async/tree/main/fivetran_provider_async/operators.py)
 
-`FivetranOperator` submits a Fivetran sync job and monitors it on trigger for completion.
-It requires that you specify the `connector_id` of the sync job to start. You can find `connector_id` in the Settings page of the connector you configured in the [Fivetran dashboard](https://fivetran.com/dashboard/connectors).
-
-Import into your DAG via:
 ```python
 from fivetran_provider_async.operators import FivetranOperator
 ```
 
+`FivetranOperator` submits a Fivetran sync job and monitors it on trigger for completion.
+
+`FivetranOperator` requires that you specify the `connector_id` of the Fivetran connector you wish to trigger. You can find `connector_id` in the Settings page of the connector you configured in the [Fivetran dashboard](https://fivetran.com/dashboard/connectors).
+
+The `FivetranOperator` will wait for the sync to complete so long as `wait_for_completion=True` (this is the default). It is recommended that
+you run in deferrable mode (this is also the default). If `wait_for_completion=False`, the operator will return the timestamp for the last sync.
+
+Import into your DAG via:
+
 ### [Fivetran Sensor Async](https://github.com/astronomer/airflow-provider-fivetran-async/tree/main/fivetran_provider_async/sensors.py)
 
+```python
+from fivetran_provider_async.sensors import FivetranSensor
+```
+
 `FivetranSensor` monitors a Fivetran sync job for completion.
 Monitoring with `FivetranSensor` allows you to trigger downstream processes only when the Fivetran sync jobs have completed, ensuring data consistency.
 
-
+`FivetranSensor` requires that you specify the `connector_id` of the Fivetran connector you want to wait for. You can find `connector_id` in the Settings page of the connector you configured in the [Fivetran dashboard](https://fivetran.com/dashboard/connectors).
 
 You can use multiple instances of `FivetranSensor` to monitor multiple Fivetran connectors.
 
-If used in this way,
+`FivetranSensor` is most commonly useful in two scenarios:
 
-`FivetranSensor` requires that you specify the `connector_id` of the sync job to start. You can find `connector_id` in the Settings page of the connector you configured in the [Fivetran dashboard](https://fivetran.com/dashboard/connectors).
+1. Fivetran is using a separate scheduler than the Airflow scheduler.
+2. You set `wait_for_completion=False` in the `FivetranOperator`, and you need to await the `FivetranOperator` task later. (You may want to do this if you want to arrange your DAG such that some tasks are dependent on _starting_ a sync and other tasks are dependent on _completing_ a sync).
+
+If you are doing the 1st pattern, you may find it useful to set the `completed_after_time` to `data_interval_end`, or `data_interval_end` with some buffer:
 
-Import into your DAG via:
 ```python
-from fivetran_provider_async.sensors import FivetranSensor
+fivetran_sensor = FivetranSensor(
+    task_id="wait_for_fivetran_externally_scheduled_sync",
+    connector_id="bronzing_largely",
+    poke_interval=5,
+    completed_after_time="{{ data_interval_end + macros.timedelta(minutes=1) }}",
+)
+```
+
+If you are doing the 2nd pattern, you can use XComs to pass the target completed time to the sensor:
+
+```python
+fivetran_op = FivetranOperator(
+    task_id="fivetran_sync_my_db",
+    connector_id="bronzing_largely",
+    wait_for_completion=False,
+)
+
+fivetran_sensor = FivetranSensor(
+    task_id="wait_for_fivetran_db_sync",
+    connector_id="bronzing_largely",
+    poke_interval=5,
+    completed_after_time="{{ task_instance.xcom_pull('fivetran_sync_op', key='return_value') }}",
+)
+
+fivetran_op >> fivetran_sensor
 ```
 
+You may also specify the `FivetranSensor` without a `completed_after_time`.
+In this case, the sensor will make note of when the last completed time was, and will wait for a new completed time.
+
+Import into your DAG via:
+
 ## Examples
 
 See the [**examples**](https://github.com/astronomer/airflow-provider-fivetran-async/tree/main/fivetran_provider_async/example_dags) directory for an example DAG.

fivetran_provider_async/example_dags/example_fivetran_async.py

@@ -34,7 +34,7 @@
         task_id="fivetran_async_sensor",
         connector_id="bronzing_largely",
         poke_interval=5,
-        xcom="{{ task_instance.xcom_pull('fivetran_sync_op', key='return_value') }}",
+        completed_after_time="{{ task_instance.xcom_pull('fivetran_sync_op', key='return_value') }}",
     )
 
     fivetran_async_op >> fivetran_sync_op >> fivetran_async_sensor

fivetran_provider_async/example_dags/example_fivetran_dbt.py

@@ -4,7 +4,6 @@
 from airflow.providers.ssh.operators.ssh import SSHOperator
 
 from fivetran_provider_async.operators import FivetranOperator
-from fivetran_provider_async.sensors import FivetranSensor
 
 default_args = {
     "owner": "Airflow",
@@ -22,29 +21,15 @@
         connector_id="{{ var.value.linkedin_connector_id }}",
     )
 
-    linkedin_sensor = FivetranSensor(
-        task_id="linkedin-sensor",
-        connector_id="{{ var.value.linkedin_connector_id }}",
-        poke_interval=600,
-    )
-
     twitter_sync = FivetranOperator(
         task_id="twitter-ads-sync",
         connector_id="{{ var.value.twitter_connector_id }}",
     )
 
-    twitter_sensor = FivetranSensor(
-        task_id="twitter-sensor",
-        connector_id="{{ var.value.twitter_connector_id }}",
-        poke_interval=600,
-    )
-
     dbt_run = SSHOperator(
         task_id="dbt_ad_reporting",
         command="cd dbt_ad_reporting ; ~/.local/bin/dbt run -m +ad_reporting",
         ssh_conn_id="dbtvm",
     )
 
-    linkedin_sync >> linkedin_sensor
-    twitter_sync >> twitter_sensor
-    [linkedin_sensor, twitter_sensor] >> dbt_run
+    [linkedin_sync, twitter_sync] >> dbt_run

fivetran_provider_async/example_dags/example_fivetran_xcom.py

@@ -34,7 +34,7 @@
         fivetran_conn_id="fivetran_default",
         connector_id="{{ var.value.connector_id }}",
         poke_interval=5,
-        xcom="{{ task_instance.xcom_pull('fivetran-operator', key='return_value') }}",
+        completed_after_time="{{ task_instance.xcom_pull('fivetran-operator', key='return_value') }}",
     )
 
     fivetran_operator >> delay_task >> fivetran_sensor