[GitHub] [incubator-doris] HappenLee commented on a change in pull request #4438: [ODBC SCAN NODE] 4/4 Add ODBC_SCAN_NODE and Odbc_Scanner in BE and add ODBC_SCAN_NODE docs

[GitBox <gi...@apache.org>]

HappenLee commented on a change in pull request #4438:
URL: https://github.com/apache/incubator-doris/pull/4438#discussion_r477109250



##########
File path: docs/zh-CN/extending-doris/odbc-of-doris.md
##########
@@ -0,0 +1,172 @@
+---
+{
+    "title": "ODBC of Doris",
+    "language": "zh-CN"
+}
+---
+
+<!-- 
+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.
+-->
+
+# ODBC External Table Of Doris
+
+ODBC External Table Of Doris 提供了Doris通过数据库访问的标准接口(ODBC)来访问外部表，外部表省去了繁琐的数据导入工作，让Doris可以具有了访问各式数据库的能力，并借助Doris本身的OLAP的能力来解决外部表的数据分析问题：
+ 
+ 1. 支持各种数据源接入Doris
+ 2. 支持Doris与各种数据源中的表联合查询，进行更加复杂的分析操作
+
+本文档主要介绍该功能的实现原理、使用方式等。
+
+## 名词解释
+
+### Doirs相关
+* FE：Frontend，Doris 的前端节点,负责元数据管理和请求接入
+* BE：Backend，Doris 的后端节点,负责查询执行和数据存储
+
+## 使用方法
+
+### Doris中创建ODBC的外表
+
+```
+CREATE EXTERNAL TABLE `baseall_oracle` (
+  `k1` decimal(9, 3) NOT NULL COMMENT "",
+  `k2` char(10) NOT NULL COMMENT "",
+  `k3` datetime NOT NULL COMMENT "",
+  `k5` varchar(20) NOT NULL COMMENT "",
+  `k6` double NOT NULL COMMENT ""
+) ENGINE=ODBC
+COMMENT "ODBC"
+PROPERTIES (
+"host" = "192.168.0.1",
+"port" = "8086",
+"user" = "test",
+"password" = "test",
+"database" = "test",
+"table" = "baseall",
+"driver" = "Oracle 19 ODBC driver",
+"type" = "oracle"
+);
+```
+
+参数说明：
+
+参数 | 说明
+---|---
+**hosts** | 外表数据库的IP地址
+**driver** | ODBC外表的Driver名，该名字需要和be/conf/odbcinst.ini中的Driver名一致。
+**type** | 外表数据库的类型，当前支持oracle与mysql
+**user** | 外表数据库的用户名
+**password** | 对应用户的密码信息
+
+
+##### ODBC Driver的安装和配置
+各大主流数据库都会提供ODBC的访问Driver，用户可以执行参照参照各数据库官方推荐的方式安装对应的ODBC Driver LiB库。
+
+
+安装完成之后，查找对应的数据库的Driver Lib库的路径，并且修改be/conf/odbcinst.ini的配置：
+```
+[MySQL Driver]
+Description     = ODBC for MySQL
+Driver          = /usr/lib64/libmyodbc8w.so
+FileUsage       = 1 
+```
+* 上述配置`[]`里的对应的是Driver名，在建立外部表时需要保持外部表的Driver名和配置文件之中的一致。
+* `Driver=`  这个要根据实际BE安装Driver的路径来填写，本质上就是一个动态库的路径，这里需要保证该动态库的前置依赖都被满足。
+
+**切记，这里要求所有的BE节点都安装上相同的Driver，并且安装路径相同，同时有相同的be/conf/odbcinst.ini的配置。**
+
+
+### 查询用法
+
+完成在Doris中建立ODBC外表后，除了无法使用Doris中的数据模型(rollup、预聚合、物化视图等)外，与普通的Doris表并无区别
+
+
+```
+select * from oracle_table where k1 > 1000 and k3 ='term' or k4 like '%doris'
+```
+
+
+
+## 类型匹配
+
+各个数据之间数据类型存在不同，这里列出了各个数据库中的类型和Doris之中数据类型匹配的情况。
+
+### MySQL类型
+
+|  MySQL  | Doris  |             替换方案              |
+| :------: | :----: | :-------------------------------: |
+|  BOOLEAN  | BOOLEAN  |                         |
+|   CHAR   |  CHAR  |            当前仅支持UTF8编码            |
+| VARCHAR | VARCHAR |       当前仅支持UTF8编码       |
+|   DATE   |  DATE  |                                   |
+|  FLOAT   |  FLOAT  |                                   |
+|   TINYINT   | TINYINT |  |
+|   SMALLINT  | SMALLINT |  |
+|   INT  | INT |  |
+|   BIGINT  | BIGINT |  |
+|   DOUBLE  | DOUBLE |  |
+|   DATE  | DATE |  |
+|   DECIMAL  | DECIMAL |  |
+
+### Oracle类型                          
+
+|  Oracle  | Doris  |             替换方案              |
+| :------: | :----: | :-------------------------------: |
+|  不支持 | BOOLEAN  |          Oracle可用number(1) 替换boolean               |
+|   CHAR   |  CHAR  |                       |
+| VARCHAR | VARCHAR |              |
+|   DATE   |  DATE  |                                   |
+|  FLOAT   |  FLOAT  |                                   |
+|  无   | TINYINT | Oracle可由NUMMBER替换 |
+|   SMALLINT  | SMALLINT |  |
+|   INT  | INT |  |
+|   无  | BIGINT |  Oracle可由NUMMBER替换 |
+|   无  | DOUBLE | Oracle可由NUMMBER替换 |
+|   DATE  | DATE |  |
+|   NUMBER  | DECIMAL |  |
+
+## Q&A
+
+1. 与原先的MySQL外表的关系
+
+    在接入ODBC外表之后，原先的访问MySQL外表的方式将被逐渐弃用。如果之前没有使用过MySQL外表，建议新接入的MySQL表直接使用ODBC的MySQL外表。
+    
+2. 除了MySQL和Oracle，是否能够支持更多的数据库
+
+    目前Doris只适配了MySQL和Oracle，关于其他的数据库的适配工作正在规划之中，原则上来说任何支持ODBC访问的数据库都能通过ODBC外表来访问。如果您有访问其他外表的需求，欢迎修改代码并贡献给Doris。
+
+3. 什么场合适合通过外表访问
+
+    通常在外表数据量较小，少于100W条时，可以通过外部表的方式访问。由于外表无法发挥Doris在存储引擎部分的能力和会带来额外的网络开销，所以建议根据实际对查询的访问时延要求来确定是否通过外部表访问还是将数据导入Doris之中。
+
+4. 通过Oracle访问出现乱码
+
+   尝试在BE启动脚本之中添加如下参数：`export NLS_LANG=AMERICAN_AMERICA.AL32UTF8`， 并重新启动所有BE

Review comment:
       不会有什么影响，但是原则上不使用oracle数据库的话是用不到这个环境变量的




----------------------------------------------------------------
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.

For queries about this service, please contact Infrastructure at:
users@infra.apache.org



---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@doris.apache.org
For additional commands, e-mail: commits-help@doris.apache.org