breaking: require file column attribute to be schema name instead of logical name for better column creation support

Author: Max Wang

examples/advanced/file_upload.py

@@ -210,9 +210,7 @@ def ensure_table():
 attr_prefix = table_schema_name.split("_", 1)[0] if "_" in table_schema_name else table_schema_name
 name_attr = f"{attr_prefix}_name"
 small_file_attr_schema = f"{attr_prefix}_SmallDocument"  # second file attribute for small single-request demo
-small_file_attr_logical = f"{attr_prefix}_smalldocument"  # expected logical name (lowercase)
 chunk_file_attr_schema = f"{attr_prefix}_ChunkDocument"  # attribute for streaming chunk upload demo
-chunk_file_attr_logical = f"{attr_prefix}_chunkdocument"  # expected logical name
 
 # --------------------------- Record create ---------------------------
 record_id = None
@@ -260,15 +258,15 @@ def get_dataset_info(file_path: Path):
             lambda: client.upload_file(
                 table_schema_name,
                 record_id,
-                small_file_attr_logical,
+                small_file_attr_schema,
                 str(DATASET_FILE),
                 mode="small",
             )
         )
         print({"small_upload_completed": True, "small_source_size": small_file_size})
         odata = client._get_odata()
         dl_url_single = (
-            f"{odata.api}/{entity_set}({record_id})/{small_file_attr_logical}/$value"  # raw entity_set URL OK
+            f"{odata.api}/{entity_set}({record_id})/{small_file_attr_schema.lower()}/$value"  # raw entity_set URL OK
         )
         resp_single = backoff(lambda: odata._request("get", dl_url_single))
         content_single = resp_single.content or b""
@@ -294,7 +292,7 @@ def get_dataset_info(file_path: Path):
             lambda: client.upload_file(
                 table_schema_name,
                 record_id,
-                small_file_attr_logical,
+                small_file_attr_schema,
                 str(replacement_file),
                 mode="small",
             )
@@ -332,15 +330,15 @@ def get_dataset_info(file_path: Path):
             lambda: client.upload_file(
                 table_schema_name,
                 record_id,
-                chunk_file_attr_logical,
+                chunk_file_attr_schema,
                 str(DATASET_FILE),
                 mode="chunk",
             )
         )
         print({"chunk_upload_completed": True})
         odata = client._get_odata()
         dl_url_chunk = (
-            f"{odata.api}/{entity_set}({record_id})/{chunk_file_attr_logical}/$value"  # raw entity_set for download
+            f"{odata.api}/{entity_set}({record_id})/{chunk_file_attr_schema.lower()}/$value"  # raw entity_set for download
         )
         resp_chunk = backoff(lambda: odata._request("get", dl_url_chunk))
         content_chunk = resp_chunk.content or b""
@@ -365,7 +363,7 @@ def get_dataset_info(file_path: Path):
             lambda: client.upload_file(
                 table_schema_name,
                 record_id,
-                chunk_file_attr_logical,
+                chunk_file_attr_schema,
                 str(replacement_file),
                 mode="chunk",
             )

src/PowerPlatform/Dataverse/client.py

@@ -617,7 +617,7 @@ def upload_file(
         :type table_schema_name: :class:`str`
         :param record_id: GUID of the target record.
         :type record_id: :class:`str`
-        :param file_name_attribute: Logical name of the file column attribute.
+        :param file_name_attribute: Schema name of the file column attribute (e.g., ``"new_Document"``). If the column doesn't exist, it will be created automatically.
         :type file_name_attribute: :class:`str`
         :param path: Local filesystem path to the file. The stored filename will be
             the basename of this path.
@@ -646,7 +646,7 @@ def upload_file(
                 client.upload_file(
                     table_schema_name="account",
                     record_id=account_id,
-                    file_name_attribute="new_contract",
+                    file_name_attribute="new_Contract",
                     path="/path/to/contract.pdf",
                     mime_type="application/pdf"
                 )
@@ -656,7 +656,7 @@ def upload_file(
                 client.upload_file(
                     table_schema_name="email",
                     record_id=email_id,
-                    file_name_attribute="new_attachment",
+                    file_name_attribute="new_Attachment",
                     path="/path/to/large_file.zip",
                     mode="auto"
                 )

src/PowerPlatform/Dataverse/data/_odata.py

@@ -901,7 +901,7 @@ def _get_attribute_metadata(
     def _wait_for_attribute_visibility(
         self,
         entity_set: str,
-        attribute_logical_name: str,
+        attribute_name: str,
         delays: tuple = (0, 3, 10, 20),
     ) -> None:
         """Wait for a newly created attribute to become visible in the data API.
@@ -910,7 +910,9 @@ def _wait_for_attribute_visibility(
         it becomes queryable in the data API. This method polls the entity set with
         the attribute in the $select clause until it succeeds or all delays are exhausted.
         """
-        probe_url = f"{self.api}/{entity_set}?$top=1&$select={attribute_logical_name}"
+        # Convert to lowercase logical name for URL
+        logical_name = attribute_name.lower()
+        probe_url = f"{self.api}/{entity_set}?$top=1&$select={logical_name}"
         last_error = None
         total_wait = sum(delays)
 
@@ -926,7 +928,7 @@ def _wait_for_attribute_visibility(
 
         # All retries exhausted - raise with context
         raise RuntimeError(
-            f"Attribute '{attribute_logical_name}' did not become visible in the data API "
+            f"Attribute '{logical_name}' did not become visible in the data API "
             f"after {total_wait} seconds (exhausted all retries)."
         ) from last_error
 

src/PowerPlatform/Dataverse/data/_upload.py

@@ -30,7 +30,7 @@ def _upload_file(
         record_id : :class:`str`
             GUID of the target record.
         file_name_attribute : :class:`str`
-            Logical name of the file column attribute. If the column doesn't exist, it will be created.
+            Schema name of the file column attribute (e.g., "new_Document"). If the column doesn't exist, it will be created.
         path : :class:`str`
             Local filesystem path to the file.
         mode : :class:`str` | None
@@ -66,13 +66,16 @@ def _upload_file(
             size = os.path.getsize(path)
             mode = "small" if size < 128 * 1024 * 1024 else "chunk"
 
+        # Convert schema name to lowercase logical name for URL usage
+        logical_name = file_name_attribute.lower()
+
         if mode == "small":
             return self._upload_file_small(
-                entity_set, record_id, file_name_attribute, path, content_type=mime_type, if_none_match=if_none_match
+                entity_set, record_id, logical_name, path, content_type=mime_type, if_none_match=if_none_match
             )
         if mode == "chunk":
             return self._upload_file_chunk(
-                entity_set, record_id, file_name_attribute, path, if_none_match=if_none_match
+                entity_set, record_id, logical_name, path, if_none_match=if_none_match
             )
         raise ValueError(f"Invalid mode '{mode}'. Use 'auto', 'small', or 'chunk'.")