docs(bigquery): add routine preview samples (#5356)

* docs(bigquery): add routine preview samples

This PR also includes minor docstring fixes for update table

Author: shollyman

bigquery/snippets_preview/routine/bigquery_create_routine.go

@@ -0,0 +1,85 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routine
+
+// [START bigquery_create_routine_preview]
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
+	"cloud.google.com/go/bigquery/v2/apiv2_client"
+
+	"github.com/googleapis/gax-go/v2/apierror"
+
+	"google.golang.org/grpc/codes"
+	"google.golang.org/protobuf/encoding/protojson"
+)
+
+// createRoutine demonstrates creation of a new routine that represents a SQL User Defined Function (UDF).
+func createRoutine(client *apiv2_client.Client, w io.Writer, projectID, datasetID, routineID string) error {
+	// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
+	// an aggregate client.
+	//
+	// projectID := "my-project-id"
+	// datasetID := "mydataset"
+	// routineID := "myroutine"
+	ctx := context.Background()
+
+	// Construct a request, populating some of the available configuration
+	// settings.
+	req := &bigquerypb.InsertRoutineRequest{
+		ProjectId: projectID,
+		DatasetId: datasetID,
+		Routine: &bigquerypb.Routine{
+			RoutineReference: &bigquerypb.RoutineReference{
+				ProjectId: projectID,
+				DatasetId: datasetID,
+				RoutineId: routineID,
+			},
+			RoutineType: bigquerypb.Routine_SCALAR_FUNCTION,
+			Arguments: []*bigquerypb.Routine_Argument{
+				{
+					Name: "x",
+					DataType: &bigquerypb.StandardSqlDataType{
+						TypeKind: bigquerypb.StandardSqlDataType_INT64,
+					},
+				},
+			},
+			ReturnType: &bigquerypb.StandardSqlDataType{
+				TypeKind: bigquerypb.StandardSqlDataType_INT64,
+			},
+			DefinitionBody: "x * 3",
+		},
+	}
+	resp, err := client.InsertRoutine(ctx, req)
+	if err != nil {
+		// Examine the error structure more deeply.
+		if apierr, ok := apierror.FromError(err); ok {
+			if status := apierr.GRPCStatus(); status.Code() == codes.AlreadyExists {
+				// The error was due to the routine already existing.  For this sample
+				// we don't consider that a failure, so return nil.
+				return nil
+			}
+		}
+		return fmt.Errorf("InsertRoutine: %w", err)
+	}
+	// Print the JSON representation of the response to the provided writer.
+	fmt.Fprintf(w, "Response from insert: %s", protojson.Format(resp))
+	return nil
+}
+
+// [END bigquery_create_routine_preview]

bigquery/snippets_preview/routine/bigquery_delete_routine.go

@@ -0,0 +1,60 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routine
+
+// [START bigquery_delete_routine_preview]
+import (
+	"context"
+	"fmt"
+
+	"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
+	"cloud.google.com/go/bigquery/v2/apiv2_client"
+	"github.com/googleapis/gax-go/v2/apierror"
+
+	"google.golang.org/grpc/codes"
+)
+
+// deleteRoutine demonstrates deleting a routine from BigQuery.
+func deleteRoutine(client *apiv2_client.Client, projectID, datasetID, routineID string) error {
+	// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
+	// an aggregate client.
+	//
+	// projectID := "my-project-id"
+	// datasetID := "mydataset"
+	// routineID := "myroutine"
+	ctx := context.Background()
+
+	req := &bigquerypb.DeleteRoutineRequest{
+		ProjectId: projectID,
+		DatasetId: datasetID,
+		RoutineId: routineID,
+	}
+
+	// Deleting a routine doesn't return information, but it may produce an error.
+	if err := client.DeleteRoutine(ctx, req); err != nil {
+		if apierr, ok := apierror.FromError(err); ok {
+			if status := apierr.GRPCStatus(); status.Code() == codes.NotFound {
+				// The error indicates the routine isn't present.  Possibly another process removed
+				// the routine, or perhaps there was a partial failure and this was handled via automatic retry.
+				// In any case, treat this as a success.
+				return nil
+			}
+		}
+		return fmt.Errorf("DeleteRoutine: %w", err)
+	}
+	return nil
+}
+
+// [END bigquery_delete_routine_preview]

