diff --git a/docs/assets/themes/zeppelin/img/docs-img/click_create_button.png b/docs/assets/themes/zeppelin/img/docs-img/click_create_button.png new file mode 100644 index 00000000000..d6f3c15b910 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/click_create_button.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/click_interpreter_binding_button.png b/docs/assets/themes/zeppelin/img/docs-img/click_interpreter_binding_button.png new file mode 100644 index 00000000000..1c1a36ac51e Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/click_interpreter_binding_button.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/edit_dependencies.png b/docs/assets/themes/zeppelin/img/docs-img/edit_dependencies.png new file mode 100644 index 00000000000..30f22db25d1 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/edit_dependencies.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/edit_properties.png b/docs/assets/themes/zeppelin/img/docs-img/edit_properties.png new file mode 100644 index 00000000000..e67d49bcff4 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/edit_properties.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/hive_setting.png b/docs/assets/themes/zeppelin/img/docs-img/hive_setting.png new file mode 100644 index 00000000000..31a9821360e Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/hive_setting.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/jdbc-multi-connection-setting.png b/docs/assets/themes/zeppelin/img/docs-img/jdbc-multi-connection-setting.png deleted file mode 100644 index 4b4d7b50ff2..00000000000 Binary files a/docs/assets/themes/zeppelin/img/docs-img/jdbc-multi-connection-setting.png and /dev/null differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/jdbc-simple-connection-setting.png b/docs/assets/themes/zeppelin/img/docs-img/jdbc-simple-connection-setting.png deleted file mode 100644 index 6134b39a7a6..00000000000 Binary files a/docs/assets/themes/zeppelin/img/docs-img/jdbc-simple-connection-setting.png and /dev/null differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/jdbc_interpreter_binding.png b/docs/assets/themes/zeppelin/img/docs-img/jdbc_interpreter_binding.png new file mode 100644 index 00000000000..86a7ce418b2 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/jdbc_interpreter_binding.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/mysql_setting.png b/docs/assets/themes/zeppelin/img/docs-img/mysql_setting.png new file mode 100644 index 00000000000..f4e4a65b3ed Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/mysql_setting.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/phoenix_thick_setting.png b/docs/assets/themes/zeppelin/img/docs-img/phoenix_thick_setting.png new file mode 100644 index 00000000000..57f524e445d Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/phoenix_thick_setting.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/phoenix_thin_setting.png b/docs/assets/themes/zeppelin/img/docs-img/phoenix_thin_setting.png new file mode 100644 index 00000000000..8f93ab6ac86 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/phoenix_thin_setting.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/run_paragraph_with_jdbc.png b/docs/assets/themes/zeppelin/img/docs-img/run_paragraph_with_jdbc.png new file mode 100644 index 00000000000..41638da6f83 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/run_paragraph_with_jdbc.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/select_name_and_group.png b/docs/assets/themes/zeppelin/img/docs-img/select_name_and_group.png new file mode 100644 index 00000000000..9c963b8ae9d Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/select_name_and_group.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/tajo_setting.png b/docs/assets/themes/zeppelin/img/docs-img/tajo_setting.png new file mode 100644 index 00000000000..1e56d648f1a Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/tajo_setting.png differ diff --git a/docs/assets/themes/zeppelin/img/docs-img/tested_databases.png b/docs/assets/themes/zeppelin/img/docs-img/tested_databases.png new file mode 100644 index 00000000000..fb6ace22d85 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/tested_databases.png differ diff --git a/docs/interpreter/jdbc.md b/docs/interpreter/jdbc.md index d3104cb9d5d..25230947da6 100644 --- a/docs/interpreter/jdbc.md +++ b/docs/interpreter/jdbc.md @@ -25,102 +25,136 @@ limitations under the License. ## Overview -This interpreter lets you create a JDBC connection to any data source, by now it has been tested with: +JDBC interpreter lets you create a JDBC connection to any data sources seamlessly. By now, it has been tested with: -* Postgres -* MySql -* MariaDB -* Redshift -* Apache Hive -* Apache Phoenix -* Apache Drill (Details on using [Drill JDBC Driver](https://drill.apache.org/docs/using-the-jdbc-driver)) -* Apache Tajo +
+
+ +
+
+
  • + Postgresql - + JDBC Driver +
    • +
  • + Mysql - + JDBC Driver +
    • +
  • + MariaDB - + JDBC Driver +
    • +
  • + Redshift - + JDBC Driver +
    • +
  • + Apache Hive - + JDBC Driver +
    • +
  • + Apache Phoenix itself is a JDBC driver +
    • +
  • + Apache Drill - + JDBC Driver +
    • +
  • + Apache Tajo - + JDBC Driver +
    • +
    +
    + +If you are using other databases not in the above list, please feel free to share your use case. It would be helpful to improve the functionality of JDBC interpreter. + +## Create a new JDBC Interpreter + +First, click `+ Create` button at the top-right corner in the interpreter setting page. -If someone else used another database please report how it works to improve functionality. + -## Create Interpreter +Fill `Interpreter name` field with whatever you want to use as the alias(e.g. mysql, mysql2, hive, redshift, and etc..). Please note that this alias will be used as `%interpreter_name` to call the interpreter in the paragraph. +Then select `jdbc` as an `Interpreter group`. -When you create a interpreter by default use PostgreSQL with the next properties: + + +The default driver of JDBC interpreter is set as `PostgreSQL`. It means Zeppelin includes `PostgreSQL` driver jar in itself. +So you don't need to add any dependencies(e.g. the artifact name or path for `PostgreSQL` driver jar) for `PostgreSQL` connection. +The JDBC interpreter properties are defined by default like below. - - + + + + + - + + + - + +
    namevalueNameDefault ValueDescription
    common.max_count 1000The maximun number of SQL result to display
    default.driver org.postgresql.DriverJDBC Driver Name
    default.password********The JDBC user password
    default.url jdbc:postgresql://localhost:5432/The URL for JDBC
    default.user gpadmin
    The JDBC user name
    -It is not necessary to add driver jar to the classpath for PostgreSQL as it is included in Zeppelin. +If you want to connect other databases such as `Mysql`, `Redshift` and `Hive`, you need to edit the property values. +The below example is for `Mysql` connection. -### Simple connection + -Prior to creating the interpreter it is necessary to add maven coordinate or path of the JDBC driver to the Zeppelin classpath. To do this you must edit dependencies artifact(ex. `mysql:mysql-connector-java:5.1.38`) in interpreter menu as shown: +The last step is **Dependency Setting**. Since Zeppelin only includes `PostgreSQL` driver jar by default, you need to add each driver's maven coordinates or JDBC driver's jar file path for the other databases. -
    -
    - -
    -
    + + +That's it. You can find more JDBC connection setting examples([Mysql](#mysql), [Apache Hive](#apache-hive), [Apache Phoenix](#apache-phoenix), and [Apache Tajo](#apache-tajo)) in [this section](#examples). -To create the interpreter you need to specify connection parameters as shown in the table. +## More properties +There are more JDBC interpreter properties you can specify like below. - - + + - - + + - - + + - - + + - - + + - - - -
    namevalueProperty NameDescription
    common.max_count1000common.max_resultMax number of SQL result to display to prevent the browser overload. This is common properties for all connections
    default.driverdriver namezeppelin.jdbc.auth.typeTypes of authentications' methods supported are SIMPLE, and KERBEROS
    default.password********zeppelin.jdbc.principalThe principal name to load from the keytab
    default.urljdbc urlzeppelin.jdbc.keytab.locationThe path to the keytab file
    default.useruser name
    -### Multiple connections - -JDBC interpreter also allows connections to multiple data sources. It is necessary to set a prefix for each connection to reference it in the paragraph in the form of `%jdbc(prefix)`. Before you create the interpreter it is necessary to add each driver's maven coordinates or JDBC driver's jar file path to the Zeppelin classpath. To do this you must edit the dependencies of JDBC interpreter in interpreter menu as following: - -
    -
    - -
    -
    - -You can add all the jars you need to make multiple connections into the same JDBC interpreter. To create the interpreter you must specify the parameters. For example we will create two connections to MySQL and Redshift, the respective prefixes are `default` and `redshift`: +You can also add more properties by using this [method](http://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html#getConnection%28java.lang.String,%20java.util.Properties%29). +For example, if a connection needs a schema parameter, it would have to add the property as follows: @@ -128,16 +162,62 @@ You can add all the jars you need to make multiple connections into the same JDB - - + + +
    value
    common.max_count1000default.schemaschema_name
    + +## Binding JDBC interpter to notebook +To bind the interpreters created in the interpreter setting page, click the gear icon at the top-right corner. + + + +Select(blue) or deselect(white) the interpreter buttons depending on your use cases. +If you need to use more than one interpreter in the notebook, activate several buttons. +Don't forget to click `Save` button, or you will face `Interpreter *** is not found` error. + + + +## How to use +### Run the paragraph with JDBC interpreter +To test whether your databases and Zeppelin are successfully connected or not, type `%jdbc_interpreter_name`(e.g. `%mysql`) at the top of the paragraph and run `show databases`. + +```sql +%jdbc_interpreter_name +show databases +``` +If the paragraph is `FINISHED` without any errors, a new paragraph will be automatically added after the previous one with `%jdbc_interpreter_name`. +So you don't need to type this prefix in every paragraphs' header. + + + +### Apply Zeppelin Dynamic Forms + +You can leverage [Zeppelin Dynamic Form](../manual/dynamicform.html) inside your queries. You can use both the `text input` and `select form` parametrization features. + +```sql +%jdbc_interpreter_name +SELECT name, country, performer +FROM demo.performers +WHERE name='{{"{{performer=Sheryl Crow|Doof|Fanfarlo|Los Paranoia"}}}}' +``` + +## Examples +Here are some examples you can refer to. Including the below connectors, you can connect every databases as long as it can be configured with it's JDBC driver. + +### Mysql + + + +##### Properties + - - + + - - + + @@ -145,262 +225,200 @@ You can add all the jars you need to make multiple connections into the same JDB - + - - + + +
    default.drivercom.mysql.jdbc.DriverNameValue
    default.password********default.drivercom.mysql.jdbc.Driver
    default.url
    default.usermysql-usermysql_user
    redshift.drivercom.amazon.redshift.jdbc4.Driverdefault.passwordmysql_password
    + +##### Dependencies + - - + + - - + + - - - -
    redshift.password********ArtifactExcludes
    redshift.urljdbc:redshift://examplecluster.abc123xyz789.us-west-2.redshift.amazonaws.com:5439mysql:mysql-connector-java:5.1.38
    redshift.userredshift-user
    +### Apache Hive -## Bind to Notebook -In the `Notebook` click on the `settings` icon at the top-right corner. Use select/deselect to specify the interpreters to be used in the `Notebook`. - -## More Properties -You can modify the interpreter configuration in the `Interpreter` section. The most common properties are as follows, but you can specify other properties that need to be connected. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    Property NameDescription
    {prefix}.urlJDBC URL to connect, the URL must include the name of the database
    {prefix}.userJDBC user name
    {prefix}.passwordJDBC password
    {prefix}.driverJDBC driver name.
    common.max_resultMax number of SQL result to display to prevent the browser overload. This is common properties for all connections
    zeppelin.jdbc.auth.typeTypes of authentications' methods supported are SIMPLE, and KERBEROS
    zeppelin.jdbc.principalThe principal name to load from the keytab
    zeppelin.jdbc.keytab.locationThe path to the keytab file
    - -To develop this functionality use this [method](http://docs.oracle.com/javase/7/docs/api/java/sql/DriverManager.html#getConnection%28java.lang.String,%20java.util.Properties%29). For example if a connection needs a schema parameter, it would have to add the property as follows: + +##### Properties - - + + - - + + + + + + + + + + + + + +
    namevalueNameValue
    {prefix}.schemaschema_namedefault.driverorg.apache.hive.jdbc.HiveDriver
    default.urljdbc:hive2://localhost:10000
    default.userhive_user
    default.passwordhive_password
    -## Examples +##### Dependencies + + + + + + + + + + + + + +
    ArtifactExcludes
    org.apache.hive:hive-jdbc:0.14.0
    org.apache.hadoop:hadoop-common:2.6.0
    -### Hive - -#### Properties - - - - - - - - - - - - - - - - - - - - - -
    NameValue
    hive.driverorg.apache.hive.jdbc.HiveDriver
    hive.urljdbc:hive2://localhost:10000
    hive.userhive_user
    hive.passwordhive_password
    - -#### Dependencies - - - - - - - - - - - - - -
    ArtifactExcludes
    org.apache.hive:hive-jdbc:0.14.0
    org.apache.hadoop:hadoop-common:2.6.0
    - -### Phoenix - - Phoenix supports `thick` and `thin` connection types: - - - Thick client is faster, but must connect directly to ZooKeeper and HBase RegionServers. - - Thin client has fewer dependencies and connects through a [Phoenix Query Server](http://phoenix.apache.org/server.html) instance. - -Use the appropriate `phoenix.driver` and `phoenix.url` for your connection type. - -#### Properties: - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    NameValueDescription
    phoenix.driverorg.apache.phoenix.jdbc.PhoenixDriver'Thick Client', connects directly to Phoenix
    phoenix.driverorg.apache.phoenix.queryserver.client.Driver'Thin Client', connects via Phoenix Query Server
    phoenix.urljdbc:phoenix:localhost:2181:/hbase-unsecure'Thick Client', connects directly to Phoenix
    phoenix.urljdbc:phoenix:thin:url=http://localhost:8765;serialization=PROTOBUF'Thin Client', connects via Phoenix Query Server
    phoenix.userphoenix_user
    phoenix.passwordphoenix_password
    -#### Dependencies: - - Include the dependency for your connection type (it should be only *one* of the following). - - - - - - - - - - - - - - - - - - - - - - -
    ArtifactExcludesDescription
    org.apache.phoenix:phoenix-core:4.4.0-HBase-1.0'Thick Client', connects directly to Phoenix
    org.apache.phoenix:phoenix-server-client:4.7.0-HBase-1.1'Thin Client' for Phoenix 4.7, connects via Phoenix Query Server
    org.apache.phoenix:phoenix-queryserver-client:4.8.0-HBase-1.2'Thin Client' for Phoenix 4.8+, connects via Phoenix Query Server
    - -### Tajo -#### Properties - - - - - - - - - - - - - -
    NameValue
    tajo.driverorg.apache.tajo.jdbc.TajoDriver
    tajo.urljdbc:tajo://localhost:26002/default
    - -#### Dependencies - - - - - - - - - -
    ArtifactExcludes
    org.apache.tajo:tajo-jdbc:0.11.0
    - -## How to use +### Apache Phoenix -### Reference in paragraph +Phoenix supports `thick` and `thin` connection types: -Start the paragraphs with the `%jdbc`, this will use the `default` prefix for connection. If you want to use other connection you should specify the prefix of it as follows `%jdbc(prefix)`: + - [Thick client](#thick-client-connection) is faster, but must connect directly to ZooKeeper and HBase RegionServers. + - [Thin client](#thin-client-connection) has fewer dependencies and connects through a [Phoenix Query Server](http://phoenix.apache.org/server.html) instance. -```sql -%jdbc -SELECT * FROM db_name; +Use the appropriate `default.driver`, `default.url`, and the dependency artifact for your connection type. -``` +#### Thick client connection -or + -```sql -%jdbc(prefix) -SELECT * FROM db_name; +##### Properties + + + + + + + + + + + + + + + + + + + + + +
    NameValue
    default.driverorg.apache.phoenix.jdbc.PhoenixDriver
    default.urljdbc:phoenix:localhost:2181:/hbase-unsecure
    default.userphoenix_user
    default.passwordphoenix_password
    -``` +##### Dependencies + + + + + + + + + +
    ArtifactExcludes
    org.apache.phoenix:phoenix-core:4.4.0-HBase-1.0
    -### Apply Zeppelin Dynamic Forms +#### Thin client connection -You can leverage [Zeppelin Dynamic Form](../manual/dynamicform.html) inside your queries. You can use both the `text input` and `select form` parametrization features + -```sql -%jdbc(prefix) -SELECT name, country, performer -FROM demo.performers -WHERE name='{{performer=Sheryl Crow|Doof|Fanfarlo|Los Paranoia}}' -``` +##### Properties + + + + + + + + + + + + + + + + + + + + + +
    NameValue
    default.driverorg.apache.phoenix.queryserver.client.Driver
    default.urljdbc:phoenix:thin:url=http://localhost:8765;serialization=PROTOBUF
    default.userphoenix_user
    default.passwordphoenix_password
    + +##### Dependencies + +Before Adding one of the below dependencies, check the Phoenix version first. + + + + + + + + + + + + + + + + + +
    ArtifactExcludesDescription
    org.apache.phoenix:phoenix-server-client:4.7.0-HBase-1.1For Phoenix 4.7
    org.apache.phoenix:phoenix-queryserver-client:4.8.0-HBase-1.2For Phoenix 4.8+
    + +### Apache Tajo + + + +##### Properties + + + + + + + + + + + + + +
    NameValue
    default.driverorg.apache.tajo.jdbc.TajoDriver
    default.urljdbc:tajo://localhost:26002/default
    + +##### Dependencies + + + + + + + + + +
    ArtifactExcludes
    org.apache.tajo:tajo-jdbc:0.11.0
    -## Bugs & Reporting -If you find a bug for this interpreter, please create a [JIRA]( https://issues.apache.org/jira/browse/ZEPPELIN-382?jql=project%20%3D%20ZEPPELIN) ticket. +## Bug reporting +If you find a bug using JDBC interpreter, please create a [JIRA](https://issues.apache.org/jira/browse/ZEPPELIN) ticket. diff --git a/jdbc/src/main/java/org/apache/zeppelin/jdbc/JDBCInterpreter.java b/jdbc/src/main/java/org/apache/zeppelin/jdbc/JDBCInterpreter.java index 5f784d7eb7b..0fbbda37455 100644 --- a/jdbc/src/main/java/org/apache/zeppelin/jdbc/JDBCInterpreter.java +++ b/jdbc/src/main/java/org/apache/zeppelin/jdbc/JDBCInterpreter.java @@ -49,7 +49,7 @@ /** * JDBC interpreter for Zeppelin. This interpreter can also be used for accessing HAWQ, - * GreenplumDB, MariaDB, MySQL, Postgres and Redshit. + * GreenplumDB, MariaDB, MySQL, Postgres and Redshift. * *