You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@beam.apache.org by lc...@apache.org on 2022/01/11 00:04:52 UTC

[beam] branch master updated: [BEAM-3221] Improve documentation in model pipeline protos (#16474)

This is an automated email from the ASF dual-hosted git repository.

lcwik pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/beam.git


The following commit(s) were added to refs/heads/master by this push:
     new ee3b76a  [BEAM-3221] Improve documentation in model pipeline protos (#16474)
ee3b76a is described below

commit ee3b76ad1a6d1e8b92f54236f992887ebb29cbdf
Author: Lukasz Cwik <lu...@gmail.com>
AuthorDate: Mon Jan 10 16:03:39 2022 -0800

    [BEAM-3221] Improve documentation in model pipeline protos (#16474)
    
    * clarify state caching tokens
    * fix documentation around side input types and valid request types.
---
 model/fn-execution/src/main/proto/beam_fn_api.proto | 14 +++++++++++---
 model/pipeline/src/main/proto/beam_runner_api.proto |  7 +++----
 2 files changed, 14 insertions(+), 7 deletions(-)

diff --git a/model/fn-execution/src/main/proto/beam_fn_api.proto b/model/fn-execution/src/main/proto/beam_fn_api.proto
index f8aa6fb..82f9c23a 100644
--- a/model/fn-execution/src/main/proto/beam_fn_api.proto
+++ b/model/fn-execution/src/main/proto/beam_fn_api.proto
@@ -268,8 +268,11 @@ message ProcessBundleRequest {
   // instantiated and executed by the SDK harness.
   string process_bundle_descriptor_id = 1;
 
-  // A cache token which can be used by an SDK to check for the validity
-  // of cached elements which have a cache token associated.
+  // Contains the cache token and also defines the scope of what the token applies to.
+  //
+  // See https://s.apache.org/beam-fn-state-api-and-bundle-processing#heading=h.7ghoih5aig5m
+  // for additional details on how to use the cache token with the State API
+  // to cache data across bundle boundaries.
   message CacheToken {
 
     // A flag to indicate a cache token is valid for all user state.
@@ -289,12 +292,17 @@ message ProcessBundleRequest {
       SideInput side_input = 2;
     }
 
-    // The cache token identifier which should be globally unique.
+    // An opaque token used with the StateKey to create a globally unique
+    // identifier.
     bytes token = 10;
   }
 
   // (Optional) A list of cache tokens that can be used by an SDK to reuse
   // cached data returned by the State API across multiple bundles.
+  //
+  // See https://s.apache.org/beam-fn-state-api-and-bundle-processing#heading=h.7ghoih5aig5m
+  // for additional details on how to use the cache token with the State API
+  // to cache data across bundle boundaries.
   repeated CacheToken cache_tokens = 2;
 
   // (Optional) Elements to be processed with the bundle. Either all or
diff --git a/model/pipeline/src/main/proto/beam_runner_api.proto b/model/pipeline/src/main/proto/beam_runner_api.proto
index aaeb9da..2316c77 100644
--- a/model/pipeline/src/main/proto/beam_runner_api.proto
+++ b/model/pipeline/src/main/proto/beam_runner_api.proto
@@ -452,7 +452,7 @@ message StandardSideInputTypes {
     // Represents a view over a PCollection<KV<K, V>>.
     //
     // StateGetRequests performed on this side input must use
-    // StateKey.IterableSideInput or StateKey.MultimapSideInput.
+    // StateKey.MultimapKeysSideInput or StateKey.MultimapSideInput.
     MULTIMAP = 1 [(beam_urn) = "beam:side_input:multimap:v1"];
   }
 }
@@ -1354,9 +1354,8 @@ message SideInput {
   // This access pattern defines the SDK harness <-> Runner Harness RPC
   // interface for accessing a side input.
   //
-  // The only access pattern intended for Beam, because of its superior
-  // performance possibilities, is "beam:sideinput:multimap" (or some such
-  // URN)
+  // See StandardSideInputTypes for an enumeration of all side input types
+  // defined.
   FunctionSpec access_pattern = 1;
 
   // (Required) The FunctionSpec of the UDF that adapts a particular