bigquery/snippets_preview/routine/bigquery_list_routines.go

@@ -0,0 +1,70 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routine
+
+// [START bigquery_list_routines_preview]
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
+	"cloud.google.com/go/bigquery/v2/apiv2_client"
+
+	"google.golang.org/api/iterator"
+	"google.golang.org/protobuf/types/known/wrapperspb"
+)
+
+// listRoutines demonstrates iterating through the routines within a specified dataset.
+func listRoutines(client *apiv2_client.Client, w io.Writer, projectID, datasetID string) error {
+	// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
+	// an aggregate client.
+	//
+	// projectID := "my-project-id"
+	// datasetID := "mydataset"
+	ctx := context.Background()
+
+	req := &bigquerypb.ListRoutinesRequest{
+		ProjectId: projectID,
+		DatasetId: datasetID,
+		// MaxResults is the per-page threshold (aka page size).  Generally you should only
+		// worry about setting this if you're executing code in a memory constrained environment
+		// and don't want to process large pages of results.  BigQuery will select a reasonable
+		// page size automatically.
+		MaxResults: &wrapperspb.UInt32Value{Value: 100},
+	}
+
+	// ListRoutines returns an iterator so users don't have to manage pagination when processing
+	// the results.
+	it := client.ListRoutines(ctx, req)
+
+	// Process data from the iterator one result at a time.  The internal implementation of the iterator
+	// is fetching pages at a time.
+	for {
+		routine, err := it.Next()
+		if err == iterator.Done {
+			// We're reached the end of the iteration, break the loop.
+			break
+		}
+		if err != nil {
+			return fmt.Errorf("iterator errored: %w", err)
+		}
+		// Print basic information to the provided writer.
+		fmt.Fprintf(w, "routine %q reports type %q\n", routine.GetRoutineReference().GetRoutineId(), routine.GetRoutineType().String())
+	}
+	return nil
+}
+
+// [END bigquery_list_routines_preview]

bigquery/snippets_preview/routine/bigquery_update_routine.go

@@ -0,0 +1,84 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package routine
+
+// [START bigquery_update_routine_preview]
+import (
+	"context"
+	"fmt"
+	"io"
+
+	"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
+	"cloud.google.com/go/bigquery/v2/apiv2_client"
+	"github.com/googleapis/gax-go/v2/apierror"
+	"github.com/googleapis/gax-go/v2/callctx"
+
+	"google.golang.org/grpc/codes"
+)
+
+// updateRoutine demonstrates making partial updates to an existing routine's metadata.
+func updateRoutine(client *apiv2_client.Client, w io.Writer, projectID, datasetID, routineID string) error {
+	// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
+	// an aggregate client.
+	//
+	// projectID := "my-project-id"
+	// datasetID := "mydataset"
+	// routineID := "myroutine"
+	ctx := context.Background()
+
+	// Fetch the existing routine metadata prior to making any modifications.
+	// This allows us to use optimistic concurrency controls to avoid overwriting
+	// other changes.
+	meta, err := client.GetRoutine(ctx, &bigquerypb.GetRoutineRequest{
+		ProjectId: projectID,
+		DatasetId: datasetID,
+		RoutineId: routineID,
+	})
+	if err != nil {
+		return fmt.Errorf("GetRoutine: %w", err)
+	}
+
+	// Construct an update request, copying the current state of the
+	// request since we'll be doing a full update.
+	req := &bigquerypb.UpdateRoutineRequest{
+		ProjectId: projectID,
+		DatasetId: datasetID,
+		RoutineId: routineID,
+		Routine:   meta,
+	}
+	// Modify the request to change the description.
+	req.GetRoutine().Description = "Updated description."
+
+	// Now, use the ETag from the original metadata to guard against conflicting writes.
+	// The callctx package let's us inject headers in a transport agnostic fashion (gRPC or HTTP).
+	patchCtx := callctx.SetHeaders(ctx, "if-match", meta.GetEtag())
+	resp, err := client.UpdateRoutine(patchCtx, req)
+	if err != nil {
+		if apierr, ok := apierror.FromError(err); ok {
+			if status := apierr.GRPCStatus(); status.Code() == codes.FailedPrecondition {
+				// The error was due to precondition failing (the If-Match constraint).
+				// For this example we're not doing anything overly stateful with the dataset
+				// so we simply return a more readable outer error.
+				return fmt.Errorf("routine etag changed between Get and Update: %w", err)
+			}
+		}
+		return fmt.Errorf("UpdateRoutine: %w", err)
+	}
+	// Print the values we expected to be modified.
+	fmt.Fprintf(w, "Description: %s\n", resp.GetDescription())
+	return nil
+}
+
+// [END bigquery_update_routine_preview]

