made an issue

Author: LiamHamsters

src/Ydb.Sdk/src/Ado/BulkUpsert/BulkUpsertImporter.cs

@@ -34,35 +34,40 @@ internal BulkUpsertImporter(
     /// <summary>
     /// Add a single row to the current BulkUpsert batch.
     /// </summary>
-    /// <param name="values">Column values in the same order as the configured <c>columns</c>.</param>
+    /// <param name="values">Values in the same order as the configured <c>columns</c>.</param>
     /// <remarks>
-    /// Supported element types: <see cref="YdbValue"/>, <see cref="YdbParameter"/>, <see cref="YdbList"/> (as-is);
-    /// other CLR values are converted via <see cref="YdbParameter"/>.
+    /// Supported per-cell types: <see cref="YdbValue"/>, <see cref="YdbParameter"/>.
+    /// Other CLR values are converted via <see cref="YdbParameter"/>.
+    /// Passing <see cref="YdbList"/> as a column value is not supported (tables do not accept list-typed columns).
+    /// Use <c>AddListAsync(YdbList)</c> to append many rows from a list parameter.
     /// </remarks>
+    /// <exception cref="ArgumentException">Thrown when the number of values differs from the number of columns.</exception>
+    /// <exception cref="InvalidOperationException">Thrown when a value cannot be mapped to a YDB type.</exception>
     /// <example>
     /// <code>
     /// // columns: ["Id", "Name"]
     /// await importer.AddRowAsync(1, "Alice");
+    /// await importer.AddRowAsync(2, "Bob");
     /// </code>
     /// </example>
-    /// <exception cref="ArgumentException">When the number of values doesn't equal the number of columns.</exception>
-    /// <exception cref="InvalidOperationException">When a value cannot be mapped to a YDB type.</exception>
     public async ValueTask AddRowAsync(params object[] values)
     {
         if (values.Length != _columns.Count)
             throw new ArgumentException("Values count must match columns count.", nameof(values));
 
         var ydbValues = values.Select(v => v switch
         {
-            YdbValue ydbValue => ydbValue.GetProto(),
+            YdbValue ydbValue  => ydbValue.GetProto(),
             YdbParameter param => param.TypedValue,
-            YdbList list => list.ToTypedValue(),
+            YdbList => throw new ArgumentException(
+                "YdbList cannot be used as a column value. Use AddListAsync(YdbList) to append multiple rows.",
+                nameof(values)),
             _ => new YdbParameter { Value = v }.TypedValue
         }).ToArray();
 
         var protoStruct = new Ydb.Value();
-        foreach (var value in ydbValues)
-            protoStruct.Items.Add(value.Value);
+        foreach (var tv in ydbValues)
+            protoStruct.Items.Add(tv.Value);
 
         var rowSize = protoStruct.CalculateSize();
 
@@ -79,24 +84,17 @@ public async ValueTask AddRowAsync(params object[] values)
     }
 
     /// <summary>
-    /// Add multiple rows from a single <see cref="YdbList"/> parameter.
+    /// Add multiple rows from a <see cref="YdbList"/> shaped as <c>List&lt;Struct&lt;...&gt;&gt;</c>.
+    /// Struct member names and order must exactly match the configured <c>columns</c>.
     /// </summary>
-    /// <remarks>
-    /// Expects <c>List&lt;Struct&lt;...&gt;&gt;</c>; struct member names and order must exactly match the configured <c>columns</c>.
-    /// Example: <c>columns=["Id","Name"]</c> → <c>List&lt;Struct&lt;Id:Int64, Name:Utf8&gt;&gt;</c>.
-    /// </remarks>
+    /// <param name="list">Rows as <c>List&lt;Struct&lt;...&gt;&gt;</c> with the exact column names and order.</param>
+    /// <exception cref="ArgumentException">
+    /// Thrown when the struct column set, order, or count does not match the importer’s <c>columns</c>.
+    /// </exception>
     public async ValueTask AddListAsync(YdbList list)
     {
         var tv = list.ToTypedValue();
 
-        if (tv.Type.TypeCase != Type.TypeOneofCase.ListType ||
-            tv.Type.ListType.Item.TypeCase != Type.TypeOneofCase.StructType)
-        {
-            throw new ArgumentException(
-                "BulkUpsertImporter.AddListAsync expects a YdbList with a value like List<Struct<...>>",
-                nameof(list));
-        }
-
         var incomingStruct = tv.Type.ListType.Item.StructType;
 
         if (incomingStruct.Members.Count != _columns.Count)
@@ -130,6 +128,10 @@ public async ValueTask AddListAsync(YdbList list)
     /// <summary>
     /// Flush the current batch via BulkUpsert. No-op if the batch is empty.
     /// </summary>
+    /// <remarks>
+    /// Uses the collected struct schema from the first added row (or the provided list) and sends
+    /// the accumulated rows in a single BulkUpsert request.
+    /// </remarks>
     public async ValueTask FlushAsync()
     {
         if (_rows.Count == 0)

src/Ydb.Sdk/src/Ado/BulkUpsert/IBulkUpsertImporter.cs

@@ -2,18 +2,30 @@
 
 namespace Ydb.Sdk.Ado.BulkUpsert;
 
+/// <summary>
+/// Bulk upsert importer API: add rows and flush them to YDB in batches.
+/// </summary>
 public interface IBulkUpsertImporter
 {
-    /// <summary>Add a single row to the batch. Values must match the importer column order.</summary>
-    /// <param name="row">Column values in the same order as the configured <c>columns</c>.</param>
+    /// <summary>
+    /// Add a single row to the batch. Values must match the importer’s column order.
+    /// </summary>
+    /// <param name="row">Values in the same order as the configured <c>columns</c>.</param>
+    /// <exception cref="ArgumentException">Thrown when the number of values differs from the number of columns.</exception>
     ValueTask AddRowAsync(params object[] row);
 
     /// <summary>
-    /// Add many rows from <see cref="YdbList"/> (shape: <c>List&lt;Struct&lt;...&gt;&gt;</c>).
+    /// Add multiple rows from a <see cref="YdbList"/> shaped as <c>List&lt;Struct&lt;...&gt;&gt;</c>.
     /// Struct member names and order must exactly match the configured <c>columns</c>.
     /// </summary>
+    /// <param name="list">Rows as <c>List&lt;Struct&lt;...&gt;&gt;</c> with the exact column names and order.</param>
+    /// <exception cref="ArgumentException">
+    /// Thrown when the struct column set, order, or count does not match the importer’s <c>columns</c>.
+    /// </exception>
     ValueTask AddListAsync(YdbList list);
 
-    /// <summary>Flush the current batch via BulkUpsert (no-op if empty).</summary>
+    /// <summary>
+    /// Flush the current batch via BulkUpsert. No-op if the batch is empty.
+    /// </summary>
     ValueTask FlushAsync();
 }

src/Ydb.Sdk/src/Ado/YdbParameter.cs

@@ -149,9 +149,8 @@ internal TypedValue TypedValue
                 YdbDbType.Double => MakeDouble(value),
                 YdbDbType.Decimal when value is decimal decimalValue => Decimal(decimalValue),
                 YdbDbType.Bytes => MakeBytes(value),
-                YdbDbType.Json when value is string stringJsonValue => stringJsonValue.Json(),
-                YdbDbType.JsonDocument when value is string stringJsonDocumentValue => stringJsonDocumentValue
-                    .JsonDocument(),
+                YdbDbType.Json when value is string stringValue => stringValue.Json(),
+                YdbDbType.JsonDocument when value is string stringValue => stringValue.JsonDocument(),
                 YdbDbType.Uuid when value is Guid guidValue => guidValue.Uuid(),
                 YdbDbType.Date => MakeDate(value),
                 YdbDbType.DateTime when value is DateTime dateTimeValue => dateTimeValue.Datetime(),
@@ -290,7 +289,8 @@ private TypedValue NullTypedValue()
         }
 
         throw new InvalidOperationException(
-            "Writing value of 'null' is not supported without explicit mapping to the YdbDbType");
+            "Writing value of 'null' is not supported without explicit mapping to the YdbDbType"
+        );
     }
 
     private InvalidOperationException ValueTypeNotSupportedException =>

