KalleOlaviNiemitalo commented on code in PR #2282:
URL: https://github.com/apache/avro/pull/2282#discussion_r1349457370
##########
doc/content/en/docs/++version++/Specification/_index.md:
##########
@@ -810,6 +810,20 @@ Scale must be zero or a positive integer less than or
equal to the precision.
For the purposes of schema resolution, two schemas that are `decimal` logical
types _match_ if their scales and precisions match.
+**alternative**
+
+As it's not always possible to fix scale and precision in advance for a
decimal field, `big-decimal` is another `decimal` logical type restrict to Avro
_bytes_.
+
+_only available in Java_
+
+```json
+{
+ "type": "bytes",
+ "logicalType": "big-decimal"
+}
+```
+Here, as scale property is stored in value itself it needs more bytes than
preceding `decimal` type, but it allows more flexibility.
+
Review Comment:
No comments on the Java code, but I'd like to see the specification
clarified a bit.
* Separate the "big-decimal" description under its own `### Decimal
(variable scale)` heading, for these purposes:
+ Gives it an ID in HTML so that it can be linked to.
+ Makes it show up in the table of contents.
+ Makes it clear that the schema-resolution matching rule of "decimal"
does not apply.
* Describe how the decimal value is encoded. AFAICT, it goes like this:
> A `big-decimal` logical type annotates an Avro `bytes` type, which
stores the [binary
encoding](https://avro.apache.org/docs/1.11.1/specification/#binary-encoding)
of the following record:
>
> ```JSON
> {
> "type": "record",
> "name": "BigDecimal",
> "doc": "Avro 'big-decimal' value encoded within 'bytes'",
> "fields": [
> {
> "name": "unscaled",
> "type": "bytes",
> "doc": "The two’s-complement representation of the unscaled
integer value in big-endian byte order"
> },
> {
> "name": "scale",
> "type": "int",
> "doc": "How many digits of the unscaled value lie at the
right side of the decimal point. Must not be negative."
> }
> ]
> }
Or describe it in prose -- as long as the specification is clear enough
that the logical type can be implemented without looking at how the Java code
does it.
##########
doc/content/en/docs/++version++/Specification/_index.md:
##########
@@ -810,6 +810,20 @@ Scale must be zero or a positive integer less than or
equal to the precision.
For the purposes of schema resolution, two schemas that are `decimal` logical
types _match_ if their scales and precisions match.
+**alternative**
+
+As it's not always possible to fix scale and precision in advance for a
decimal field, `big-decimal` is another `decimal` logical type restrict to Avro
_bytes_.
+
+_only available in Java_
+
+```json
+{
+ "type": "bytes",
+ "logicalType": "big-decimal"
+}
+```
+Here, as scale property is stored in value itself it needs more bytes than
preceding `decimal` type, but it allows more flexibility.
+
Review Comment:
No comments on the Java code, but I'd like to see the specification
clarified a bit.
* Separate the "big-decimal" description under its own `### Decimal
(variable scale)` heading, for these purposes:
+ Gives it an ID in HTML so that it can be linked to.
+ Makes it show up in the table of contents.
+ Makes it clear that the schema-resolution matching rule of "decimal"
does not apply.
* Describe how the decimal value is encoded. AFAICT, it goes like this:
> A `big-decimal` logical type annotates an Avro `bytes` type, which
stores the [binary
encoding](https://avro.apache.org/docs/1.11.1/specification/#binary-encoding)
of the following record:
>
> ```JSON
> {
> "type": "record",
> "name": "BigDecimal",
> "doc": "Avro 'big-decimal' value encoded within 'bytes'",
> "fields": [
> {
> "name": "unscaled",
> "type": "bytes",
> "doc": "The two’s-complement representation of the unscaled
integer value in big-endian byte order"
> },
> {
> "name": "scale",
> "type": "int",
> "doc": "How many digits of the unscaled value lie at the
right side of the decimal point. Must not be negative."
> }
> ]
> }
Or describe it in prose -- as long as the specification is clear enough
that the logical type can be implemented without looking at how the Java code
does it.
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
