You are viewing a plain text version of this content. The canonical link for it is here.
Posted to reviews@spark.apache.org by "itholic (via GitHub)" <gi...@apache.org> on 2023/03/08 12:12:33 UTC
[GitHub] [spark] itholic opened a new pull request, #40336: [SPARK-42706][SQL][DOCS] List the error class to user-facing documentation.
itholic opened a new pull request, #40336:
URL: https://github.com/apache/spark/pull/40336
### What changes were proposed in this pull request?
This PR proposes to document Spark SQL error classes to [Spark SQL Guide](https://spark.apache.org/docs/latest/sql-programming-guide.html).
- Error Conditions
<img width="1077" alt="Screen Shot 2023-03-08 at 8 54 43 PM" src="https://user-images.githubusercontent.com/44108233/223706823-7817b57d-c032-4817-a440-7f79119fa0b4.png">
- SQLSTATE Codes
<img width="1139" alt="Screen Shot 2023-03-08 at 8 54 54 PM" src="https://user-images.githubusercontent.com/44108233/223706860-3f64b00b-fa0d-47e0-b154-0d7be92b8637.png">
- Error Classes that includes sub-error classes (`INVALID_FORMAT` as an example)
<img width="1045" alt="Screen Shot 2023-03-08 at 9 10 22 PM" src="https://user-images.githubusercontent.com/44108233/223709925-74144f41-8836-45dc-b851-5d96ac8aa38c.png">
### Why are the changes needed?
To improve the usability for error messages for Spark SQL.
### Does this PR introduce _any_ user-facing change?
No API change, but yes, it's user-facing documentation.
### How was this patch tested?
Manually built docs and check the contents one-by-one compare to [error-classes.json](https://github.com/apache/spark/blob/master/core/src/main/resources/error/error-classes.json).
--
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] srielau commented on a diff in pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "srielau (via GitHub)" <gi...@apache.org>.
srielau commented on code in PR #40336:
URL: https://github.com/apache/spark/pull/40336#discussion_r1129592566
##########
docs/sql-error-conditions-sqlstates.md:
##########
@@ -0,0 +1,720 @@
+---
+layout: global
+title: SQLSTATE Codes
+displayTitle: SQLSTATE Codes
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Most error classes returned by Spark SQL are associated with a 5 character `SQLSTATE`.
+A `SQLSTATE` is a SQL standard encoding for error conditions commonly used by `JDBC`, `ODBC`, and other client APIs.
+
+A `SQLSTATE` consists of two portions: A two character class, and a three character subclass.
+Each character must be a digit `'0'` to `'9'` or `'A'` to `'Z'`.
+
+While many `SQLSTATE` values are prescribed by the SQL standard, others are common in the industry, specific to Spark.
+
+For an ordered list of error classes see: [Error Conditions in Spark SQL](sql-error-conditions.html)
+
+Spark SQL uses the following `SQLSTATE` classes:
+
+## Class `0A`: feature not supported
+
+<table class="table">
Review Comment:
Isn't .md supposed to take care of the HTML conversion of the table?
--
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] MaxGekk commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "MaxGekk (via GitHub)" <gi...@apache.org>.
MaxGekk commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1460234386
@itholic Did you write those files manually, or generated by a script?
--
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] MaxGekk commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "MaxGekk (via GitHub)" <gi...@apache.org>.
MaxGekk commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1462195522
+1, LGTM. Merging to master.
Thank you, @itholic and @srielau for review.
--
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] MaxGekk closed pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "MaxGekk (via GitHub)" <gi...@apache.org>.
MaxGekk closed pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
URL: https://github.com/apache/spark/pull/40336
--
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] itholic commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "itholic (via GitHub)" <gi...@apache.org>.
itholic commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1460067796
cc @srielau @MaxGekk @cloud-fan This is user-facing documentation for SQL error classes.
--
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] itholic commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "itholic (via GitHub)" <gi...@apache.org>.
itholic commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1461084364
> @itholic Did you write those files manually, or generated by a script?
I did both. I used the script, and for the parts that didn't print correctly, I fixed them manually by checking the page one by one. Since the script is not very polished for now, let me submit it as a follow-up task if we aim for automation in the future.
--
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] MaxGekk commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "MaxGekk (via GitHub)" <gi...@apache.org>.
MaxGekk commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1467595434
@gatorsmile I stoped merging PRs related to error classes after RC0. Need to re-check carefully which error classes are in branch-3.4 already. @itholic Please, backport the changes to branch-3.4.
--
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] itholic commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "itholic (via GitHub)" <gi...@apache.org>.
itholic commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1469347578
3.4: https://github.com/apache/spark/pull/40433
--
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 #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "cloud-fan (via GitHub)" <gi...@apache.org>.
cloud-fan commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1469189625
It's probably ok to mention non-existing errors in the doc in 3.4
--
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] gatorsmile commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "gatorsmile (via GitHub)" <gi...@apache.org>.
gatorsmile commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1467329403
@MaxGekk should we merge it to 3.4?
--
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] itholic commented on a diff in pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "itholic (via GitHub)" <gi...@apache.org>.
itholic commented on code in PR #40336:
URL: https://github.com/apache/spark/pull/40336#discussion_r1129664407
##########
docs/sql-error-conditions-sqlstates.md:
##########
@@ -0,0 +1,720 @@
+---
+layout: global
+title: SQLSTATE Codes
+displayTitle: SQLSTATE Codes
+license: |
+ Licensed to the Apache Software Foundation (ASF) under one or more
+ contributor license agreements. See the NOTICE file distributed with
+ this work for additional information regarding copyright ownership.
+ The ASF licenses this file to You under the Apache License, Version 2.0
+ (the "License"); you may not use this file except in compliance with
+ the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+---
+
+Most error classes returned by Spark SQL are associated with a 5 character `SQLSTATE`.
+A `SQLSTATE` is a SQL standard encoding for error conditions commonly used by `JDBC`, `ODBC`, and other client APIs.
+
+A `SQLSTATE` consists of two portions: A two character class, and a three character subclass.
+Each character must be a digit `'0'` to `'9'` or `'A'` to `'Z'`.
+
+While many `SQLSTATE` values are prescribed by the SQL standard, others are common in the industry, specific to Spark.
+
+For an ordered list of error classes see: [Error Conditions in Spark SQL](sql-error-conditions.html)
+
+Spark SQL uses the following `SQLSTATE` classes:
+
+## Class `0A`: feature not supported
+
+<table class="table">
Review Comment:
I am not entirely sure, but it seems like Jekyll(the tool used for building documentation in OSS Spark) has specific rules for conversion. I checked the table may not be built properly if we don't use the html tag here.
--
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] itholic commented on pull request #40336: [SPARK-42706][SQL][DOCS] Document the Spark SQL error classes in user-facing documentation.
Posted by "itholic (via GitHub)" <gi...@apache.org>.
itholic commented on PR #40336:
URL: https://github.com/apache/spark/pull/40336#issuecomment-1460398791
> @itholic Did you write those files manually, or generated by a script?
I did both. I used the script, and for the parts that didn't print correctly, I fixed them manually by checking the page one by one. Since the script is not very polished, I will submit it as a follow-up task if we aim for automation in the future 🥲
--
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