You are viewing a plain text version of this content. The canonical link for it is here.
Posted to github@arrow.apache.org by "ByteBaker (via GitHub)" <gi...@apache.org> on 2026/07/08 10:03:54 UTC

[PR] docs: clarify decimal negative scale behavior [arrow-rs]

ByteBaker opened a new pull request, #10304:
URL: https://github.com/apache/arrow-rs/pull/10304

   # Which issue does this PR close?
   
   - Refs #5793.
   - Follow-up to #6413.
   
   # Rationale for this change
   
   The issue was discussed in the PR and issue mentioned above and it was agreed [here](https://github.com/apache/arrow-rs/issues/5793#issuecomment-2362484895) that we should update the docs. We just never got to actually doing it.
   
   
   
   # What changes are included in this PR?
   
   Updates the `Decimal32`, `Decimal64`, `Decimal128`, and `Decimal256` docs to explain that negative scale rounds values to the left of the decimal point, and that precision is the maximum number of non-rounded digits.
   
   Also adds an example showing how a value is rounded and represented internally.
   
   # Are these changes tested?
   
   Ran fmt. Doc only changes, no other test required.
   No runtime tests were added because this is a documentation-only change.
   
   # Are there any user-facing changes?
   
   Documentation only. No API or behavior changes.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: clarify decimal negative scale behavior [arrow-rs]

Posted by "Jefffrey (via GitHub)" <gi...@apache.org>.
Jefffrey merged PR #10304:
URL: https://github.com/apache/arrow-rs/pull/10304


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: clarify decimal negative scale behavior [arrow-rs]

Posted by "ByteBaker (via GitHub)" <gi...@apache.org>.
ByteBaker commented on code in PR #10304:
URL: https://github.com/apache/arrow-rs/pull/10304#discussion_r3564988248


##########
arrow-schema/src/datatype.rs:
##########
@@ -361,12 +361,12 @@ pub enum DataType {
     ///
     /// For example the number 123.45 has precision 5 and scale 2.
     ///
-    /// In certain situations, scale could be negative number. For
-    /// negative scale, it is the number of padding 0 to the right
-    /// of the digits.
+    /// In certain situations, scale can be negative. Negative scale
+    /// rounds values to the left of the decimal point, and precision is
+    /// the maximum number of non-rounded digits.
     ///
-    /// For example the number 12300 could be treated as a decimal
-    /// has precision 3 and scale -2.
+    /// For example, with precision 2 and scale -3, the value 12345 is
+    /// rounded to 12000 and represented as the stored integer 12.

Review Comment:
   I updated it. TBH I find explaining this somewhat confusing by nature. 😬 
   
   But please see if the newer one is more clearer.



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: clarify decimal negative scale behavior [arrow-rs]

Posted by "Jefffrey (via GitHub)" <gi...@apache.org>.
Jefffrey commented on PR #10304:
URL: https://github.com/apache/arrow-rs/pull/10304#issuecomment-4986365460

   thanks @ByteBaker 


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: clarify decimal negative scale behavior [arrow-rs]

Posted by "ByteBaker (via GitHub)" <gi...@apache.org>.
ByteBaker commented on PR #10304:
URL: https://github.com/apache/arrow-rs/pull/10304#issuecomment-4913676698

   @jayzhan211 @alamb @wjones127 Please accept my apologies. We agreed the last time while closing #5793 that we should fix the docs, and I was supposed to do it. Life happened in the meantime and I totally forgot about it. 😅
   
   This morning I found it in my old TODOs and decided to do it. Lemme know what y'all think of the changes.


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org

Re: [PR] docs: clarify decimal negative scale behavior [arrow-rs]

Posted by "Jefffrey (via GitHub)" <gi...@apache.org>.
Jefffrey commented on code in PR #10304:
URL: https://github.com/apache/arrow-rs/pull/10304#discussion_r3552032653


##########
arrow-schema/src/datatype.rs:
##########
@@ -361,12 +361,12 @@ pub enum DataType {
     ///
     /// For example the number 123.45 has precision 5 and scale 2.
     ///
-    /// In certain situations, scale could be negative number. For
-    /// negative scale, it is the number of padding 0 to the right
-    /// of the digits.
+    /// In certain situations, scale can be negative. Negative scale
+    /// rounds values to the left of the decimal point, and precision is
+    /// the maximum number of non-rounded digits.
     ///
-    /// For example the number 12300 could be treated as a decimal
-    /// has precision 3 and scale -2.
+    /// For example, with precision 2 and scale -3, the value 12345 is
+    /// rounded to 12000 and represented as the stored integer 12.

Review Comment:
   i find it a little confusing that we talk about how `12345` is converted to a negative scale decimal here, instead of in cast kernels 🤔
   
   imo at this level all we care about is explaining how values already stored as decimals are represented and what they actually represent, aka we can say a value of `12` but with `-3` scale is equivalent to `12000`
   
   (i skimmed the linked discussion so maybe this was already discussed 😅)



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: github-unsubscribe@arrow.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org