README

Go SDK (experimental)

The Go SDK is currently an experimental feature of Apache Beam and not suitable for production use. It is based on the following initial design.

How to run the examples

Prerequisites: to use Google Cloud sources and sinks (default for most examples), follow the setup here. You can verify that it works by running the corresponding Java example.

The examples are normal Go programs and are most easily run directly. They are parameterized by Go flags. For example, to run wordcount on direct runner do:

$ pwd
[...]/sdks/go
$ go run examples/wordcount/wordcount.go --output=/tmp/result.txt
[{6: KV<string,int>/GW/KV<bytes,int[varintz]>}]
[{10: KV<int,string>/GW/KV<int[varintz],bytes>}]
2018/03/21 09:39:03 Pipeline:
2018/03/21 09:39:03 Nodes: {1: []uint8/GW/bytes}
{2: string/GW/bytes}
{3: string/GW/bytes}
{4: string/GW/bytes}
{5: string/GW/bytes}
{6: KV<string,int>/GW/KV<bytes,int[varintz]>}
{7: CoGBK<string,int>/GW/CoGBK<bytes,int[varintz]>}
{8: KV<string,int>/GW/KV<bytes,int[varintz]>}
{9: string/GW/bytes}
{10: KV<int,string>/GW/KV<int[varintz],bytes>}
{11: CoGBK<int,string>/GW/CoGBK<int[varintz],bytes>}
Edges: 1: Impulse [] -> [Out: []uint8 -> {1: []uint8/GW/bytes}]
2: ParDo [In(Main): []uint8 <- {1: []uint8/GW/bytes}] -> [Out: T -> {2: string/GW/bytes}]
3: ParDo [In(Main): string <- {2: string/GW/bytes}] -> [Out: string -> {3: string/GW/bytes}]
4: ParDo [In(Main): string <- {3: string/GW/bytes}] -> [Out: string -> {4: string/GW/bytes}]
5: ParDo [In(Main): string <- {4: string/GW/bytes}] -> [Out: string -> {5: string/GW/bytes}]
6: ParDo [In(Main): T <- {5: string/GW/bytes}] -> [Out: KV<T,int> -> {6: KV<string,int>/GW/KV<bytes,int[varintz]>}]
7: CoGBK [In(Main): KV<string,int> <- {6: KV<string,int>/GW/KV<bytes,int[varintz]>}] -> [Out: CoGBK<string,int> -> {7: CoGBK<string,int>/GW/CoGBK<bytes,int[varintz]>}]
8: Combine [In(Main): int <- {7: CoGBK<string,int>/GW/CoGBK<bytes,int[varintz]>}] -> [Out: KV<string,int> -> {8: KV<string,int>/GW/KV<bytes,int[varintz]>}]
9: ParDo [In(Main): KV<string,int> <- {8: KV<string,int>/GW/KV<bytes,int[varintz]>}] -> [Out: string -> {9: string/GW/bytes}]
10: ParDo [In(Main): T <- {9: string/GW/bytes}] -> [Out: KV<int,T> -> {10: KV<int,string>/GW/KV<int[varintz],bytes>}]
11: CoGBK [In(Main): KV<int,string> <- {10: KV<int,string>/GW/KV<int[varintz],bytes>}] -> [Out: CoGBK<int,string> -> {11: CoGBK<int,string>/GW/CoGBK<int[varintz],bytes>}]
12: ParDo [In(Main): CoGBK<int,string> <- {11: CoGBK<int,string>/GW/CoGBK<int[varintz],bytes>}] -> []
2018/03/21 09:39:03 Reading from gs://apache-beam-samples/shakespeare/kinglear.txt
2018/03/21 09:39:04 Writing to /tmp/result.txt

The debugging output is currently quite verbose and likely to change. The output is a local file in this case:

$ head /tmp/result.txt
while: 2
darkling: 1
rail'd: 1
ford: 1
bleed's: 1
hath: 52
Remain: 1
disclaim: 1
sentence: 1
purse: 6

To run wordcount on dataflow runner do:

$  go run wordcount.go --runner=dataflow --project=<YOUR_GCP_PROJECT> --region=<YOUR_GCP_REGION> --staging_location=<YOUR_GCS_LOCATION>/staging --worker_harness_container_image=<YOUR_SDK_HARNESS_IMAGE_LOCATION> --output=<YOUR_GCS_LOCATION>/output

The output is a GCS file in this case:

$ gsutil cat <YOUR_GCS_LOCATION>/output* | head
Blanket: 1
blot: 1
Kneeling: 3
cautions: 1
appears: 4
Deserved: 1
nettles: 1
OSWALD: 53
sport: 3
Crown'd: 1

