Skip to content

Commit af70992

Browse files
shollymanshollyman
authored
docs(bigquery): add more preview samples (#5366)
* docs(bigquery): add more preview samples
1 parent 8b84ce0 commit af70992

15 files changed

+872
-0
lines changed

‎bigquery/snippets_preview/dataset/bigquery_get_dataset.go

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package dataset
16+
17+
// [START bigquery_get_dataset_preview]
18+
import (
19+
"context"
20+
"fmt"
21+
"io"
22+
23+
"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
24+
"cloud.google.com/go/bigquery/v2/apiv2_client"
25+
"google.golang.org/protobuf/encoding/protojson"
26+
)
27+
28+
// getDataset demonstrates fetching dataset information.
29+
func getDataset(client *apiv2_client.Client, w io.Writer, projectID, datasetID string) error {
30+
// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
31+
// an aggregate client.
32+
//
33+
// projectID := "my-project-id"
34+
// datasetID := "mydataset"
35+
ctx := context.Background()
36+
37+
req := &bigquerypb.GetDatasetRequest{
38+
ProjectId: projectID,
39+
DatasetId: datasetID,
40+
// Dataset supports fetching a subset of the dataset information depending
41+
// on whether you're interested in security information, basic metadata, or
42+
// both. For the example, we'll request all the information.
43+
DatasetView: bigquerypb.GetDatasetRequest_FULL,
44+
}
45+
46+
resp, err := client.GetDataset(ctx, req)
47+
if err != nil {
48+
return fmt.Errorf("GetDataset: %w", err)
49+
}
50+
51+
// Print some of the information about the dataset to the provided writer.
52+
fmt.Fprintf(w, "Dataset %q has description %q\n",
53+
resp.GetDatasetReference().GetDatasetId(),
54+
resp.GetDescription())
55+
// Alternately, use the protojson package to print a more complete representation
56+
// of the dataset using a basic JSON mapping:
57+
fmt.Fprintf(w, "Dataset JSON representation:\n%s\n", protojson.Format(resp))
58+
return nil
59+
}
60+
61+
// [END bigquery_get_dataset_preview]

‎bigquery/snippets_preview/dataset/integration_test.go

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,9 @@ func TestDatasetSnippets(t *testing.T) {
5656
if err := createDataset(client, io.Discard, projID, dsID); err != nil {
5757
t.Fatalf("createDataset(%q,%q): %v", projID, dsID, err)
5858
}
59+
if err := getDataset(client, io.Discard, projID, dsID); err != nil {
60+
t.Fatalf("getDataset(%q,%q): %v", projID, dsID, err)
61+
}
5962
if err := updateDataset(client, io.Discard, projID, dsID); err != nil {
6063
t.Fatalf("updateDataset(%q,%q): %v", projID, dsID, err)
6164
}

‎bigquery/snippets_preview/job/bigquery_list_jobs.go

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package job
16+
17+
// [START bigquery_list_jobs_preview]
18+
import (
19+
"context"
20+
"fmt"
21+
"io"
22+
23+
"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
24+
"cloud.google.com/go/bigquery/v2/apiv2_client"
25+
26+
"google.golang.org/api/iterator"
27+
)
28+
29+
// listJobs demonstrates iterating through job metadata.
30+
func listJobs(client *apiv2_client.Client, w io.Writer, projectID string) error {
31+
// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
32+
// an aggregate client.
33+
//
34+
// projectID := "my-project-id"
35+
ctx := context.Background()
36+
37+
req := &bigquerypb.ListJobsRequest{
38+
ProjectId: projectID,
39+
// Only list pending or running jobs.
40+
StateFilter: []bigquerypb.ListJobsRequest_StateFilter{
41+
bigquerypb.ListJobsRequest_PENDING,
42+
bigquerypb.ListJobsRequest_RUNNING,
43+
},
44+
}
45+
46+
// ListJobs returns an iterator so users don't have to manage pagination when processing
47+
// the results.
48+
it := client.ListJobs(ctx, req)
49+
50+
// Process data from the iterator one result at a time, and stop after we
51+
// process a fixed number of jobs. While the number of inflight
52+
// (pending or running) jobs may be more reasonable, listing all jobs can yield
53+
// a potentially very large number of results.
54+
maxJobs := 10
55+
for numJobs := 0; numJobs < maxJobs; numJobs++ {
56+
job, err := it.Next()
57+
if err == iterator.Done {
58+
// We're reached the end of the iteration, break the loop.
59+
break
60+
}
61+
if err != nil {
62+
return fmt.Errorf("iterator errored: %w", err)
63+
}
64+
// Print basic information to the provided writer.
65+
fmt.Fprintf(w, "job %q in location %q is in state %q\n",
66+
job.GetJobReference().GetJobId(),
67+
job.GetJobReference().GetLocation(),
68+
job.GetState())
69+
}
70+
return nil
71+
}
72+
73+
// [END bigquery_list_jobs_preview]

‎bigquery/snippets_preview/job/integration_test.go

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
// Package job provides some basic snippet examples for working with job
16+
// metadata using the preview BigQuery Cloud Client Library.
17+
package job
18+
19+
import (
20+
"context"
21+
"io"
22+
"testing"
23+
"time"
24+
25+
"cloud.google.com/go/bigquery/v2/apiv2_client"
26+
"github.com/GoogleCloudPlatform/golang-samples/internal/testutil"
27+
)
28+
29+
const testTimeout = 30 * time.Second
30+
31+
func TestJobSnippet(t *testing.T) {
32+
tc := testutil.SystemTest(t)
33+
names := []string{"gRPC", "REST"}
34+
35+
for _, name := range names {
36+
t.Run(name, func(t *testing.T) {
37+
t.Parallel()
38+
ctx, cancel := context.WithTimeout(context.Background(), testTimeout)
39+
defer cancel()
40+
// Setup client.
41+
var client *apiv2_client.Client
42+
var err error
43+
if name == "gRPC" {
44+
client, err = apiv2_client.NewClient(ctx)
45+
} else {
46+
client, err = apiv2_client.NewRESTClient(ctx)
47+
}
48+
if err != nil {
49+
t.Fatalf("client creation failed: %v", err)
50+
}
51+
defer client.Close()
52+
53+
projID := tc.ProjectID
54+
if err := listJobs(client, io.Discard, projID); err != nil {
55+
t.Fatalf("listJobs(%q): %v", projID, err)
56+
}
57+
})
58+
}
59+
}

‎bigquery/snippets_preview/model/bigquery_delete_model.go

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package model
16+
17+
// [START bigquery_delete_model_preview]
18+
import (
19+
"context"
20+
"fmt"
21+
22+
"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
23+
"cloud.google.com/go/bigquery/v2/apiv2_client"
24+
"github.com/googleapis/gax-go/v2/apierror"
25+
26+
"google.golang.org/grpc/codes"
27+
)
28+
29+
// deleteModel demonstrates deleting a ML model from BigQuery.
30+
func deleteModel(client *apiv2_client.Client, projectID, datasetID, modelID string) error {
31+
// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
32+
// an aggregate client.
33+
//
34+
// projectID := "my-project-id"
35+
// datasetID := "mydataset"
36+
// modelID := "mymodel"
37+
ctx := context.Background()
38+
39+
req := &bigquerypb.DeleteModelRequest{
40+
ProjectId: projectID,
41+
DatasetId: datasetID,
42+
ModelId: modelID,
43+
}
44+
45+
// Deleting a model doesn't return information, but it may produce an error.
46+
if err := client.DeleteModel(ctx, req); err != nil {
47+
if apierr, ok := apierror.FromError(err); ok {
48+
if status := apierr.GRPCStatus(); status.Code() == codes.NotFound {
49+
// The error indicates the model isn't present. Possibly another process removed
50+
// the model, or perhaps there was a partial failure and this was handled via automatic retry.
51+
// In any case, treat this as a success.
52+
return nil
53+
}
54+
}
55+
return fmt.Errorf("DeleteModel: %w", err)
56+
}
57+
return nil
58+
}
59+
60+
// [END bigquery_delete_model_preview]

‎bigquery/snippets_preview/model/bigquery_get_model.go

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package model
16+
17+
// [START bigquery_get_model_preview]
18+
import (
19+
"context"
20+
"fmt"
21+
"io"
22+
23+
"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
24+
"cloud.google.com/go/bigquery/v2/apiv2_client"
25+
"google.golang.org/protobuf/encoding/protojson"
26+
)
27+
28+
// getModel demonstrates fetching ML model information.
29+
func getModel(client *apiv2_client.Client, w io.Writer, projectID, datasetID, modelID string) error {
30+
// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
31+
// an aggregate client.
32+
//
33+
// projectID := "my-project-id"
34+
// datasetID := "mydataset"
35+
// modelID := "mymodel"
36+
ctx := context.Background()
37+
38+
req := &bigquerypb.GetModelRequest{
39+
ProjectId: projectID,
40+
DatasetId: datasetID,
41+
ModelId: modelID,
42+
}
43+
44+
resp, err := client.GetModel(ctx, req)
45+
if err != nil {
46+
return fmt.Errorf("GetModel: %w", err)
47+
}
48+
49+
// Print some of the information about the model to the provided writer.
50+
fmt.Fprintf(w, "Model %q has description %q\n",
51+
resp.GetModelReference().GetModelId(),
52+
resp.GetDescription())
53+
// Alternately, use the protojson package to print a more complete representation
54+
// of the model using a basic JSON mapping:
55+
fmt.Fprintf(w, "Model JSON representation:\n%s\n", protojson.Format(resp))
56+
return nil
57+
}
58+
59+
// [END bigquery_get_model_preview]

‎bigquery/snippets_preview/model/bigquery_list_models.go

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// Copyright 2025 Google LLC
2+
//
3+
// Licensed under the Apache License, Version 2.0 (the "License");
4+
// you may not use this file except in compliance with the License.
5+
// You may obtain a copy of the License at
6+
//
7+
// https://www.apache.org/licenses/LICENSE-2.0
8+
//
9+
// Unless required by applicable law or agreed to in writing, software
10+
// distributed under the License is distributed on an "AS IS" BASIS,
11+
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
// See the License for the specific language governing permissions and
13+
// limitations under the License.
14+
15+
package model
16+
17+
// [START bigquery_list_models_preview]
18+
import (
19+
"context"
20+
"fmt"
21+
"io"
22+
23+
"cloud.google.com/go/bigquery/v2/apiv2/bigquerypb"
24+
"cloud.google.com/go/bigquery/v2/apiv2_client"
25+
26+
"google.golang.org/api/iterator"
27+
"google.golang.org/protobuf/types/known/wrapperspb"
28+
)
29+
30+
// listModels demonstrates iterating through BigQuery ML models.
31+
func listModels(client *apiv2_client.Client, w io.Writer, projectID, datasetID string) error {
32+
// client can be instantiated per-RPC service, or use cloud.google.com/go/bigquery/v2/apiv2_client to create
33+
// an aggregate client.
34+
//
35+
// projectID := "my-project-id"
36+
ctx := context.Background()
37+
38+
req := &bigquerypb.ListModelsRequest{
39+
ProjectId: projectID,
40+
DatasetId: datasetID,
41+
// MaxResults is the per-page threshold (aka page size). Generally you should only
42+
// worry about setting this if you're executing code in a memory constrained environment
43+
// and don't want to process large pages of results.
44+
MaxResults: &wrapperspb.UInt32Value{Value: 100},
45+
}
46+
47+
// ListJobs returns an iterator so users don't have to manage pagination when processing
48+
// the results.
49+
it := client.ListModels(ctx, req)
50+
51+
// Process data from the iterator one result at a time. The internal implementation of the iterator
52+
// is fetching pages at a time.
53+
for {
54+
model, err := it.Next()
55+
if err == iterator.Done {
56+
// We're reached the end of the iteration, break the loop.
57+
break
58+
}
59+
if err != nil {
60+
return fmt.Errorf("iterator errored: %w", err)
61+
}
62+
// Print basic information to the provided writer.
63+
fmt.Fprintf(w, "model %q is of type %q\n",
64+
model.GetModelReference().GetModelId(),
65+
model.GetModelType())
66+
}
67+
return nil
68+
}
69+
70+
// [END bigquery_list_models_preview]

0 commit comments

Comments
 (0)