src/Ydb.Sdk/src/Value/YdbList.cs

@@ -5,33 +5,34 @@
 namespace Ydb.Sdk.Value;
 
 /// <summary>
-/// Struct-only builder for YDB <c>List&lt;Struct&lt;...&gt;&gt;</c>.
-/// Works directly with protobuf:
-/// - Each call to <see cref="AddRow(object?[])"/> converts values into protobuf cells (<see cref="Ydb.Value"/>) and stores a row immediately.
-/// - The struct schema (<see cref="StructType"/>) is derived from column type hints or from the first non-null sample per column.
-/// - If a column has at least one <c>null</c>, its type becomes <c>Optional&lt;T&gt;</c>; individual null cells are encoded via <see cref="NullValue.NullValue"/>.
+/// Builder for YDB values shaped as <c>List&lt;Struct&lt;...&gt;&gt;</c>, working directly with protobuf.
+/// Each call to <see cref="AddRow(object?[])"/> converts input values into protobuf cells and stores the row.
+/// The struct schema is derived from explicit type hints or from the first non-null sample per column.
+/// If a column contains at least one <c>null</c>, its member type becomes <c>Optional&lt;T&gt;</c>.
 /// </summary>
 public sealed class YdbList
 {
     private readonly string[] _columns;
-    private readonly YdbDbType[]? _typeHints;
+    private readonly YdbDbType[] _typeHints;
 
     private readonly List<Ydb.Value> _rows = new();
 
     private readonly Type?[] _observedBaseTypes;
     private readonly bool[] _sawNull;
 
     /// <summary>
-    /// Create a struct-mode list with column names; types will be inferred from the
-    /// first non-null value per column (columns with any nulls become Optional&lt;T&gt;).
+    /// Create a struct-mode list with column names. Types will be inferred from the
+    /// first non-null value per column (columns with any nulls become <c>Optional&lt;T&gt;</c>).
     /// </summary>
+    /// <param name="columns">Struct member names, in order.</param>
     public static YdbList Struct(params string[] columns) => new(columns);
 
     /// <summary>
-    /// Create a struct-mode list with column names and explicit YDB type hints
-    /// (array length must match <paramref name="columns"/>). Columns with any nulls
-    /// will be emitted as Optional&lt;hintedType&gt;.
+    /// Create a struct-mode list with column names and explicit YDB type hints. The array length must match <paramref name="columns"/>.
+    /// Columns that contain <c>null</c> are emitted as <c>Optional&lt;hintedType&gt;</c>.
     /// </summary>
+    /// <param name="columns">Struct member names, in order.</param>
+    /// <param name="types">YDB type hints for each column (same length as <paramref name="columns"/>).</param>
     public static YdbList Struct(string[] columns, YdbDbType[] types) => new(columns, types);
 
     /// <summary>
@@ -45,7 +46,7 @@ private YdbList(string[] columns, YdbDbType[]? types = null)
             throw new ArgumentException("Length of 'types' must match length of 'columns'.", nameof(types));
 
         _columns = columns;
-        _typeHints = types;
+        _typeHints = types ?? Enumerable.Repeat(YdbDbType.Unspecified, columns.Length).ToArray();
         _observedBaseTypes = new Type[_columns.Length];
         _sawNull = new bool[_columns.Length];
     }