bigquery/snippets_preview/routine/integration_test.go

@@ -0,0 +1,95 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     https://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package routine provides some basic snippet examples for working with routines using
+// the preview BigQuery Cloud Client Library.
+package routine
+
+import (
+	"context"
+	"fmt"
+	"io"
+	"testing"
+	"time"
+
+	"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
+	"cloud.google.com/go/bigquery/v2/apiv2_client"
+	"github.com/GoogleCloudPlatform/golang-samples/internal/testutil"
+)
+
+const testTimeout = 30 * time.Second
+const testLocation = "us-west1"
+
+func TestRoutineSnippet(t *testing.T) {
+	tc := testutil.SystemTest(t)
+	names := []string{"gRPC", "REST"}
+
+	for _, name := range names {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+			ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
+			defer cancel()
+			// Setup client.
+			var client *apiv2_client.Client
+			var err error
+			if name == "gRPC" {
+				client, err = apiv2_client.NewClient(ctx)
+			} else {
+				client, err = apiv2_client.NewRESTClient(ctx)
+			}
+			if err != nil {
+				t.Fatalf("client creation failed: %v", err)
+			}
+			defer client.Close()
+
+			// Create a test dataset.
+			projID := tc.ProjectID
+			dsID := fmt.Sprintf("snippettesting_routines_%s_%d", name, time.Now().UnixNano())
+
+			_, err = client.InsertDataset(ctx, &bigquerypb.InsertDatasetRequest{
+				ProjectId: projID,
+				Dataset: &bigquerypb.Dataset{
+					DatasetReference: &bigquerypb.DatasetReference{
+						ProjectId: projID,
+						DatasetId: dsID,
+					},
+					Location: testLocation,
+				},
+			})
+			if err != nil {
+				t.Fatalf("couldn't create test dataset: %v", err)
+			}
+			defer client.DeleteDataset(ctx, &bigquerypb.DeleteDatasetRequest{
+				ProjectId:      projID,
+				DatasetId:      dsID,
+				DeleteContents: true,
+			})
+
+			routineID := fmt.Sprintf("routinesnippet_%s_%d", name, time.Now().UnixNano())
+
+			if err := createRoutine(client, io.Discard, projID, dsID, routineID); err != nil {
+				t.Fatalf("createRoutine(%q,%q,%q): %v", projID, dsID, routineID, err)
+			}
+			if err := updateRoutine(client, io.Discard, projID, dsID, routineID); err != nil {
+				t.Fatalf("updateRoutine(%q,%q,%q): %v", projID, dsID, routineID, err)
+			}
+			if err := listRoutines(client, io.Discard, projID, dsID); err != nil {
+				t.Fatalf("listRoutines(%q,%q): %v", projID, dsID, err)
+			}
+			if err := deleteRoutine(client, projID, dsID, routineID); err != nil {
+				t.Fatalf("deleteRoutine(%q,%q,%q): %v", projID, dsID, routineID, err)
+			}
+		})
+	}
+}