[SPARK-17947] [SQL] Add Doc and Comment about spark.sql.debug

[gatorsmile]

What changes were proposed in this pull request?

Just document the impact of spark.sql.debug:

When enabling the debug, Spark SQL internal table properties are not filtered out; however, some related DDL commands (e.g., Analyze Table and CREATE TABLE LIKE) might not work properly.

How was this patch tested?

N/A

[rxin]

Why do they not work properly?

[SparkQA]

Test build #66987 has finished for PR 15494 at commit a020f66.

• This patch passes all tests.
• This patch merges cleanly.
• This patch adds no public classes.

[gatorsmile]

@rxin. The failed test cases are accessible in the PR: #15478

ANALYZE TABLE will fail due to the checking when we try to alter the table properties.

SHOW CREATE TABLE also outputs the table properties that should not be part of the output CREAT TABLE statement.

CREATE TABLE LIKE always excludes all the table properties of the source table. However, we might make a change in this part. This is still waiting for your input in another PR. See the discussion

[cloud-fan]

@rxin because we are assuming that all the hive hacks are isolated inside HiveExternalCatalog, but the debug mode will break it and spread the hive metastore specific table properties outside of HiveExternalCatalog. Then some commands like SHOW CREATE TABLE, ALTER TABLE will be broken, but should be ok as it's a "debug" mode anyway.

[cloud-fan]

thanks, merging to master!