Document dynamic destination key should be unique over the pipeline (#…

…32338)

* Document dynamic destination key should be unique over the pipeline

* address comments

sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/BigQueryIO.java

@@ -3995,7 +3995,12 @@ ValueProvider<TableReference> getTableWithDefaultProject(BigQueryOptions bqOptio
     }
   }
 
-  /** Clear the cached map of created tables. Used for testing. */
+  /**
+   * Clear the cached map of created tables. Used for testing only.
+   *
+   * <p>Should not be used in any PTransform as cache is a static member shared by different
+   * BigQueryIO.write.
+   */
   @VisibleForTesting
   static void clearStaticCaches() throws ExecutionException, InterruptedException {
     CreateTables.clearCreatedTables();

sdks/java/io/google-cloud-platform/src/main/java/org/apache/beam/sdk/io/gcp/bigquery/DynamicDestinations.java

@@ -132,6 +132,10 @@ void setSideInputAccessorFromProcessContext(DoFn<?, ?>.ProcessContext context) {
   /**
    * Returns an object that represents at a high level which table is being written to. May not
    * return null.
+   *
+   * <p>The method must return a unique object for different destination tables involved over all
+   * BigQueryIO write transforms in the same pipeline. See
+   * https://github.com/apache/beam/issues/32335 for details.
    */
   public abstract DestinationT getDestination(@Nullable ValueInSingleWindow<T> element);