From 702adedf20e3d73078f17d29b564acd367e18a66 Mon Sep 17 00:00:00 2001
From: Purujit Saha <purujit.saha@snowflake.com>
Date: Thu, 22 Feb 2024 17:45:58 +0000
Subject: [PATCH] Add more detailed javadoc for the drop related api to warn
 about the pitfalls

---
 .../streaming/SnowflakeStreamingIngestChannel.java   |  6 ++++++
 .../streaming/SnowflakeStreamingIngestClient.java    | 12 +++++++++---
 2 files changed, 15 insertions(+), 3 deletions(-)

diff --git a/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestChannel.java b/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestChannel.java
index b8687358e..9475f86ef 100644
--- a/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestChannel.java
+++ b/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestChannel.java
@@ -82,6 +82,12 @@ public interface SnowflakeStreamingIngestChannel {
   /**
    * Close the channel, this function will make sure all the data in this channel is committed
    *
+   * <p>Note that this call with drop=true will delete <a
+   * href=https://docs.snowflake.com/en/user-guide/data-load-snowpipe-streaming-overview#offset-tokens>Offset
+   * Token</a> information from Snowflake servers unless the channel has already been opened in
+   * another client. So only use it if you are completely done ingesting data for this channel. If
+   * you open a channel with the same name in the future, it will behave like a new channel.
+   *
    * @param drop if true, the channel will be dropped after all data is successfully committed.
    * @return a completable future which will be completed when the channel is closed
    */
diff --git a/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestClient.java b/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestClient.java
index 8b65b5cae..42f0638d8 100644
--- a/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestClient.java
+++ b/src/main/java/net/snowflake/ingest/streaming/SnowflakeStreamingIngestClient.java
@@ -28,9 +28,15 @@ public interface SnowflakeStreamingIngestClient extends AutoCloseable {
   /**
    * Drop the specified channel on the server using a {@link DropChannelRequest}
    *
-   * <p>Note that this call will blindly drop the latest version of the channel and any pending data
-   * will be lost. Also see {@link SnowflakeStreamingIngestChannel#close(boolean)} to drop channels
-   * on close. That approach will drop the local version of the channel and if the channel has been
+   * <p>Note that this call will <em>blindly</em> drop the latest version of the channel and any
+   * pending data will be lost. It will also delete <a
+   * href=https://docs.snowflake.com/en/user-guide/data-load-snowpipe-streaming-overview#offset-tokens>Offset
+   * Token</a> information from Snowflake servers. So only use it if you are completely done
+   * ingesting data for this channel. If you open a channel with the same name in the future, it
+   * will behave like a new channel.
+   *
+   * <p>Also see {@link SnowflakeStreamingIngestChannel#close(boolean)} to drop channels on close.
+   * That approach will drop the local version of the channel and if the channel has been
    * concurrently reopened by another client, that version of the channel won't be affected.
    *
    * @param request the drop channel request