See BUILD.md for how to build Go code in general. See container documentation for how to build and push the Go SDK harness container image.

Issues

Please use the sdk-go component for any bugs or feature requests.

Contributing to the Go SDK

New to developing Go?

https://tour.golang.org : The Go Tour gives you the basics of the language, interactively no installation required.

https://github.com/campoy/go-tooling-workshop is a great start on learning good (optional) development tools for Go.

Developing Go Beam SDK on Github

To make and test changes when working with Go, it's neecessary to clone your repository in a subdirectory of your GOPATH. This permits existing gradle tools to use your in progress changes.

# Create a Go compatible place for the repo, using src/github.com/apache/
# matches where Go will look for the files, or go get would put them.
$ mkdir -p $GOPATH/src/github.com/apache/
$ cd $GOPATH/src/github.com/apache/


# Clone the repo, and update your branch as normal
$ git clone https://github.com/apache/beam.git
$ cd beam
$ git remote add <GitHub_user> git@github.com:<GitHub_user>/beam.git
$ git fetch --all

# Get or Update all the Go SDK dependencies
$ go get -u ./...
# Test that the system compiles and runs.
$ go test ./...

If you don’t have a GOPATH set, follow these instructions to create a new directory in your home directory, and use that.

Follow the contribution guide to create branches, and submit pull requests as normal.

Dependency management

Until BEAM-5379 is resolved, Beam locks versions of packages with the gogradle plugin. If new dependencies are added in a PR then the lock file needs to be updated. From the $GOPATH/src/github.com/apache/beam directory run

$ ./gradlew :sdks:go:goLock
`./gradlew :goPostcommit`

to update the lock file, and test your code under the locked versions. gogradle will add vendor directories with the locked versions of the code.

You can sanity check a PR on Jenkins by commenting Run Go PostCommit to trigger the integration tests. This is important so that the Beam testing done on the jenkins cluster can produce consistent results, and have the packages available.

Expand ▾ Collapse ▴

Directories