@@ -54,6 +55,8 @@ private YdbList(string[] columns, YdbDbType[]? types = null)
     /// Add a single positional row. The number of values must match the number of columns.
     /// Values are converted to protobuf cells and the row is stored immediately.
     /// </summary>
+    /// <param name="values">Row values in the same order as the declared columns.</param>
+    /// <exception cref="ArgumentException">Thrown when the number of values differs from the number of columns.</exception>
     public YdbList AddRow(params object?[] values)
     {
         if (values.Length != _columns.Length)
@@ -92,13 +95,17 @@ public YdbList AddRow(params object?[] values)
     }
 
     /// <summary>
-    /// Convert to a YDB <see cref="TypedValue"/> shaped as <c>List&lt;Struct&lt;...&gt;&gt;</c>.
-    /// Columns that observed <c>null</c> values are emitted as <c>Optional&lt;T&gt;</c>;
-    /// individual <c>null</c> cells are encoded via <see cref="NullValue.NullValue"/>.
+    /// Convert the accumulated rows into a YDB <see cref="TypedValue"/> with shape <c>List&lt;Struct&lt;...&gt;&gt;</c>.
+    /// Columns that observed <c>null</c> values are emitted as <c>Optional&lt;T&gt;</c>.
     /// </summary>
+    /// <returns>TypedValue representing <c>List&lt;Struct&lt;...&gt;&gt;</c> and the collected data rows.</returns>
+    /// <exception cref="InvalidOperationException">
+    /// Thrown when the schema cannot be inferred (e.g., empty list without type hints, or a column has only nulls
+    /// and no explicit type hint).
+    /// </exception>
     internal TypedValue ToTypedValue()
     {
-        if (_rows.Count == 0 && (_typeHints is null || _typeHints.All(t => t == YdbDbType.Unspecified)))
+        if (_rows.Count == 0)
             throw new InvalidOperationException(
                 "Cannot infer Struct schema from an empty list without explicit YdbDbType hints.");
 
@@ -109,7 +116,7 @@ internal TypedValue ToTypedValue()
         {
             Type? baseType;
 
-            if (_typeHints is not null && _typeHints[i] != YdbDbType.Unspecified)
+            if (_typeHints[i] != YdbDbType.Unspecified)
             {
                 baseType = new YdbParameter { YdbDbType = _typeHints[i], Value = DBNull.Value }.TypedValue.Type;