diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/DataGovernanceTagsInfo.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/DataGovernanceTagsInfo.java new file mode 100644 index 000000000000..6868cdfba8be --- /dev/null +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/DataGovernanceTagsInfo.java @@ -0,0 +1,139 @@ +/* + * Copyright 2026 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 + * + * http://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 com.google.cloud.bigquery; + +import com.google.api.client.util.Data; +import com.google.api.services.bigquery.model.TableFieldSchema; +import com.google.auto.value.AutoValue; +import com.google.common.collect.ImmutableMap; +import java.io.Serializable; +import java.util.Map; +import org.jspecify.annotations.NullMarked; +import org.jspecify.annotations.Nullable; + +/** + * Represents data governance tags attached to a BigQuery table schema {@link Field} for + * column-level access control and dynamic data masking. + * + *

This wrapper distinguishes an unset field ({@code null} on {@link Field}, which preserves + * existing column tags during a {@code Tables.patch} request) from an empty wrapper (for example, + * {@code DataGovernanceTagsInfo.newBuilder().build()}, which serializes as an empty object to clear + * existing tags from the column). + * + * @see Control access to + * columns with data governance tags + */ +@AutoValue +@NullMarked +public abstract class DataGovernanceTagsInfo implements Serializable { + + private static final long serialVersionUID = 1L; + + abstract ImmutableMap getDataGovernanceTagsImmut(); + + /** + * Returns the data governance tags attached to the field, keyed by namespaced tag key (for + * example, {@code "myProject/pii"}) and mapped to the tag value short name (for example, {@code + * "sensitive"}). Returns an empty map when representing an empty {@code DataGovernanceTagsInfo} + * object used to clear existing column tags. + * + * @return immutable map of data governance tag keys to values + */ + public Map getDataGovernanceTags() { + return getDataGovernanceTagsImmut(); + } + + /** Returns a builder pre-populated with the contents of this {@code DataGovernanceTagsInfo}. */ + public abstract Builder toBuilder(); + + /** Builder for {@code DataGovernanceTagsInfo}. */ + @AutoValue.Builder + public abstract static class Builder { + + abstract Builder setDataGovernanceTagsImmut( + ImmutableMap dataGovernanceTagsImmut); + + /** + * Sets the data governance tags map for the field. Pass an empty map (or build directly from + * {@link #newBuilder()}) to clear existing data governance tags from a column during a {@code + * Tables.patch} schema update. + * + * @param dataGovernanceTags non-null map of namespaced tag keys to tag value short names + * @return this builder + */ + public Builder setDataGovernanceTags(Map dataGovernanceTags) { + return setDataGovernanceTagsImmut(ImmutableMap.copyOf(dataGovernanceTags)); + } + + /** Creates a {@code DataGovernanceTagsInfo} object. */ + public abstract DataGovernanceTagsInfo build(); + } + + /** + * Returns a new builder initialized with an empty data governance tags map. Building without + * setting tags produces an empty {@code DataGovernanceTagsInfo} object, which clears existing + * tags on a column when sent in a {@code Tables.patch} request. + * + * @return a new {@code Builder} + */ + public static Builder newBuilder() { + return new AutoValue_DataGovernanceTagsInfo.Builder() + .setDataGovernanceTagsImmut(ImmutableMap.of()); + } + + /** + * Creates a {@code DataGovernanceTagsInfo} containing the given data governance tags map. + * + * @param dataGovernanceTags non-null map of namespaced tag keys to tag value short names + * @return a {@code DataGovernanceTagsInfo} instance + */ + public static DataGovernanceTagsInfo of(Map dataGovernanceTags) { + return newBuilder().setDataGovernanceTags(dataGovernanceTags).build(); + } + + /** + * Converts this instance to the underlying REST API {@link + * TableFieldSchema.DataGovernanceTagsInfo} model. Omits the inner map when empty so JSON + * serialization emits {@code "dataGovernanceTagsInfo": {}} for clearing column tags on patch. + */ + TableFieldSchema.DataGovernanceTagsInfo toPb() { + TableFieldSchema.DataGovernanceTagsInfo tagInfoPb = + new TableFieldSchema.DataGovernanceTagsInfo(); + if (!getDataGovernanceTags().isEmpty()) { + tagInfoPb.setDataGovernanceTags(getDataGovernanceTags()); + } + return tagInfoPb; + } + + /** + * Creates a {@code DataGovernanceTagsInfo} from the underlying REST API {@link + * TableFieldSchema.DataGovernanceTagsInfo} model, or returns {@code null} if {@code tagInfoPb} is + * {@code null} or JSON null. + */ + static @Nullable DataGovernanceTagsInfo fromPb( + TableFieldSchema.@Nullable DataGovernanceTagsInfo tagInfoPb) { + if (tagInfoPb == null || Data.isNull(tagInfoPb)) { + return null; + } + Builder builder = newBuilder(); + if (tagInfoPb.getDataGovernanceTags() != null + && !Data.isNull(tagInfoPb.getDataGovernanceTags())) { + builder.setDataGovernanceTags(tagInfoPb.getDataGovernanceTags()); + } + return builder.build(); + } +} diff --git a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Field.java b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Field.java index e0204aae807c..fac904058da4 100644 --- a/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Field.java +++ b/java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/Field.java @@ -30,6 +30,7 @@ import java.io.Serializable; import java.util.List; import java.util.Objects; +import org.jspecify.annotations.Nullable; /** * Google BigQuery Table schema field. A table field has a name, a type, a mode and possibly a @@ -67,6 +68,7 @@ public TableFieldSchema apply(Field field) { private final String defaultValueExpression; private final String collation; private final FieldElementType rangeElementType; + private final DataGovernanceTagsInfo dataGovernanceTagsInfo; /** * Mode for a BigQuery Table field. {@link Mode#NULLABLE} fields can be set to {@code null}, @@ -94,6 +96,7 @@ public static final class Builder { private String defaultValueExpression; private String collation; private FieldElementType rangeElementType; + private DataGovernanceTagsInfo dataGovernanceTagsInfo; private Builder() {} @@ -111,6 +114,7 @@ private Builder(Field field) { this.defaultValueExpression = field.defaultValueExpression; this.collation = field.collation; this.rangeElementType = field.rangeElementType; + this.dataGovernanceTagsInfo = field.dataGovernanceTagsInfo; } /** @@ -318,6 +322,19 @@ public Builder setRangeElementType(FieldElementType rangeElementType) { return this; } + /** + * Optional. Sets the data governance tags info for the field, used for column-level access + * control and dynamic data masking. Leave {@code null} (unset) during a {@code Tables.patch} + * update to preserve existing tags on the column, or pass an empty {@link + * DataGovernanceTagsInfo} (for example, {@code DataGovernanceTagsInfo.newBuilder().build()}) to + * clear existing tags from the column. + */ + public Builder setDataGovernanceTagsInfo( + @Nullable DataGovernanceTagsInfo dataGovernanceTagsInfo) { + this.dataGovernanceTagsInfo = dataGovernanceTagsInfo; + return this; + } + /** Creates a {@code Field} object. */ public Field build() { return new Field(this); @@ -338,6 +355,7 @@ private Field(Builder builder) { this.defaultValueExpression = builder.defaultValueExpression; this.collation = builder.collation; this.rangeElementType = builder.rangeElementType; + this.dataGovernanceTagsInfo = builder.dataGovernanceTagsInfo; } /** Returns the field name. */ @@ -407,6 +425,11 @@ public FieldElementType getRangeElementType() { return rangeElementType; } + /** Returns the data governance tags info for the field, or {@code null} if not set. */ + public @Nullable DataGovernanceTagsInfo getDataGovernanceTagsInfo() { + return dataGovernanceTagsInfo; + } + /** * Returns the list of sub-fields if {@link #getType()} is a {@link LegacySQLTypeName#RECORD}. * Returns {@code null} otherwise. @@ -435,6 +458,7 @@ public String toString() { .add("defaultValueExpression", defaultValueExpression) .add("collation", collation) .add("rangeElementType", rangeElementType) + .add("dataGovernanceTagsInfo", dataGovernanceTagsInfo) .toString(); } @@ -452,7 +476,8 @@ public int hashCode() { timestampPrecision, defaultValueExpression, collation, - rangeElementType); + rangeElementType, + dataGovernanceTagsInfo); } @Override @@ -542,6 +567,9 @@ TableFieldSchema toPb() { if (rangeElementType != null) { fieldSchemaPb.setRangeElementType(rangeElementType.toPb()); } + if (dataGovernanceTagsInfo != null) { + fieldSchemaPb.setDataGovernanceTagsInfo(dataGovernanceTagsInfo.toPb()); + } return fieldSchemaPb; } @@ -584,6 +612,10 @@ static Field fromPb(TableFieldSchema fieldSchemaPb) { fieldBuilder.setRangeElementType( FieldElementType.fromPb(fieldSchemaPb.getRangeElementType())); } + if (fieldSchemaPb.getDataGovernanceTagsInfo() != null) { + fieldBuilder.setDataGovernanceTagsInfo( + DataGovernanceTagsInfo.fromPb(fieldSchemaPb.getDataGovernanceTagsInfo())); + } return fieldBuilder.build(); } } diff --git a/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/DataGovernanceTagsInfoTest.java b/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/DataGovernanceTagsInfoTest.java new file mode 100644 index 000000000000..8fd194ebd233 --- /dev/null +++ b/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/DataGovernanceTagsInfoTest.java @@ -0,0 +1,156 @@ +/* + * Copyright 2026 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 + * + * http://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 com.google.cloud.bigquery; + +import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertFalse; +import static org.junit.jupiter.api.Assertions.assertNull; +import static org.junit.jupiter.api.Assertions.assertThrows; +import static org.junit.jupiter.api.Assertions.assertTrue; + +import com.google.api.client.json.gson.GsonFactory; +import com.google.api.client.util.Data; +import com.google.api.services.bigquery.model.TableFieldSchema; +import com.google.common.collect.ImmutableMap; +import java.io.ByteArrayInputStream; +import java.io.ByteArrayOutputStream; +import java.io.ObjectInputStream; +import java.io.ObjectOutputStream; +import java.util.Collections; +import java.util.HashMap; +import java.util.Map; +import org.junit.jupiter.api.Test; + +class DataGovernanceTagsInfoTest { + + private static final Map TAGS = ImmutableMap.of("myProject/pii", "sensitive"); + private static final DataGovernanceTagsInfo TAGS_INFO = + DataGovernanceTagsInfo.newBuilder().setDataGovernanceTags(TAGS).build(); + + @Test + void testBuilderAndOf() { + assertEquals(TAGS, TAGS_INFO.getDataGovernanceTags()); + assertEquals(TAGS_INFO, DataGovernanceTagsInfo.of(TAGS)); + compareDataGovernanceTagsInfo(TAGS_INFO, TAGS_INFO.toBuilder().build()); + } + + @Test + void testDefensiveCopyAndImmutability() { + Map mutableInput = new HashMap<>(); + mutableInput.put("myProject/pii", "sensitive"); + DataGovernanceTagsInfo info = DataGovernanceTagsInfo.of(mutableInput); + mutableInput.put("myProject/other", "public"); + + assertEquals(TAGS, info.getDataGovernanceTags()); + assertThrows( + UnsupportedOperationException.class, + () -> info.getDataGovernanceTags().put("another/key", "value")); + } + + @Test + void testEmptyBuilderAndPatchClearingSemantics() throws Exception { + DataGovernanceTagsInfo emptyFromBuilder = DataGovernanceTagsInfo.newBuilder().build(); + DataGovernanceTagsInfo emptyFromMap = DataGovernanceTagsInfo.of(Collections.emptyMap()); + + assertTrue(emptyFromBuilder.getDataGovernanceTags().isEmpty()); + compareDataGovernanceTagsInfo(emptyFromBuilder, emptyFromMap); + compareDataGovernanceTagsInfo( + emptyFromBuilder, DataGovernanceTagsInfo.fromPb(emptyFromBuilder.toPb())); + + GsonFactory gsonFactory = GsonFactory.getDefaultInstance(); + + // Unset on Field: dataGovernanceTagsInfo must be omitted from JSON to preserve tags on patch. + Field unsetField = Field.of("col", StandardSQLTypeName.STRING); + String unsetJson = gsonFactory.toString(unsetField.toPb()); + assertFalse(unsetJson.contains("dataGovernanceTagsInfo")); + + // Empty DataGovernanceTagsInfo on Field: emits `"dataGovernanceTagsInfo":{}` to clear tags. + Field clearField = + Field.newBuilder("col", StandardSQLTypeName.STRING) + .setDataGovernanceTagsInfo(emptyFromBuilder) + .build(); + String clearJson = gsonFactory.toString(clearField.toPb()); + assertTrue(clearJson.contains("\"dataGovernanceTagsInfo\":{}")); + + TableFieldSchema parsedClearPb = gsonFactory.fromString(clearJson, TableFieldSchema.class); + Field roundTrippedClearField = Field.fromPb(parsedClearPb); + assertEquals(clearField, roundTrippedClearField); + assertEquals(emptyFromBuilder, roundTrippedClearField.getDataGovernanceTagsInfo()); + } + + @Test + void testPopulatedJsonRoundTrip() throws Exception { + GsonFactory gsonFactory = GsonFactory.getDefaultInstance(); + Field taggedField = + Field.newBuilder("ssn", StandardSQLTypeName.STRING) + .setDataGovernanceTagsInfo(TAGS_INFO) + .build(); + + String json = gsonFactory.toString(taggedField.toPb()); + assertTrue( + json.contains( + "\"dataGovernanceTagsInfo\":{\"dataGovernanceTags\":{\"myProject/pii\":\"sensitive\"}}")); + + TableFieldSchema parsedPb = gsonFactory.fromString(json, TableFieldSchema.class); + Field roundTripped = Field.fromPb(parsedPb); + assertEquals(taggedField, roundTripped); + assertEquals(TAGS_INFO, roundTripped.getDataGovernanceTagsInfo()); + } + + @Test + void testFromPbNullHandling() { + assertNull(DataGovernanceTagsInfo.fromPb(null)); + assertNull( + DataGovernanceTagsInfo.fromPb(Data.nullOf(TableFieldSchema.DataGovernanceTagsInfo.class))); + + TableFieldSchema.DataGovernanceTagsInfo pbWithJsonNullMap = + new TableFieldSchema.DataGovernanceTagsInfo() + .setDataGovernanceTags(Data.nullOf(HashMap.class)); + DataGovernanceTagsInfo parsed = DataGovernanceTagsInfo.fromPb(pbWithJsonNullMap); + assertEquals(DataGovernanceTagsInfo.newBuilder().build(), parsed); + } + + @Test + void testNullInputRejected() { + assertThrows(NullPointerException.class, () -> DataGovernanceTagsInfo.of(null)); + assertThrows( + NullPointerException.class, + () -> DataGovernanceTagsInfo.newBuilder().setDataGovernanceTags(null)); + } + + @Test + void testJavaSerialization() throws Exception { + ByteArrayOutputStream baos = new ByteArrayOutputStream(); + try (ObjectOutputStream oos = new ObjectOutputStream(baos)) { + oos.writeObject(TAGS_INFO); + } + DataGovernanceTagsInfo deserialized; + try (ObjectInputStream ois = + new ObjectInputStream(new ByteArrayInputStream(baos.toByteArray()))) { + deserialized = (DataGovernanceTagsInfo) ois.readObject(); + } + compareDataGovernanceTagsInfo(TAGS_INFO, deserialized); + } + + private void compareDataGovernanceTagsInfo( + DataGovernanceTagsInfo expected, DataGovernanceTagsInfo actual) { + assertEquals(expected, actual); + assertEquals(expected.getDataGovernanceTags(), actual.getDataGovernanceTags()); + assertEquals(expected.hashCode(), actual.hashCode()); + assertEquals(expected.toString(), actual.toString()); + } +} diff --git a/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/FieldTest.java b/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/FieldTest.java index 72f8bb3e8234..99694067855b 100644 --- a/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/FieldTest.java +++ b/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/FieldTest.java @@ -17,8 +17,10 @@ package com.google.cloud.bigquery; import static org.junit.jupiter.api.Assertions.assertEquals; +import static org.junit.jupiter.api.Assertions.assertNull; import static org.junit.jupiter.api.Assertions.assertThrows; +import com.google.common.collect.ImmutableMap; import java.io.ByteArrayInputStream; import java.io.ByteArrayOutputStream; import java.io.InputStream; @@ -44,11 +46,14 @@ public class FieldTest { private static final String FIELD_DESCRIPTION3 = "FieldDescription3"; private static final String FIELD_DEFAULT_VALUE_EXPRESSION1 = "This is default value for this field"; + private static final DataGovernanceTagsInfo DATA_GOVERNANCE_TAGS_INFO = + DataGovernanceTagsInfo.of(ImmutableMap.of("myProject/pii", "sensitive")); private static final Field FIELD_SCHEMA1 = Field.newBuilder(FIELD_NAME1, FIELD_TYPE1) .setMode(FIELD_MODE1) .setDescription(FIELD_DESCRIPTION1) .setDefaultValueExpression(FIELD_DEFAULT_VALUE_EXPRESSION1) + .setDataGovernanceTagsInfo(DATA_GOVERNANCE_TAGS_INFO) .build(); private static final Field FIELD_SCHEMA2 = Field.newBuilder(FIELD_NAME2, FIELD_TYPE2) @@ -67,6 +72,7 @@ public class FieldTest { .setMode(FIELD_MODE1) .setDescription(FIELD_DESCRIPTION1) .setDefaultValueExpression(FIELD_DEFAULT_VALUE_EXPRESSION1) + .setDataGovernanceTagsInfo(DATA_GOVERNANCE_TAGS_INFO) .build(); private static final Field STANDARD_FIELD_SCHEMA2 = Field.newBuilder(FIELD_NAME2, StandardSQLTypeName.INT64) @@ -151,6 +157,8 @@ public void testBuilder() { assertEquals(FIELD_MODE1, FIELD_SCHEMA1.getMode()); assertEquals(FIELD_DESCRIPTION1, FIELD_SCHEMA1.getDescription()); assertEquals(FIELD_DEFAULT_VALUE_EXPRESSION1, FIELD_SCHEMA1.getDefaultValueExpression()); + assertEquals(DATA_GOVERNANCE_TAGS_INFO, FIELD_SCHEMA1.getDataGovernanceTagsInfo()); + assertNull(FIELD_SCHEMA2.getDataGovernanceTagsInfo()); assertEquals(null, FIELD_SCHEMA1.getSubFields()); assertEquals(FIELD_NAME3, FIELD_SCHEMA3.getName()); assertEquals(FIELD_TYPE3, FIELD_SCHEMA3.getType()); @@ -166,6 +174,7 @@ public void testBuilderWithStandardSQLTypeName() { assertEquals(FIELD_MODE1, STANDARD_FIELD_SCHEMA1.getMode()); assertEquals(FIELD_DESCRIPTION1, STANDARD_FIELD_SCHEMA1.getDescription()); assertEquals(FIELD_DEFAULT_VALUE_EXPRESSION1, FIELD_SCHEMA1.getDefaultValueExpression()); + assertEquals(DATA_GOVERNANCE_TAGS_INFO, STANDARD_FIELD_SCHEMA1.getDataGovernanceTagsInfo()); assertEquals(null, STANDARD_FIELD_SCHEMA1.getSubFields()); assertEquals(FIELD_NAME3, STANDARD_FIELD_SCHEMA3.getName()); assertEquals(FIELD_TYPE3, STANDARD_FIELD_SCHEMA3.getType()); @@ -185,6 +194,11 @@ public void testToAndFromPb() { compareFieldSchemas(FIELD_SCHEMA3, Field.fromPb(FIELD_SCHEMA3.toPb())); Field field = Field.newBuilder(FIELD_NAME1, FIELD_TYPE1).build(); compareFieldSchemas(field, Field.fromPb(field.toPb())); + Field clearTagsField = + Field.newBuilder(FIELD_NAME1, FIELD_TYPE1) + .setDataGovernanceTagsInfo(DataGovernanceTagsInfo.newBuilder().build()) + .build(); + compareFieldSchemas(clearTagsField, Field.fromPb(clearTagsField.toPb())); } @Test @@ -234,6 +248,7 @@ private void compareFieldSchemas(Field expected, Field value) { assertEquals(expected.getType(), value.getType()); assertEquals(expected.getMode(), value.getMode()); assertEquals(expected.getDescription(), value.getDescription()); + assertEquals(expected.getDataGovernanceTagsInfo(), value.getDataGovernanceTagsInfo()); assertEquals(expected.getSubFields(), value.getSubFields()); } } diff --git a/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/SchemaTest.java b/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/SchemaTest.java index 9750fd7bd36f..2400dc508d05 100644 --- a/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/SchemaTest.java +++ b/java-bigquery/google-cloud-bigquery/src/test/java/com/google/cloud/bigquery/SchemaTest.java @@ -20,6 +20,7 @@ import com.google.api.services.bigquery.model.TableSchema; import com.google.common.collect.ImmutableList; +import com.google.common.collect.ImmutableMap; import java.util.List; import org.junit.jupiter.api.Test; @@ -27,6 +28,8 @@ class SchemaTest { private static PolicyTags POLICY_TAGS = PolicyTags.newBuilder().setNames(ImmutableList.of("someTag")).build(); + private static final DataGovernanceTagsInfo DATA_GOVERNANCE_TAGS_INFO = + DataGovernanceTagsInfo.of(ImmutableMap.of("myProject/pii", "sensitive")); private static final Field FIELD_SCHEMA1 = Field.newBuilder("StringField", LegacySQLTypeName.STRING) @@ -35,6 +38,7 @@ class SchemaTest { .setPrecision(20L) .setScale(20L) .setMaxLength(10L) + .setDataGovernanceTagsInfo(DATA_GOVERNANCE_TAGS_INFO) .build(); private static final Field FIELD_SCHEMA2 = Field.newBuilder("IntegerField", LegacySQLTypeName.INTEGER)