Path Synopsis
cmd/beamctl beamctl is a command line client for the Apache Beam portability services.
cmd/beamctl/cmd Package cmd contains the commands for beamctl.
cmd/specialize specialize is a low-level tool to generate type-specialized code.
cmd/starcgen starcgen is a tool to generate specialized type assertion shims to be used in Apache Beam Go SDK pipelines instead of the default reflection shim.
cmd/symtab Package verifies that functions sym2addr and addr2sym work correctly.
container
examples/complete/autocomplete
examples/contains
examples/cookbook/combine
examples/cookbook/filter
examples/cookbook/join
examples/cookbook/max
examples/cookbook/tornadoes tornadoes is an example that reads the public samples of weather data from BigQuery, counts the number of tornadoes that occur in each month, and writes the results to BigQuery.
examples/debugging_wordcount debugging_wordcount is an example that verifies word counts in Shakespeare and includes Beam best practices.
examples/forest forest is an example that shows that pipeline construction is normal Go code -- the pipeline "forest" is created recursively and uses a global variable -- and that a pipeline may contain non-connected parts.
examples/grades
examples/minimal_wordcount minimal_wordcount is an example that counts words in Shakespeare.
examples/multiout multiout is a wordcount variation that uses a multi-outout DoFn and writes 2 output files.
examples/pingpong
examples/readavro readavro is a simple Avro read/write Example This example uses a 500 Byte sample avro file [twitter.avro] download here: https://s3-eu-west-1.amazonaws.com/daidokoro-dev/apache/twitter.avro
examples/streaming_wordcap streaming_wordcap is a toy streaming pipeline that uses PubSub.
examples/stringsplit An example of using a Splittable DoFn in the Go SDK with a portable runner.
examples/windowed_wordcount windowed_wordcount counts words in text, and can run over either unbounded or bounded input collections.
examples/wordcount wordcount is an example that counts words in Shakespeare and includes Beam best practices.
examples/xlang Package xlang contains functionality for testing cross-language transforms.
examples/xlang/cogroup_by cogroup_by exemplifies using a cross-language cogroup by key transform from a test expansion service.
examples/xlang/combine combine exemplifies using a cross-language combine per key transform from a test expansion service.
examples/xlang/combine_globally combine_globally exemplifies using a cross-language combine global transform from a test expansion service.
examples/xlang/flatten
examples/xlang/group_by group_by exemplifies using a cross-language group by key transform from a test expansion service.
examples/xlang/multi_input_output multi exemplifies using a cross-language transform with multiple inputs and outputs from a test expansion service.
examples/xlang/partition partition exemplifies using a cross-language partition transform from a test expansion service.
examples/xlang/wordcount wordcount exemplifies using a cross-language Count transform from a test expansion service to count words.
examples/yatzy yatzy is an implementation of https://en.wikipedia.org/wiki/Yatzy that shows that pipeline construction is normal Go code.
pkg/beam Package beam is an implementation of the Apache Beam (https://beam.apache.org) programming model in Go.
pkg/beam/artifact Package artifact contains utilities for staging and retrieving artifacts.
pkg/beam/artifact/gcsproxy Package gcsproxy contains artifact staging and retrieval servers backed by GCS.
pkg/beam/core/funcx Package funcx contains functions and types used to perform type analysis of Beam functions.
pkg/beam/core/graph Package graph is the internal representation of the Beam execution plan.
pkg/beam/core/graph/coder Package coder contains coder representation and utilities.
pkg/beam/core/graph/mtime Package mtime contains a millisecond representation of time.
pkg/beam/core/graph/window Package window contains window representation, windowing strategies and utilities.
pkg/beam/core/metrics Package metrics implements the Beam metrics API, described at http://s.apache.org/beam-metrics-api Metrics in the Beam model are uniquely identified by a namespace, a name, and the PTransform context in which they are used.
pkg/beam/core/runtime Package runtime contains runtime hooks and utilities for pipeline options and type registration.
pkg/beam/core/runtime/coderx Package coderx contains coders for primitive types that aren't included in the beam model.
pkg/beam/core/runtime/exec Package exec contains runtime plan representation and execution.
pkg/beam/core/runtime/exec/optimized Package optimized contains type-specialized shims for faster execution.
pkg/beam/core/runtime/genx Package genx is a convenience package to better support the code generator.
pkg/beam/core/runtime/graphx Package graphx provides facilities to help with the serialization of pipelines into a serializable graph structure suitable for the worker.
pkg/beam/core/runtime/graphx/schema Package schema contains utility functions for relating Go types and Beam Schemas.
pkg/beam/core/runtime/graphx/v1 Package v1 is a generated protocol buffer package.
pkg/beam/core/runtime/harness Package harness implements the SDK side of the Beam FnAPI.
pkg/beam/core/runtime/harness/init Package init contains the harness initialization code defined by the FnAPI.
pkg/beam/core/runtime/harness/session Package session is a generated protocol buffer package.
pkg/beam/core/runtime/metricsx
pkg/beam/core/runtime/pipelinex Package pipelinex contains utilities for manipulating Beam proto pipelines.
pkg/beam/core/runtime/xlangx
pkg/beam/core/sdf Package contains interfaces used specifically for splittable DoFns.
pkg/beam/core/typex Package typex contains full type representation for PCollections and DoFns, and utilities for type checking.
pkg/beam/core/util/dot Package dot produces DOT graphs from Beam graph representations.
pkg/beam/core/util/hooks Package hooks allows runners to tailor execution of the worker harness.
pkg/beam/core/util/ioutilx Package ioutilx contains additional io utilities.
pkg/beam/core/util/jsonx Package jsonx contains utilities for working with JSON encoded data.
pkg/beam/core/util/protox Package protox contains utilities for working with protobufs.
pkg/beam/core/util/reflectx Package reflectx contains a set of reflection utilities and well-known types.
pkg/beam/core/util/stringx Package stringx contains utilities for working with strings.
pkg/beam/core/util/symtab Package symtab allows reading low-level symbol information from the symbol table.
pkg/beam/internal/errors Package errors contains functionality for creating and wrapping errors with improved formatting compared to the standard Go error functionality.
pkg/beam/io/avroio Package avroio contains transforms for reading and writing avro files.
pkg/beam/io/bigqueryio Package bigqueryio provides transformations and utilities to interact with Google BigQuery.
pkg/beam/io/databaseio Package databaseio provides transformations and utilities to interact with generic database database/sql API.
pkg/beam/io/datastoreio Package datastoreio provides transformations and utilities to interact with Google Datastore.
pkg/beam/io/filesystem Package filesystem contains an extensible file system abstraction.
pkg/beam/io/filesystem/gcs Package gcs contains a Google Cloud Storage (GCS) implementation of the Beam file system.
pkg/beam/io/filesystem/local Package local contains a local file implementation of the Beam file system.
pkg/beam/io/filesystem/memfs Package memfs contains a in-memory Beam filesystem.
pkg/beam/io/pubsubio Package pubsubio provides access to PubSub on Dataflow streaming.
pkg/beam/io/pubsubio/v1 Package v1 is a generated protocol buffer package.
pkg/beam/io/rtrackers/offsetrange Package offsetrange defines a restriction and restriction tracker for offset ranges.
pkg/beam/io/synthetic Package synthetic contains transforms for creating synthetic pipelines.
pkg/beam/io/textio Package textio contains transforms for reading and writing text files.
pkg/beam/log Package log contains a re-targetable context-aware logging system.
pkg/beam/model Package model contains the portable Beam model contracts.
pkg/beam/model/fnexecution_v1
pkg/beam/model/jobmanagement_v1
pkg/beam/model/pipeline_v1
pkg/beam/options/gcpopts Package gcpopts contains shared options for Google Cloud Platform.
pkg/beam/options/jobopts Package jobopts contains shared options for job submission.
pkg/beam/provision Package provision contains utilities for obtaining runtime provision, information -- such as pipeline options.
pkg/beam/runners/dataflow Package dataflow contains the Dataflow runner for submitting pipelines to Google Cloud Dataflow.
pkg/beam/runners/dataflow/dataflowlib Package dataflowlib translates a Beam pipeline model to the Dataflow API job model, for submission to Google Cloud Dataflow.
pkg/beam/runners/direct Package direct contains the direct runner for running single-bundle pipelines in the current process.
pkg/beam/runners/dot Package dot is a Beam runner that "runs" a pipeline by producing a DOT graph of the execution plan.
pkg/beam/runners/flink Package flink contains the Flink runner.
pkg/beam/runners/session
pkg/beam/runners/spark Package spark contains the Spark runner.
pkg/beam/runners/universal Package universal contains a general-purpose runner that can submit jobs to any portable Beam runner.
pkg/beam/runners/universal/extworker Package extworker provides an external worker service and related utilities.
pkg/beam/runners/universal/runnerlib Package runnerlib contains utilities for submitting Go pipelines to a Beam model runner.
pkg/beam/runners/vet Package vet is a Beam runner that "runs" a pipeline by producing generated code to avoid symbol table lookups and reflection in pipeline execution.
pkg/beam/runners/vet/testpipeline Package testpipeline exports small test pipelines for testing the vet runner.
pkg/beam/testing/passert Package passert contains verification transformations for testing pipelines.
pkg/beam/testing/ptest Package ptest contains utilities for pipeline unit testing.
pkg/beam/transforms/filter Package filter contains transformations for removing pipeline elements based on various conditions.
pkg/beam/transforms/stats Package stats contains transforms for statistical processing.
pkg/beam/transforms/top Package top contains transformations for finding the smallest (or largest) N elements based on arbitrary orderings.
pkg/beam/util/errorx Package errorx contains utilities for handling errors.
pkg/beam/util/execx Package execx contains wrappers and utilities for the exec package.
pkg/beam/util/gcsx Package gcsx contains utilities for working with Google Cloud Storage (GCS).
pkg/beam/util/grpcx Package grpcx contains utilities for working with gRPC.
pkg/beam/util/pubsubx Package pubsubx contains utilities for working with Google PubSub.
pkg/beam/util/shimx Package shimx specifies the templates for generating type assertion shims for Apache Beam Go SDK pipelines.
pkg/beam/util/starcgenx Package starcgenx is a Static Analysis Type Assertion shim and Registration Code Generator which provides an extractor to extract types from a package, in order to generate approprate shimsr a package so code can be generated for it.
pkg/beam/util/syscallx Package syscallx provides system call utilities that attempt to hide platform differences.
pkg/beam/x/beamx Package beamx is a convenience package for beam.
pkg/beam/x/debug Package debug contains pipeline components that may help in debugging pipeline issues.
pkg/beam/x/hooks/perf Package perf is to add performance measuring hooks to a runner, such as cpu, heap, or trace profiles.
test/integration The integration driver provides a suite of tests to run against a registered runner.
test/integration/primitives
test/integration/synthetic Package synthetic contains pipelines for testing synthetic steps and sources.
test/integration/wordcount Package wordcount contains transforms for wordcount.
test/load
test/load/cogbk
test/load/combine
test/load/group_by_key
test/load/pardo
test/load/sideinput
test/regression Package regression contains pipeline regression tests.
test/regression/coders/fromyaml fromyaml generates a resource file from the standard_coders.yaml file for use in these coder regression tests.
test/validatesrunner Package validatesrunner contains Validates Runner tests, which are a type of integration test that execute short pipelines on various runners to validate runner behavior.