From c2bea045e3628081bca1ba752669a5bc009ebd00 Mon Sep 17 00:00:00 2001 From: Takeshi Yamamuro Date: Wed, 28 Oct 2020 11:21:35 +0900 Subject: [PATCH] [SPARK-33264][SQL][DOCS] Add a dedicated page for SQL-on-file in SQL documents ### What changes were proposed in this pull request? This PR intends to add a dedicated page for SQL-on-file in SQL documents. This comes from the comment: https://github.com/apache/spark/pull/30095/files#r508965149 ### Why are the changes needed? For better documentations. ### Does this PR introduce _any_ user-facing change? Screen Shot 2020-10-28 at 9 56 59 ### How was this patch tested? N/A Closes #30165 from maropu/DocForFile. Authored-by: Takeshi Yamamuro Signed-off-by: Takeshi Yamamuro --- docs/_data/menu-sql.yaml | 2 + docs/sql-ref-syntax-qry-select-file.md | 76 ++++++++++++++++++++++++++ docs/sql-ref-syntax-qry-select.md | 3 +- docs/sql-ref-syntax-qry.md | 1 + docs/sql-ref-syntax.md | 1 + 5 files changed, 82 insertions(+), 1 deletion(-) create mode 100644 docs/sql-ref-syntax-qry-select-file.md diff --git a/docs/_data/menu-sql.yaml b/docs/_data/menu-sql.yaml index 63f6b4a0a2..2207bd6a17 100644 --- a/docs/_data/menu-sql.yaml +++ b/docs/_data/menu-sql.yaml @@ -175,6 +175,8 @@ url: sql-ref-syntax-qry-select-hints.html - text: Inline Table url: sql-ref-syntax-qry-select-inline-table.html + - text: File + url: sql-ref-syntax-qry-select-file.html - text: JOIN url: sql-ref-syntax-qry-select-join.html - text: LIKE Predicate diff --git a/docs/sql-ref-syntax-qry-select-file.md b/docs/sql-ref-syntax-qry-select-file.md new file mode 100644 index 0000000000..c3dc406ee7 --- /dev/null +++ b/docs/sql-ref-syntax-qry-select-file.md @@ -0,0 +1,76 @@ +--- +layout: global +title: File +displayTitle: File +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. +--- + +### Description + +You can query a file with a specified format directly with SQL. + +### Syntax + +```sql +file_format.`file_path` +``` + +### Parameters + +* **file_format** + + Specifies a file format for a given file path, could be TEXTFILE, ORC, PARQUET, etc. + +* **file_path** + + Specifies a file path with a given format. + +### Examples + +```sql +-- PARQUET file +SELECT * FROM parquet.`examples/src/main/resources/users.parquet`; ++------+--------------+----------------+ +| name|favorite_color|favorite_numbers| ++------+--------------+----------------+ +|Alyssa| null| [3, 9, 15, 20]| +| Ben| red| []| ++------+--------------+----------------+ + +-- ORC file +SELECT * FROM orc.`examples/src/main/resources/users.orc`; ++------+--------------+----------------+ +| name|favorite_color|favorite_numbers| ++------+--------------+----------------+ +|Alyssa| null| [3, 9, 15, 20]| +| Ben| red| []| ++------+--------------+----------------+ + +-- JSON file +SELECT * FROM json.`examples/src/main/resources/people.json`; ++----+-------+ +| age| name| ++----+-------+ +|null|Michael| +| 30| Andy| +| 19| Justin| ++----+-------+ +``` + +### Related Statements + +* [SELECT](sql-ref-syntax-qry-select.html) diff --git a/docs/sql-ref-syntax-qry-select.md b/docs/sql-ref-syntax-qry-select.md index 655766d4c6..bac7c2bc6a 100644 --- a/docs/sql-ref-syntax-qry-select.md +++ b/docs/sql-ref-syntax-qry-select.md @@ -85,7 +85,7 @@ SELECT [ hints , ... ] [ ALL | DISTINCT ] { named_expression [ , ... ] } * [Table-value function](sql-ref-syntax-qry-select-tvf.html) * [Inline table](sql-ref-syntax-qry-select-inline-table.html) * Subquery - * [File](sql-data-sources-load-save-functions.html#run-sql-on-files-directly) + * [File](sql-ref-syntax-qry-select-file.html) * **PIVOT** @@ -165,6 +165,7 @@ SELECT [ hints , ... ] [ ALL | DISTINCT ] { named_expression [ , ... ] } * [Common Table Expression](sql-ref-syntax-qry-select-cte.html) * [Hints](sql-ref-syntax-qry-select-hints.html) * [Inline Table](sql-ref-syntax-qry-select-inline-table.html) +* [File](sql-ref-syntax-qry-select-file.html) * [JOIN](sql-ref-syntax-qry-select-join.html) * [LIKE Predicate](sql-ref-syntax-qry-select-like.html) * [Set Operators](sql-ref-syntax-qry-select-setops.html) diff --git a/docs/sql-ref-syntax-qry.md b/docs/sql-ref-syntax-qry.md index d55ea43d15..6751b90e12 100644 --- a/docs/sql-ref-syntax-qry.md +++ b/docs/sql-ref-syntax-qry.md @@ -39,6 +39,7 @@ ability to generate logical and physical plan for a given query using * [Common Table Expression](sql-ref-syntax-qry-select-cte.html) * [Hints](sql-ref-syntax-qry-select-hints.html) * [Inline Table](sql-ref-syntax-qry-select-inline-table.html) + * [File](sql-ref-syntax-qry-select-file.html) * [JOIN](sql-ref-syntax-qry-select-join.html) * [LIKE Predicate](sql-ref-syntax-qry-select-like.html) * [Set Operators](sql-ref-syntax-qry-select-setops.html) diff --git a/docs/sql-ref-syntax.md b/docs/sql-ref-syntax.md index 4e58abb2a8..f3d35b57d9 100644 --- a/docs/sql-ref-syntax.md +++ b/docs/sql-ref-syntax.md @@ -56,6 +56,7 @@ Spark SQL is Apache Spark's module for working with structured data. The SQL Syn * [HAVING Clause](sql-ref-syntax-qry-select-having.html) * [Hints](sql-ref-syntax-qry-select-hints.html) * [Inline Table](sql-ref-syntax-qry-select-inline-table.html) + * [File](sql-ref-syntax-qry-select-file.html) * [JOIN](sql-ref-syntax-qry-select-join.html) * [LIKE Predicate](sql-ref-syntax-qry-select-like.html) * [LIMIT Clause](sql-ref-syntax-qry-select-limit.html)