You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@spark.apache.org by GitBox <gi...@apache.org> on 2022/11/10 21:45:30 UTC
[GitHub] [spark] amaliujia opened a new pull request, #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
amaliujia opened a new pull request, #38605:
URL: https://github.com/apache/spark/pull/38605
<!--
Thanks for sending a pull request! Here are some tips for you:
1. If this is your first time, please read our contributor guidelines: https://spark.apache.org/contributing.html
2. Ensure you have added or run the appropriate tests for your PR: https://spark.apache.org/developer-tools.html
3. If the PR is unfinished, add '[WIP]' in your PR title, e.g., '[WIP][SPARK-XXXX] Your PR title ...'.
4. Be sure to keep the PR description updated to reflect all changes.
5. Please write your PR title to summarize what this PR proposes.
6. If possible, provide a concise example to reproduce the issue for a faster review.
7. If you want to add a new configuration, please read the guideline first for naming configurations in
'core/src/main/scala/org/apache/spark/internal/config/ConfigEntry.scala'.
8. If you want to add or modify an error type or message, please read the guideline first in
'core/src/main/resources/error/README.md'.
-->
### What changes were proposed in this pull request?
<!--
Please clarify what changes you are proposing. The purpose of this section is to outline the changes and how this PR fixes the issue.
If possible, please consider writing useful notes for better and faster reviews in your PR. See the examples below.
1. If you refactor some codes with changing classes, showing the class hierarchy will help reviewers.
2. If you fix some SQL features, you can provide some references of other DBMSes.
3. If there is design documentation, please add the link.
4. If there is a discussion in the mailing list, please add the link.
-->
This PR adds a developer facing documentation for how to add proto messages to Connect proto. More specifically, adding how to add a proto field which takes considerations of `required`, `optional` and default values.
### Why are the changes needed?
<!--
Please clarify why the changes are needed. For instance,
1. If you propose a new API, clarify the use case for a new API.
2. If you fix a bug, you can clarify why it is a bug.
-->
Improve documentation for developers who want to update Connect proto.
### Does this PR introduce _any_ user-facing change?
<!--
Note that it means *any* user-facing change including all aspects such as the documentation fix.
If yes, please clarify the previous behavior and the change this PR proposes - provide the console output, description and/or an example to show the behavior difference if possible.
If possible, please also clarify if this is a user-facing change compared to the released Spark versions or within the unreleased branches such as master.
If no, write 'No'.
-->
NO
### How was this patch tested?
<!--
If tests were added, say they were added here. Please make sure to add some test cases that check the changes thoroughly including negative and positive cases if possible.
If it was tested in a way different from regular unit tests, please clarify how you tested step by step, ideally copy and paste-able, so that other reviewers can test and check, and descendants can verify in the future.
If tests were not added, please describe why they were not added and/or why it was difficult to add.
If benchmark tests were added, please run the benchmarks in GitHub Actions for the consistent environment, and the instructions could accord to: https://spark.apache.org/developer-tools.html#github-workflow-benchmarks.
-->
N/A
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia commented on a diff in pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia commented on code in PR #38605:
URL: https://github.com/apache/spark/pull/38605#discussion_r1019647668
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,87 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
+Every field is optional. For non-message proto fields, there is also no `hasXXX`
+functions to easy tell if a filed is set or not-set. For those non-message proto,
+they also have default values. E.g. int has 0 as the default value.
+
+
+### Required field
+
+Even proto3 does not offer `required` constraint, there is still some fields that
+are semantically required. For such case, we share add comment on the field to mark
+it as required. The expectation for client implementation (or any submitted proto plan)
+is that such fields should be always set, and server will always assume such fields
+are set and use whatever values of the fields directly. It is the client side's fault
+to not offer meaningful value for `required` field and in that case, the behavior on
+the server side is not defined.
+
+
+### Optional field and default value
+
+Optional fields could have default values when the field is not set, and we are seeing
+two cases that depends on whether the default value for the proto field is consistent
+with the corresponding Spark parameter default value.
+
+If both default values of the proto field and Spark parameter are the same, we keep the
+proto field as is.
+
+For example:
+```Scala
+// Spark Plan.
+class FooPlan(size: Long = 0)
+```
+
+```protobuf
+// Connect proto.
+message Foo {
+ int64 size;
Review Comment:
I intentionally do not add the proto field number. This is to avoid people mis-understand it as a default value thus causing confusions.
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] grundprinzip commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
grundprinzip commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1310967986
TBF I only recently learned about this. If we can use it the refactoring will be worth 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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia closed pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia closed pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
URL: https://github.com/apache/spark/pull/38605
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] grundprinzip commented on a diff in pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
grundprinzip commented on code in PR #38605:
URL: https://github.com/apache/spark/pull/38605#discussion_r1022745612
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,41 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
+For non-message proto fields, there is also no `has_field_name` functions to easy tell
+if a filed is set or not-set. (Read [proto3 field rules](https://developers.google.com/protocol-buffers/docs/proto3#specifying_field_rules))
+
+
+### Required field
+
+Even proto3 does not offer `required` constraint, there are still some fields that
+are semantically required. For such case, we shall add comment `(Required)` on the
+field to indicate it as required. The expectation for client implementation
+(or any submitted proto plan) is that such fields should be always set, and server will
+always assume such fields are set and use whatever values from the fields directly.
+It is the client side's fault to not offer meaningful value for `required` field and in that case,
+the behavior on the server side is decided by the default value of the field.
Review Comment:
```suggestion
When adding fields that have required semantics, developers are required to follow
the outlined process. Fields that are semantically required for the server to
correctly process the incoming message must be documented with `(Required)`. For scalar
fields the server will not perform any additional input validation. For compound fields,
the server will perform minimal checks to avoid null pointer exceptions but will not
perform any semantic validation.
```
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,41 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
Review Comment:
```suggestion
Spark Connect adopts proto3, which does not support the use of the `required` constraint anymore.
```
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,41 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
+For non-message proto fields, there is also no `has_field_name` functions to easy tell
+if a filed is set or not-set. (Read [proto3 field rules](https://developers.google.com/protocol-buffers/docs/proto3#specifying_field_rules))
+
+
+### Required field
+
+Even proto3 does not offer `required` constraint, there are still some fields that
+are semantically required. For such case, we shall add comment `(Required)` on the
+field to indicate it as required. The expectation for client implementation
+(or any submitted proto plan) is that such fields should be always set, and server will
+always assume such fields are set and use whatever values from the fields directly.
+It is the client side's fault to not offer meaningful value for `required` field and in that case,
+the behavior on the server side is decided by the default value of the field.
+
+Example:
+```protobuf
+message DataSource {
+ // (Required) Supported formats include: parquet, orc, text, json, parquet, csv, avro.
+ string format = 1;
+}
+```
+
+
+### Optional field and default value
+
+Semantically optional fields should be marked by proto3 `optional`. The server side will decide
+if to use the generated `has_field_name` to tell the field is set (when its default value
+is different from the Spark parameter default value) or use the field default value directly
+(when its default value is the same as Spark parameter default value). It is also required
+to use `(Optional)` in the comment to indicate this field is optional.
Review Comment:
```suggestion
Semantically optional fields must be marked by `optional`. The server side will
then use this information to branch into different behaviors based on the presence or absence of this field.
Due to the lack of configurable default values for scalar types, the pure presence of
an optional value does not define its default value. The server side implementation will interpret the observed value based on its own rules.
```
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,41 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
+For non-message proto fields, there is also no `has_field_name` functions to easy tell
+if a filed is set or not-set. (Read [proto3 field rules](https://developers.google.com/protocol-buffers/docs/proto3#specifying_field_rules))
+
+
+### Required field
+
+Even proto3 does not offer `required` constraint, there are still some fields that
+are semantically required. For such case, we shall add comment `(Required)` on the
+field to indicate it as required. The expectation for client implementation
+(or any submitted proto plan) is that such fields should be always set, and server will
+always assume such fields are set and use whatever values from the fields directly.
+It is the client side's fault to not offer meaningful value for `required` field and in that case,
+the behavior on the server side is decided by the default value of the field.
+
+Example:
+```protobuf
+message DataSource {
+ // (Required) Supported formats include: parquet, orc, text, json, parquet, csv, avro.
+ string format = 1;
+}
+```
+
+
+### Optional field and default value
Review Comment:
```suggestion
### Optional fields
```
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] AmplabJenkins commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
AmplabJenkins commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1316622345
Can one of the admins verify this patch?
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] grundprinzip commented on a diff in pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
grundprinzip commented on code in PR #38605:
URL: https://github.com/apache/spark/pull/38605#discussion_r1019652632
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,87 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
+Every field is optional. For non-message proto fields, there is also no `hasXXX`
+functions to easy tell if a filed is set or not-set. For those non-message proto,
+they also have default values. E.g. int has 0 as the default value.
Review Comment:
Hey, please have a look at https://developers.google.com/protocol-buffers/docs/proto3#specifying_field_rules and check if this is not applicable in this case.
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan closed pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
cloud-fan closed pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
URL: https://github.com/apache/spark/pull/38605
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1310944726
@grundprinzip @cloud-fan @HyukjinKwon @zhengruifeng @hvanhovell
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1314804133
@zhengruifeng @HyukjinKwon @cloud-fan please take a look on this updated version of the proto style guide.
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] grundprinzip commented on a diff in pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
grundprinzip commented on code in PR #38605:
URL: https://github.com/apache/spark/pull/38605#discussion_r1023155908
##########
connector/connect/README.md:
##########
@@ -70,3 +70,4 @@ When contributing a new client please be aware that we strive to have a common
user experience across all languages. Please follow the below guidelines:
* [Connection string configuration](docs/client-connection-string.md)
+* [Adding-proto-messages](docs/adding-proto-messages.md)
Review Comment:
```suggestion
* [Adding new messages](docs/adding-proto-messages.md) in the Spark Connect protocol.
```
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] grundprinzip commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
grundprinzip commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1310962668
From what I get we can explicitly set fields as optional and we get an `hasXXX` method
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1310964795
@grundprinzip ah let me check that. If so probably we need refactor proto a lot.
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1311029606
@grundprinzip
I am gonna to refactor the proto based on this then.
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] amaliujia commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
amaliujia commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1315721838
@grundprinzip suggestions applied. The doc look much better now with some more details filled in. Minding take another look?
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on a diff in pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on code in PR #38605:
URL: https://github.com/apache/spark/pull/38605#discussion_r1022545314
##########
connector/connect/docs/adding-proto-messages.md:
##########
@@ -0,0 +1,41 @@
+# Required, Optional and default values
+
+Connect adopts proto3, which does not support `required` constraint anymore.
Review Comment:
```suggestion
Spark Connect adopts proto3, which does not support `required` constraint anymore.
```
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org
[GitHub] [spark] cloud-fan commented on pull request #38605: [SPARK-41103][CONNECT][DOC] Document how to add a new proto field of messages
Posted by GitBox <gi...@apache.org>.
cloud-fan commented on PR #38605:
URL: https://github.com/apache/spark/pull/38605#issuecomment-1316616610
thanks, merging to master!
--
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: reviews-unsubscribe@spark.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: reviews-unsubscribe@spark.apache.org
For additional commands, e-mail: reviews-help@spark.apache.org