From 659d981c66ac98ccf1ca5a1e525053fc9417c9f6 Mon Sep 17 00:00:00 2001
From: zwangsheng <2213335496@qq.com>
Date: Wed, 13 Apr 2022 18:39:29 +0800
Subject: [PATCH] [KYUUBI #2337] [DOCS] Access Kyuubi with Kyuubi JDBC Driver

### _Why are the changes needed?_

Access Kyuubi with Kyuubi-Hive-JDBC Documentation is missing
Close #2337

### _How was this patch tested?_
- [ ] Add some test cases that check the changes thoroughly including negative and positive cases if possible

- [x] Add screenshots for manual tests if appropriate

- [ ] [Run test](https://kyuubi.apache.org/docs/latest/develop_tools/testing.html#running-tests) locally before make a pull request

Closes #2339 from zwangsheng/ISSUE/#2337.

Closes #2337

d4154e6d [zwangsheng] fix mvn url
510708ce [zwangsheng] fix
c4bb9366 [zwangsheng] KYUUBI-2337

Authored-by: zwangsheng <2213335496@qq.com>
Signed-off-by: ulysses-you <ulyssesyou@apache.org>
---
 docs/client/index.rst      |   1 +
 docs/client/kyuubi_jdbc.md | 101 +++++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+)
 create mode 100644 docs/client/kyuubi_jdbc.md

diff --git a/docs/client/index.rst b/docs/client/index.rst
index a866bee49d0..ded20a6b314 100644
--- a/docs/client/index.rst
+++ b/docs/client/index.rst
@@ -24,4 +24,5 @@ Client Documentation
     :numbered: 2
 
     hive_jdbc
+    kyuubi_jdbc
     kerberized_kyuubi
diff --git a/docs/client/kyuubi_jdbc.md b/docs/client/kyuubi_jdbc.md
new file mode 100644
index 00000000000..5851b59cbe2
--- /dev/null
+++ b/docs/client/kyuubi_jdbc.md
@@ -0,0 +1,101 @@
+<!--
+ - 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.
+ -->
+
+<div align=center>
+
+![](../imgs/kyuubi_logo.png)
+
+</div>
+
+# Access Kyuubi with Kyuubi JDBC Drivers
+
+## Install Kyuubi JDBC
+
+For programing, the easiest way to get `kyuubi-hive-jdbc-shaded` is from [the maven central](https://mvnrepository.com/artifact/org.apache.kyuubi/kyuubi-hive-jdbc-shaded). For example,
+
+- **maven**
+```xml
+<dependency>
+    <groupId>org.apache.kyuubi</groupId>
+    <artifactId>kyuubi-hive-jdbc-shaded</artifactId>
+    <version>1.5.0-incubating</version>
+</dependency>
+```
+
+- **sbt**
+```scala
+libraryDependencies += "org.apache.kyuubi" % "kyuubi-hive-jdbc-shaded" % "1.5.0-incubating"
+```
+
+- **gradle**
+```gradle
+implementation group: 'org.apache.kyuubi', name: 'kyuubi-hive-jdbc-shaded', version: '1.5.0-incubating'
+```
+
+For BI tools, please refer to [Quick Start](../quick_start/index.html) to check the guide for the BI tool used.
+If you find there is no specific document for the BI tool that you are using, don't worry, the configuration part for all BI tools are basically the same.
+Also, we will appreciate if you can help us to improve the document.
+
+## JDBC URL
+
+JDBC URLs have the following format:
+
+```
+jdbc:hive2://<host>:<port>/<dbName>;<sessionVars>?<kyuubiConfs>#<[spark|hive]Vars>
+```
+
+JDBC Parameter | Description
+---------------| -----------
+host | The cluster node hosting Kyuubi Server.
+port | The port number to which is Kyuubi Server listening.
+dbName | Optional database name to set the current database to run the query against, use `default` if absent.
+sessionVars | Optional `Semicolon(;)` separated `key=value` parameters for the JDBC/ODBC driver. Such as `user`, `password` and `hive.server2.proxy.user`.
+kyuubiConfs | Optional `Semicolon(;)` separated `key=value` parameters for Kyuubi server to create the corresponding engine, dismissed if engine exists.
+[spark&#124;hive]Vars | Optional `Semicolon(;)` separated `key=value` parameters for Spark/Hive variables used for variable substitution.
+
+## Example
+
+```
+jdbc:hive2://localhost:10009/default;hive.server2.proxy.user=proxy_user?kyuubi.engine.share.level=CONNECTION;spark.ui.enabled=false#var_x=y
+```
+
+## Alert
+
+If you already have `hadoop-common` dependency in your classpath, you should exclude `hadoop-client-api` from `kyuubi-hive-jdbc-shaded` to avoid class confliction. For example:
+
+- **maven**
+```xml
+<dependency>
+    <groupId>org.apache.kyuubi</groupId>
+    <artifactId>kyuubi-hive-jdbc-shaded</artifactId>
+    <version>1.5.0-incubating</version>
+    <exclusion>
+        <groupId>org.apache.hadoop</groupId>
+        <artifactId>hadoop-client-api</artifactId>
+    </exclusion>
+</dependency>
+```
+
+- **sbt**
+```scala
+libraryDependencies += "org.apache.kyuubi" % "kyuubi-hive-jdbc-shaded" % "1.5.0-incubating" exclude("org.apache.hadoop", "hadoop-client-api")
+```
+
+- **gradle**
+```gradle
+implementation (group: 'org.apache.kyuubi', name: 'kyuubi-hive-jdbc-shaded', version: '1.5.0-incubating') { exclude group: 'org.apache.hadoop', module: 'hadoop-client-api' }
+```
\ No newline at end of file