feat: allow users to set Apache Avro output format options through av…

…ro_serialization_options param in TableReadOptions message (#284)

* feat: allow users to set Apache Avro output format options through avro_serialization_options param in TableReadOptions message
Through AvroSerializationOptions, users can set enable_display_name_attribute, which populates displayName for every avro field with the original column name
Improved documentation for selected_fields, added example for clarity.

PiperOrigin-RevId: 468290142

Source-Link: googleapis/googleapis@62ae1af

Source-Link: googleapis/googleapis-gen@732b7f9
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiNzMyYjdmOTIyNDc3ZDI1MzI4YjkyMzU5ZjA2NjdmZTk1ZGU1MmZhMiJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

protos/google/cloud/bigquery/storage/v1/avro.proto

@@ -39,3 +39,18 @@ message AvroRows {
   // Please use the format-independent ReadRowsResponse.row_count instead.
   int64 row_count = 2 [deprecated = true];
 }
+
+// Contains options specific to Avro Serialization.
+message AvroSerializationOptions {
+  // Enable displayName attribute in Avro schema.
+  //
+  // The Avro specification requires field names to be alphanumeric.  By
+  // default, in cases when column names do not conform to these requirements
+  // (e.g. non-ascii unicode codepoints) and Avro is requested as an output
+  // format, the CreateReadSession call will fail.
+  //
+  // Setting this field to true, populates avro field names with a placeholder
+  // value and populates a "displayName" attribute for every avro field with the
+  // original column name.
+  bool enable_display_name_attribute = 1;
+}

protos/google/cloud/bigquery/storage/v1/stream.proto

@@ -59,10 +59,53 @@ message ReadSession {
 
   // Options dictating how we read a table.
   message TableReadOptions {
-    // Names of the fields in the table that should be read. If empty, all
-    // fields will be read. If the specified field is a nested field, all
-    // the sub-fields in the field will be selected. The output field order is
-    // unrelated to the order of fields in selected_fields.
+    // Optional. The names of the fields in the table to be returned. If no
+    // field names are specified, then all fields in the table are returned.
+    //
+    // Nested fields -- the child elements of a STRUCT field -- can be selected
+    // individually using their fully-qualified names, and will be returned as
+    // record fields containing only the selected nested fields. If a STRUCT
+    // field is specified in the selected fields list, all of the child elements
+    // will be returned.
+    //
+    // As an example, consider a table with the following schema:
+    //
+    //   {
+    //       "name": "struct_field",
+    //       "type": "RECORD",
+    //       "mode": "NULLABLE",
+    //       "fields": [
+    //           {
+    //               "name": "string_field1",
+    //               "type": "STRING",
+    // .              "mode": "NULLABLE"
+    //           },
+    //           {
+    //               "name": "string_field2",
+    //               "type": "STRING",
+    //               "mode": "NULLABLE"
+    //           }
+    //       ]
+    //   }
+    //
+    // Specifying "struct_field" in the selected fields list will result in a
+    // read session schema with the following logical structure:
+    //
+    //   struct_field {
+    //       string_field1
+    //       string_field2
+    //   }
+    //
+    // Specifying "struct_field.string_field1" in the selected fields list will
+    // result in a read session schema with the following logical structure:
+    //
+    //   struct_field {
+    //       string_field1
+    //   }
+    //
+    // The order of the fields in the read session schema is derived from the
+    // table schema and does not correspond to the order in which the fields are
+    // specified in this list.
     repeated string selected_fields = 1;
 
     // SQL text filtering statement, similar to a WHERE clause in a query.
@@ -80,6 +123,9 @@ message ReadSession {
     oneof output_format_serialization_options {
       // Optional. Options specific to the Apache Arrow output format.
       ArrowSerializationOptions arrow_serialization_options = 3 [(google.api.field_behavior) = OPTIONAL];
+
+      // Optional. Options specific to the Apache Avro output format
+      AvroSerializationOptions avro_serialization_options = 4 [(google.api.field_behavior) = OPTIONAL];
     }
   }