Sqoop-1.4.5用户手册

本文以Sqoop User Guide (v1.4.5)为主，对Sqoop-1.4.5的用户手册进行翻译，同时会结合一些实际操作中的注意事项一并写入。由于原文档很长，本文首先会以实际使用到的部分为主，逐步进行完善。

1、Introduction

Sqoop是一个用于在Hadoop和关系型数据库之间流转数据的一个工具。可以使用Sqoop将数据从关系型数据库系统(RDBMS)比如MySQL或者Oracle导入到Hadoop分布式文件系统(HDFS)上，然后数据在Hadoop MapReduce上转换，以及将数据导出到RDBMS中。

Sqoop自动实现了上面提到的很多过程，Sqoop使用MapReduce来导入和导出数据，这样既可以提供并行化操作又可以提高容错能力。

这篇文档介绍了如何使用Sqoop在database和Hadoop之间流转数据，以及介绍了Sqoop命令行工具的使用方法。

2、Supported Releases

这篇文档适用于Sqoop v1.4.5。

3、Sqoop Releases

Sqoop是Apache软件基金会的一个开源项目。可以访问http://Sqoop.apache.org获取

- 最新版本的Sqoop以及其源码

- bug的追踪

- 包含Sqoop文档的Wiki

4、Prerequisites

如果想要使用Sqoop，需要已经准备好以下条件：

- 了解一些基本的计算机知识和术语

- 熟悉比如bash等的命令行操作

- 了解关系型数据管理系统(RDBMS)

- 熟悉一些Hadoop的相关操作



在使用Sqoop之前，Hadoop必须安装并配置好，目前Sqoop支持hadoop的4个主要版本-0.20,0.23,1.0以及2.0。

这篇文档基于Linux或类Linux环境，如果使用的是Windows系统的话，最好使用cygwin来操作以下的内容。如果使用Mac OS X，可能会遇到一些报错。Sqoop最好的运行环境还是Linux。

5、Basic Usage

使用Sqoop可以从关系型数据库中导入数据到HDFS上，在这个过程中import操作的输入是一个数据库表，Sqoop会逐行读取记录到HDFS中。import操作的输出是包含读入表的一系列HDFS文件，import操作是并行的也就是说可以启动多个map同时读取数据到HDFS，每一个map对应一个输出文件。这些文件可以是TextFile类型，也可以是Avro类型或者SequenceFile类型。

在import过程中还会生成一个Java类，这个类与输入的表对应，类名即表名，类变量即表字段。import过程会使用到这个Java类。

在import操作之后，就可以使用这些数据来实验export过程了。export是将数据从HDFS或者hive导出到关系型数据库中。export过程并行的读取HDFS上的文件，将每一条内容转化成一条记录，然后作为一个新行insert到关系型数据库表中。

除了import和export，Sqoop还包含一些其他的操作。比如可以使用sqoop-list-databases工具查询数据库结构，可以使用sqoop-list-tables工具查询表信息。还可以使用sqoop-eval工具执行SQL查询。

6、Sqoop Tools

Sqoop提供了一系列的操作工具，使用Sqoop需要指定你想要使用的具体工具，以及提供对应的一些参数，使用方式如下。

$ sqoop tool-name [tool-arguments]

可以使用sqoop help命令查看帮助信息，从

$ sqoop help

usage: sqoop COMMAND [ARGS]

Available commands:

  codegen            生成Java代码

  create-hive-table  根据表结构生成hive表

  eval               执行SQL语句并返回结果

  export             导出HDFS文件到数据库表

  help               帮助

  import             从数据库导入数据到HDFS

  import-all-tables  导入数据库所有表到HDFS

  list-databases     列举所有的database

  list-tables        列举数据库中的所有表

  version            查看版本信息

See 'sqoop help COMMAND' for information on a specific command.

可以看到，sqoop提供的操作工具有10个。具体工具的使用帮助可以 sqoop help (tool-name) 或者 sqoop tool-name --help 进行查看。

6.1. Using Command Aliases

在sqoop的bin目录下，提供了比如sqoop-merge之类的课执行脚本，其实这个脚本中封装的命令是sqoop merge。类似的命令还有sqoop-import, sqoop-export等。

6.2. Controlling the Hadoop Installation

sqoop命令最终执行了hadoop命令脚本。如果在服务器上安装了多个hadoop，可以使用HADOOPCOMMONHOME和HADOOP_MAPRED_HOME环境变量来指定使用哪个hadoop，比如

$ HADOOP_COMMON_HOME=/path/to/some/hadoop \

  HADOOP_MAPRED_HOME=/path/to/some/hadoop-mapreduce \

  sqoop import --arguments...

或者

$ export HADOOP_COMMON_HOME=/some/path/to/hadoop

$ export HADOOP_MAPRED_HOME=/some/path/to/hadoop-mapreduce

$ sqoop import --arguments...

6.3. Using Generic and Specific Arguments

Sqoop的每一个工具都需要接收一些参数，这些参数有hadoop相关参数，也有用户指定的sqoop相关参数。

比如，sqoop import工具的使用

$ sqoop help import

usage: sqoop import [GENERIC-ARGS] [TOOL-ARGS]

Common arguments:

   --connect <jdbc-uri>     指定JDBC连接串

   --connect-manager <jdbc-uri>     指定连接类

   --driver <class-name>    指定使用的JDFC驱动类

   --hadoop-mapred-home <dir>+      可以覆盖$HADOOP_MAPRED_HOME参数

   --help                   帮助

   --password-file          指定密码文件

   -P                       从命令行读取密码

   --password <password>    指定密码

   --username <username>    指定用户名

   --verbose                显示import过程更多信息

   --hadoop-home <dir>+     Deprecated. 可以覆盖$HADOOP_HOME参数

[...]

hadoop命令行参数:

(must preceed any tool-specific arguments)

Generic options supported are

-conf <configuration file>     指定配置文件

-D <property=value>            指定特定参数的值

-fs <local|namenode:port>      指定namenode

-jt <local|jobtracker:port>    字段jobtracker

-files <comma separated list of files>    逗号分隔的文件列表，这些文件会上传到hdfs

-libjars <comma separated list of jars>    逗号分隔的jar包，这些jar包会上传到hdfs

-archives <comma separated list of archives>    

The general command line syntax is

bin/hadoop command [genericOptions] [commandOptions]

hadoop相关的参数只能写在sqoop工具之后，但是在任何sqoop参数(比如 –connect)之前。

-conf, -D, -fs以及-jt参数用于配置Hadoop相关参数，比如 -D mapred.job.name=<job_name> 可以指定Sqoop提交的MR任务名称，如果不指定的话，默认名称为表名。

-files, -libjars, -archives参数基本不会在Sqoop中用到。

6.4. Using Options Files to Pass Arguments

对于不经常发生变化的参数，可以写在一个文件中，这个文件中每行写一个参数，如果某个参数特别长导致一行写不下的话，在结尾写一个反斜杠”\”，然后可以换行继续写。在这个配置文件中可以类似于shell脚本那样写注释，文件中空行不会起作用，引号外的空格也会忽略。配置参数的书写顺序是：首先写hadoop相关参数(即以“-”开头的参数)，然后写sqoop相关参数(即“–”开头的那些参数)，最后写需要传递到子程序中的参数。

使用配置文件的话，用参数 --options-file 来指定，如果有个配置文件 /users/homer/work/import.txt中的内容如下

import

--connect

jdbc:mysql://localhost/db

--username

foo

那么，下面两个命令的作用相同

$ sqoop import --connect jdbc:mysql://localhost/db --username foo --table TEST

$ sqoop --options-file /users/homer/work/import.txt --table TEST

import.txt文件中包含注释和空行，空格的形式如下：

#

# Options file for Sqoop import

#

# Specifies the tool being invoked

import

# Connect parameter and value

--connect

jdbc:mysql://localhost/db

# Username parameter and value

--username

foo

#

# Remaining options should be specified in the command line.

#

6.5. Using Tools

文档接下来部分会详细描述每个Sqoop工具的作用，以及使用方法

7. sqoop-import

7.1. Purpose

import工具可以用于从RDBMS中导入一张表到HDFS。表中的每一条记录对应生成HDFS文件中的每一行。这些记录可以以text files或者Avro或者SequenceFiles格式进行存储。

7.2. Syntax

使用方法如下

$ sqoop import (generic-args) (import-args)

$ sqoop-import (generic-args) (import-args)

参数列表1-import基本参数

参数	描述
–connect < jdbc-uri >	JDBC连接串
–connection-manager < class-name >	连接管理类
–driver < class-name >	手动指定JDBC驱动类
–hadoop-mapred-home < dir >	可以覆盖$HADOOP_MAPRED_HOME
–help	使用帮助
–password-file	指定包含密码的文件
-P	执行import时会暂停，等待用户手动输入密码
–password < password >	直接将密码写在命令行中
–username < username >	指定用户名
–verbose	显示Sqoop任务更多执行信息
–connection-param-file < filename >	可选的参数，用于提供连接参数
–relaxed-isolation	设置每个mapmer的连接事务隔离

7.2.1. Connecting to a Database Server

这里介绍Sqoop如何连接到一个数据库，主要使用的是–connect参数，比如

$ sqoop import --connect jdbc:mysql://database.example.com/employees

这个连接串会连接database.example.com服务器上的employees数据库。这个连接串会被各个map节点用于连接数据库，所以如果写成localhost的话就会报错， –connect参数后面不能写localhost来表示服务器地址

指定数据库连接后，接下来需要提供数据库访问的用户名和密码。上面提到了密码有三种设置方式，其中–password是最不安全的。推荐将密码写入一个文件，然后将该文件的权限设置成400，通过–password-file指定到该文件，这个文件可以位于本地也可位于HDFS上。

$ sqoop import --connect jdbc:mysql://database.example.com/employees \

    --username venkatesh --password-file ${user.home}/.password

不推荐使用–password参数传递密码，因为使用ps命令就可以直接查看到该参数。

Sqoop中内置了MySQL的驱动，如果需要指定其他的基于JDBC的数据库连接，需要将对应jar包放至lib目录下，然后指定驱动类，比如，

$ sqoop import --driver com.microsoft.jdbc.sqlserver.SQLServerDriver \

    --connect <connect-string> ...

表2-验证相关的参数

参数	描述
–valid	启动数据验证功能，只对单表copy有效
–validator < class-name >	指定验证类
–validation-threshold < class-name >	指定使用的阈值验证类
–validation-failurehandler < class-name >	指定验证失败的处理类

表3-import控制参数

参数	描述
–append	导入的数据追加到数据文件中
–as-avrodatafile	导入数据格式为avro
–as-sequencefile	导入数据格式为sqeuqncefile
–as-textfile	导入数据格式为textfile
–boundary-query < statement >	代替min(split-by),max(split-by)值指定的边界，下面会有详细介绍
–columns < col,col,col… >	指定导入字段
–delete-target-dir	如果导入的target路径存在，则删除
–direct	使用direct模式
–fetch-size < n >	从数据库一次性读入的记录数
-inline-lob-limit < n >	设定大对象数据类型的最大值
-m, –num-mappers < n >	指定并行导入数据的map个数，默认为4个
-e, –query < statement >	导入查询语句得到的数据
–split-by < column-name >	一般与-m参数一起使用，指定分割split的字段
–table < table-name >	指定database中的表名
–target-dir < dir >	指定目标HDFS路径
–warehouse-dir < dir >	指定表目标路径所在路径
–where < where clause >	即sql语句中的where条件
-z, –compress	打开压缩功能
–compression-codec < c >	使用Hadoop的压缩，默认为gzip压缩
–null-string < null-string >	源表中为null的记录导入为string类型时显示为null-string，默认显示为”null”
–null-non-string < null-string >	源表中为null的记录导入为非string类型时显示为null-string，默认显示为”null”

7.2.2. Selecting the Data to Import

使用–table参数可以指定导入的表或者视图，默认情况下，该表或视图的所有字段都会被按顺序导入进来。但是如果只需要导入该表的部分字段，或者调整导入字段的顺序时，可以使用–columns参数。例如 --columns "name, employee_id, jobtitle" 。

也可以使用–where参数符合筛选条件的记录进行导入，例如 --where "id > 400" ,则源表中只有id大于400的记录才会被导入进来。

默认情况下，Sqoop会根据指定的–split-by字段的min，max值对记录进行分片并导入。但是在有些情况下，如果不需要导入从min(split-by)到max(split-by)的记录时，可以使用 --boundary-query <statement> 参数传入一个返回两个数字类型的sql语句来指定导入范围，如果传入非数字类型的字段，比如varchar型，会报Invalid value for getLong()之类的错误信息。



7.2.3. Free-form Query Imports

除了像上面那样指定–table，–columns, –where等参数的导入方法之外，Sqoop还支持传入一个SQL语句，并把该SQL语句的结果导入到HDFS中。这里需要使用–query或者-e参数。 但是使用–query参数时，同时要指定–target-dir参数 ，如果需要并行的导入数据，即多个map并行的用相同的query语句查询不同的数据并最终汇总到一起。那么 需要在query语句中增加一个$CONDITIONS字符串，并且指定–split-by字段 。比如如下两个：

$ sqoop import \

  --query 'SELECT a.*, b.* FROM a JOIN b on (a.id == b.id) WHERE $CONDITIONS' \

  --split-by a.id --target-dir /user/foo/joinresults

$ sqoop import \

  --query 'SELECT a.*, b.* FROM a JOIN b on (a.id == b.id) WHERE $CONDITIONS' \

  -m 1 --target-dir /user/foo/joinresults

第二个语句是将map个数设置成1。这里需要注意一点上面两个示例中使用的是单引号，如果非要使用双引号，那么应该写 “$CONDITIONS ，即在前面加一个反斜杠。

在当前Sqoop版本中，也不能传入特别复杂的sql语句，比如在where条件中不能有or操作，并且对有子查询的语句，可能会出现一些未知的错误。



7.2.4. Controlling Parallelism

Sqoop支持并发的从多种数据源中导入数据。可以使用-m或者–num-mappers参数指定map的个数，每一个map处理数据源中的一部分数据，默认情况下Sqoop的并发为4，对某些数据库来说，将并发调整到8或16会有显著的性能提升。

但是并发调整的太高也不好，比如如果map个数太多，超出整个集群的最大并行数时，其他的map任务就需要等前面的map任务执行完毕才能继续执行，这样有可能反而增加了导入总时间。同时，如果并发太高，会增加数据库的访问压力，所以，应该根据实际情况调整一个最优并发参数。

当并发的导入数据时，Sqoop需要有一个明确的划分数据集的指标，告诉Sqoop如何为每个map分配处理的数据，使得既无遗漏也无重复。默认情况下如果指定表有主键，Sqoop会根据主键的max, min值除以map个数来划分数据集。比如一张表有1000条记录，主键为id，并发为4，那么每个map上执行是SQL语句是 SELECT * FROM sometable WHERE id >= lo AND id < hi ，对每个map来说，(lo, hi)分别是(0, 250), (250, 500), (500, 750), 以及(750, 1001)。

但是这样会有一个数据倾斜的问题，比如1000条记录大部分分布在0~250区间内，那么会有一个map处理大量数据，而其他map处理的数据特别少。这时候就需要使用 --split-by 参数手动指定一个分割字段了。目前Sqoop不支持联合主键，那么如果导入表没有主键，或者有联合主键时，就需要手动指定分割字段。



7.2.5. Controlling Distributed Cache

每一个Sqoop任务执行时都会上传一次ib目录下的jar包。但是如果使用Oozie来启动Sqoop任务时，就没有必要这样做了，因为Oozie会使用它自己的Sqoop共享lib文件。使用 --skip-dist-cache 参数来指定Oozie调度起的Sqoop任务跳过上传jar包这一过程。



7.2.6. Controlling the Import Process

默认情况下，Imporg过程会使用到JDBC提供的稳定服务去访问和连接数据库。但是有些数据库提供了一些其他的数据库访问工具来为import过程提供更高效的服务。比如，MySQL提供了一个mysqldump工具可以使得从MySQL导出数据到其他系统更加的快速。通过指定 --direct 参数就可以指定Sqoop使用mysqldump从数据库导入数据。这个方式会比JDBC提供更加高效。

对每一种关系型数据库如何使用direct模式import数据，需要如何安装配置，如何配置，以及有哪些局限性，都在第24节，24. Notes for specific connectors中有进一步的描述。

默认情况下，Sqoop会将一个表名为foo的表，导入到HDFS上一个名称为foo的路径下。比如，如果使用用户someuser来执行Sqoop import，那么会在将foo表导入到HDFS上的/user/someuser/foo/(files)路径下。当然了，可以使用 --warehouse-dir 参数来指定导入文件的父路径。

7.2.7. Controlling transaction isolation

7.2.8. Controlling type mapping

7.2.9. Incremental Imports

7.2.10. File Formats

7.2.11. Large Objects

7.2.12. Importing Data Into Hive

7.2.13. Importing Data Into HBase

7.2.14. Importing Data Into Accumulo

7.2.15. Additional Import Configuration Properties

7.3. Example Invocations

8. sqoop-import-all-tables

8.1. Purpose

8.2. Syntax

8.3. Example Invocations

9. sqoop-export

9.1. Purpose

Sqoop的 export 工具可以从HDFS同步一系列文件数据到RDBMS中。使用这个工具的前提是导出目标表在数据库必须存在。导出文件根据用户指定的分隔符转化成一系列的输出记录。

默认的导出操作会将这些记录转化成一系列的 INSERT 语句，根据这些语句将记录插入到关系型数据库中。而在 update 模式下，Sqoop会生成一系列的 UPDATE 语句，将数据库中已经存在的记录进行更新。在 call 模式下，Sqoop会为每一条记录调用一个存储过程来处理。

9.2. Syntax

Sqoop的 export 工具使用语法如下：

$ sqoop export (generic-args) (export-args)

$ sqoop-export (generic-args) (export-args)

前面的 generic-args 是Hadoop相关参数，如果有这些参数的话，必须写在 export 参数之前， export 参数之间的顺序可以随意调整。

表19-基本参数

参数	描述
–connect < jdbc-uri >	JDBC连接串
–connection-manager < class-name >	连接管理类
–driver < class-name >	手动指定JDBC驱动类
–hadoop-mapred-home < dir >	可以覆盖$HADOOP_MAPRED_HOME
–help	使用帮助
–password-file	指定包含密码的文件
-P	执行import时会暂停，等待用户手动输入密码
–password < password >	直接将密码写在命令行中
–username < username >	指定用户名
–verbose	显示Sqoop任务更多执行信息
–connection-param-file < filename >	可选的参数，用于提供连接参数
–relaxed-isolation	设置每个mapmer的连接事务隔离

表20-验证相关的参数

参数	描述
–valid	启动数据验证功能，只对单表copy有效
–validator < class-name >	指定验证类
–validation-threshold < class-name >	指定使用的阈值验证类
–validation-failurehandler < class-name >	指定验证失败的处理类

表21-export控制参数

参数	描述
–columns < col,col,col… >	指定导出字段
–direct	使用direct模式
–export-dir < dir >	导出HDFS文件路径
-m, –num-mappers < n >	指定并行导出数据的map个数，默认为4个
–table < table-name >	指定database中的表名
–call < stored-proc-name >	调用的存储过程名称
–update-key < col-name >	UPDATE模式下的更新字段，多个字段可以用逗号分隔
–update-mode < mode >	当某记录在数据库中找不到对应记录时的操作。默认为 updateonly ，可以设置成 allowinsert ，这个模式遇到新增记录会插入导出表中
–input-null-string < null-string >	string类型字段表示null值的字符
–input-null-non-string < null-string >	非string类型字段表示null值的字符
–staging-table < staging-table-name >	在最终导出到目标表之前临时存储这些记录的表
–clear-staging-table	表示可以清除上面的staging-table表中的记录
–batch	对底层数据库的插入操作使用batch模式

--export-dir 参数，以及 --table 或者 --call 是必须指定的参数。因为这三个参数分别用来指定导出数据集，以及数据导出后的去处，既可以是导出到某张表，也可以是对每一条导出记录调用存储过程。

默认情况下，会导出所有字段。可以使用 --columns 参数指定部分字段进行导出。多个字段使用逗号分隔，比如 --columns "col1,col2,col3" 。需要注意的是，对那些没有指定的导出字段，在数据库中要么有默认值，要么运行为 NULL 。否则导出过程在插入这些字段的值时会报错。

在导出时可以指定并行的Map个数，导出过程的速度由并发数来决定。默认情况下， export 过程会使用4个Map并行。具体的并发数由实际的数据量大小，数据库的性能等共同确定。由参数 --num-mappers 或者 -m 来设置。

有些数据库提供一中 direct 模式，比如MySQL。使用 --direct 参数可以指定特定的数据库连接方式。具体可以参考24. Notes for specific connectors。

对于数据库中的 NULL 值定义，可以由参数 --input-null-string 和 --input-null-none-string 两个参数来指定。如果不指定 --input-null-string 字段的话，那么导出数据中的 null 字符串会当做 NULL 值插入数据库中。如果不指定 --input-null-non-string 的话，那么导出数据中的 null 字符串以及空字符串都会当做 NULL 值插入数据库中。这里需要注意对非string类型字段，会将空字符串直接导出为 NULL 值。

由于Sqoop将导出过程切分成了多个transaction，那么就会有可能某个导出job失败而导致只有部分数据提交到了导出数据库中。当失败job重试时，就有可能会出现数据重复，或者导出数据冲突等情况发生。这时可以指定一个 --staging-table 参数来避免这种情况的发生。导出的数据首先会缓存在该表中，最后等job执行成功后会将该表中的数据移动到最终目标表中。

使用 --staging-table 需要在job执行前提前创建该表，这张表在结构上需要与目标表保持一致。并且这张表在任务执行前需要为空，或者指定 --clear-staging-table 参数，如果在导出前该表中有数据，那么这个参数会提前将该表清空。

--staging-table 参数不能在 --direct 模式下工作。并且如果指定了 --update-key 或者指定的存储过程会涉及到数据的插入时，也不能使用 --staging-table 参数。

9.3. Inserts vs. Updates

默认情况下， export 操作会将记录插入到导出表中。每一条导出记录都会转化成一条 INSERT 语句。如果导出表有字段约束(比如主键约束)时，需要注意避免导出记录违反这些约束条件的限制。这种模式只适合将数据导出到一张新的，或者空表中。

如果指定 --update-key 参数，Sqoop会将每一条导出记录转化成一条 UPDATE 语句，这样可以更新已存在的记录。比如，看一下下面的表定义语句：

CREATE TABLE foo(

    id INT NOT NULL PRIMARY KEY,

    msg VARCHAR(32),

    bar INT);

如果有一个HDFS文件内容如下：

0,this is a test,42

1,some more data,100

...

运行 sqoop-export --table foo --update-key id --export-dir /path/to/data --connect … ，会执行一个 export 任务，这个任务执行的SQL语句如下，

UPDATE foo SET msg='this is a test', bar=42 WHERE id=0;

UPDATE foo SET msg='some more data', bar=100 WHERE id=1;

...

如果一条 UPDATE 语句匹配不到对应的记录或者匹配到多条记录时，不会发生任何的错误。导出过程会正常继续执行后面的SQL语句。不过如果在使用 --update-key 参数的同时指定参数 --update-mode 为 allowinsert 的话， UPDATE 语句匹配不到的记录就会以 INSERT 的形式插入到目标表中。

--update-key 参数也可以设置多个字段，多个字段之间用逗号隔开。

表22-输入记录格式化参数

参数	描述
–input-enclosed-by < char>	指定必须的字段外包字符
–input-escaped-by < char >	指定输入字段忽略字符
–input-fields-terminated-by < char >	输入文件字段分隔符
–input-lines-terminated-by < char >	输入文件行分隔符
–input-optionally-enclosed-by < char >	设置可选的字段外包字符

表23-输出记录格式化参数

参数	描述
–enclosed-by < char>	指定必须的字段外包字符
–escaped-by < char >	指定字段忽略字符
–fields-terminated-by < char >	字段分隔符
–lines-terminated-by < char >	行分隔符
–mysql-delimiters	使用MySQL默认分隔符，字段用 , 分隔，行用 \n 分隔，可选外包字符为 ' ，忽略的字符为 \
–optionally-enclosed-by < char >	设置可选的字段外包字符

Sqoop会根据上面设置的各种分隔符自动生成代码来解析输入文件。在非默认的情况下，需要设置这些参数来帮助Sqoop正确的解析输入文件中的记录。如果分隔符指定错误的话，可能会出现对一行记录解析不到足够的字段数，从而导致报出 ParseExceptions 的错误。

表24-代码生成参数

参数	描述
–bindir < dir >	指定编译后的class文件路径
–class-name < name >	指定生成代码的类名，这个会覆盖 --package-name 参数的设置。当与 --jar-file 配合使用时，指定使用的类名
–jar-file < file >	关闭代码生成，使用指定的jar文件
–outdir < dir >	设置生成java文件路径
–package-name < name >	设置生成代码的package名
–map-column-java < m >	设置生成代码中指定字段的Java类型

如果需要导出的数据在前面已经由 import 导入过，那么可以使用 import 时生成的代码来进行 export 的过程。这时可以通过 --jar-file 以及 --class-name 来指定使用的 jar 文件以及需要使用的类名。

使用已有的代码，会与 --update-key 参数相冲突。 UPDATE 模式需要生成新的代码来完成这一过程，如果使用 UPDATE 模式，就不能使用 --jar-file 参数，并且必须指定所有没有默认值的分隔符。

9.4. Exports and Transactions

数据导出过程由多个writers并行的执行，每一个writer使用一个独立的数据库连接，这些writer的transaction也是各自独立的。Sqoop使用多个 INSERT 语句来插入记录，每一个stattement最多能插入100条记录。每个writer在100个statements时，执行一次提交操作，所以，每一次提交可以插入10000条记录。因此导出操作不是原子性的，在导出过程结束前可以看到部分导出数据。

9.5. Failed Exports

数据导出过程可能会由于以下原因导致导出失败：

• Hadoop集群失去与数据库的连接(可能由于硬件原因，或者网络等原因造成)
• 在 INSERT 模式下向有约束的表插入数据
• HDFS文件中记录本身有异常，数据无法正常解析
• 分隔符指定错误，导致解析发生错误

• 硬件原因，比如磁盘空间不足或内存不足等

  如果一个 export 的数据导出的map任务发生失败，将会导致整个 export 任务失败。并且失败的 export 过程的结果是未知的。每个map任务在独立的transaction中并发的导出数据，并且，每一个map任务定期的提交当前transaction中的记录。如果一个map任务失败，当前transaction将会回滚。而之前正常提交的transaction中的记录已经导出到外部表中了。

9.6. Example Invocations

下面的命令将数据导出到一个表 bar 中：

$ sqoop export --connect jdbc:mysql://db.example.com/foo --table bar  \

    --export-dir /results/bar_data

上面命令从 /results/bar_data 文件中读取记录，通过指定的jdbc连接串连接到数据库，将该数据导出到mysql中的表 bar 中。在任务执行前 bar 表必须已经存在。Sqoop会根据上面的命令生成一系列的 INSERT INTO 操作。

如果想要导出到指定字段，可以使用 --columns "col1,col2,col3" 。没有指定在 --columns 参数中的字段，要么在定义时有默认值，要么允许为 NULL ，否则导出会发生错误。

另外一个加建议条件的导出过程：

$ sqoop export --connect jdbc:mysql://db.example.com/foo --table bar  \

    --export-dir /results/bar_data --validate

再看一个不导出到表而是调用存储过程的示例：

$ sqoop export --connect jdbc:mysql://db.example.com/foo --call barproc \

    --export-dir /results/bar_data

10. validation

10.1. Purpose

校验操作会对不管是 import 过程还是 export 过程，都进行源数据和目标数据的比较。

10.2. Introduction

有关校验的过程，有以下三个基本概念：

• 校验阈值：确定源数据和目标数据之间允许出现的记录不一致情况的程度。默认为 AbsoluteValidationThreshold ，表示需要源数据和目标数据记录数保持一致。
• 校验失败的处理方法：当出现校验失败时如何进行处理，默认情况下使用的是 LogOnFailureHandler ，会记录一个提示信息到日志文件中。
• 校验器：校验的主要逻辑，默认使用的是 RowCountValidator ，用于比较源数据和目标数据的记录数。

10.3. Syntax

语法格式：

$ sqoop import (generic-args) (import-args)

$ sqoop export (generic-args) (export-args)

从前面的参数表中可以看到校验参数是 import 或者 export 参数的一部分。

10.4. Configuration

校验框架是灵活可拔插的。它提供了一些默认的实现方法，用户也可以基于接口的定义来实现自定义的类和参数。

• Validator，默认实现类是 org.apache.sqoop.validation.RowCountValidator
• Validation Threshold，默认实现类是 org.apache.sqoop.validation.AbsoluteValidationThreshold
• Validation Failure Handler，默认实现类是 org.apache.sqoop.validation.AbortOnFailureHandler

10.5. Limitations

目前校验过程只能校验单表导入到HDFS这一种场景，下面列举了校验过程的一些不足之处：

• 多表模式不支持
• 自定义sql查询语句不支持
• 数据导入到Hive, Hbase, Accumulo不支持
• 带 --where 参数的不支持
• 增量导入的不支持

10.6. Example Invocations

从 corp 库导入一张 EMPLOYEES 表，校验记录数是否一致：

$ sqoop import --connect jdbc:mysql://db.foo.com/corp  \

    --table EMPLOYEES --validate

导出数据到表 bar 中，并启动校验功能：

$ sqoop export --connect jdbc:mysql://db.example.com/foo --table bar  \

    --export-dir /results/bar_data --validate

不使用默认校验参数的示例：

$ sqoop import --connect jdbc:mysql://db.foo.com/corp --table EMPLOYEES \

    --validate --validator org.apache.sqoop.validation.RowCountValidator \

    --validation-threshold \

          org.apache.sqoop.validation.AbsoluteValidationThreshold \

    --validation-failurehandler \

          org.apache.sqoop.validation.AbortOnFailureHandler

11. Saved Jobs

12. sqoop-job

12.1. Purpose

12.2. Syntax

12.3. Saved jobs and passwords

12.4. Saved jobs and incremental imports

13. sqoop-metastore

13.1. Purpose

13.2. Syntax

14. sqoop-merge

14.1. Purpose

在Sqoop中提供了一个merge工具，用于将两个dataset中的记录进行合并操作。这个经常用于增量同步中，比如有一个全量的dataset和一个增量的dataset，执行merge时希望如果增量和全量中都有的话优先取增量dataset中的记录，如果只有增量中有，则取增量中的记录，如果只有全量中有，则取全量中的记录。

14.2. Syntax

在 $SQOOP_HOME/bin 路径下有一个 sqoop-merge 命令，其中的主要逻辑是执行 sqoop merge 操作。所以， merge 有两种使用方法

$ sqoop merge (generic-args) (merge-args)

$ sqoop-merge (generic-args) (merge-args)

参数介绍

参数	描述
–class-name	表对应的class文件
–jar-file	表对应的jar包
–merge-key	进行merge的字段，根据该字段判断新旧记录，字段名需要大写
–new-data	增量数据对应的HDFS文件路径
–onto	全量数据对应的HDFS文件路径
–target-dir	合并后的HDFS文件路径

注意这里的三个路径都是HDFS上的路径，并且要求 --target-dir 对应的路径不存在，存在的话就会报错。可以理解成，将 --new-data 中的数据合并到 --onto 文件中。当Sqoop合并两个dataset时，会假设每条记录有一个唯一主键，该主键由参数 --merge-key 指定。比如下面两个dataset

dataset-onto:

id	comment
1	xxx
3	zzz

dataset-new-data:

id	comment
1	aaa
2	yyy

如果指定 --merge-key id ，那么就会根据id去对两个dataset进行join，最终结果

dataset-target-dir

id	comment
1	aaa
2	yyy
3	zzz

从 --jar-file 参数对应的代码中可以看到，指定表的所有字段在代码中都转换成了大写，所以在指定merge-key时，记得 大写字段名，否则会报错 。在执行merge操作时，必须指定 --jar-file 参数和 --class-name 参数。jar文件可以在对这个表的sqoop import过程中生成，也可以用后面的codegen工具生成。

merge tool一般用于增量import之后。假设有两个增量import执行，前面一个任务的HDFS路径名为older，后面那个任务的HDFS路径为newer，那么这两个文件的merge操作可以使用以下命令

$ sqoop merge --new-data newer --onto older --target-dir merged \

    --jar-file datatypes.jar --class-name Foo --merge-key id

这个命令会运行一个MapReduce任务，根据id字段order和newner的每一行记录进行join。newner中的记录优先于older中的记录使用。

merge tool可以用于SequenceFile, Avro, 以及text类型的import操作。但是需要注意的是older和newner的文件类型必须保持一致。

15. sqoop-codegen

15.1. Purpose

15.2. Syntax

15.3. Example Invocations

16. sqoop-create-hive-table

16.1. Purpose

16.2. Syntax

16.3. Example Invocations

17. sqoop-eval

17.1. Purpose

17.2. Syntax

17.3. Example Invocations

18. sqoop-list-databases

18.1. Purpose

18.2. Syntax

18.3. Example Invocations

19. sqoop-list-tables

19.1. Purpose

19.2. Syntax

19.3. Example Invocations

20. sqoop-help

20.1. Purpose

20.2. Syntax

20.3. Example Invocations

21. sqoop-version

21.1. Purpose

21.2. Syntax

21.3. Example Invocations

22. Sqoop-HCatalog Integration

22.1. HCatalog Background

22.2. Exposing HCatalog Tables to Sqoop

22.2.1. New Command Line Options

22.2.2. Supported Sqoop Hive Options

22.2.3. Direct Mode support

22.2.4. Unsupported Sqoop Options

22.2.4.1. Unsupported Sqoop Hive Import Options

22.2.4.2. Unsupported Sqoop Export and Import Options

22.2.5. Ignored Sqoop Options

22.3. Automatic Table Creation

22.4. Delimited Text Formats and Field and Line Delimiter Characters

22.5. HCatalog Table Requirements

22.6. Support for Partitioning

22.7. Schema Mapping

22.8. Support for HCatalog Data Types

22.9. Providing Hive and HCatalog Libraries for the Sqoop Job

22.10. Examples

22.11. Import

22.12. Export

23. Compatibility Notes

23.1. Supported Databases

23.2. MySQL

23.2.1. zeroDateTimeBehavior

23.2.2. UNSIGNED columns

23.2.3. BLOB and CLOB columns

23.2.4. Importing views in direct mode

23.3. PostgreSQL

23.3.1. Importing views in direct mode

23.4. Oracle

23.4.1. Dates and Times

23.5. Schema Definition in Hive

24. Notes for specific connectors

24.1. MySQL JDBC Connector

24.1.1. Upsert functionality

24.2. MySQL Direct Connector

24.2.1. Requirements

24.2.2. Limitations

24.2.3. Direct-mode Transactions

24.3. Microsoft SQL Connector

24.3.1. Extra arguments

24.3.2. Schema support

24.3.3. Table hints

24.4. PostgreSQL Connector

24.4.1. Extra arguments

24.4.2. Schema support

24.5. PostgreSQL Direct Connector

24.5.1. Requirements

24.5.2. Limitations

24.6. pg_bulkload connector

24.6.1. Purpose

24.6.2. Requirements

24.6.3. Syntax

24.6.4. Data Staging

24.7. Netezza Connector

24.7.1. Extra arguments

24.7.2. Direct Mode

24.7.3. Null string handling

24.8. Data Connector for Oracle and Hadoop

24.8.1. About

24.8.1.1. Jobs

24.8.1.2. How The Standard Oracle Manager Works for Imports

24.8.1.3. How The Data Connector for Oracle and Hadoop Works for Imports

24.8.1.4. Data Connector for Oracle and Hadoop Exports

24.8.2. Requirements

24.8.2.1. Ensure The Oracle Database JDBC Driver Is Setup Correctly

24.8.2.2. Oracle Roles and Privileges

24.8.2.3. Additional Oracle Roles And Privileges Required for Export

24.8.2.4. Supported Data Types

24.8.3. Execute Sqoop With Data Connector for Oracle and Hadoop

24.8.3.1. Connect to Oracle / Oracle RAC

24.8.3.2. Connect to An Oracle Database Instance

24.8.3.3. Connect to An Oracle RAC

24.8.3.4. Login to The Oracle Instance

24.8.3.5. Kill Data Connector for Oracle and Hadoop Jobs

24.8.4. Import Data from Oracle

24.8.4.1. Match Hadoop Files to Oracle Table Partitions

24.8.4.2. Specify The Partitions To Import

24.8.4.3. Consistent Read: All Mappers Read From The Same Point In Time

24.8.5. Export Data into Oracle

24.8.5.1. Insert-Export

24.8.5.2. Update-Export

24.8.5.3. Merge-Export

24.8.5.4. Create Oracle Tables

24.8.5.5. NOLOGGING

24.8.5.6. Partitioning

24.8.5.7. Match Rows Via Multiple Columns

24.8.5.8. Storage Clauses

24.8.6. Manage Date And Timestamp Data Types

24.8.6.1. Import Date And Timestamp Data Types from Oracle

24.8.6.2. The Data Connector for Oracle and Hadoop Does Not Apply A Time Zone to DATE / TIMESTAMP Data Types

24.8.6.3. The Data Connector for Oracle and Hadoop Retains Time Zone Information in TIMEZONE Data Types

24.8.6.4. Data Connector for Oracle and Hadoop Explicitly States Time Zone for LOCAL TIMEZONE Data Types

24.8.6.5. java.sql.Timestamp

24.8.6.6. Export Date And Timestamp Data Types into Oracle

24.8.7. Configure The Data Connector for Oracle and Hadoop

24.8.7.1. oraoop-site-template.xml

24.8.7.2. oraoop.oracle.session.initialization.statements

24.8.7.3. oraoop.table.import.where.clause.location

24.8.7.4. oracle.row.fetch.size

24.8.7.5. oraoop.import.hint

24.8.7.6. oraoop.oracle.append.values.hint.usage

24.8.7.7. mapred.map.tasks.speculative.execution

24.8.7.8. oraoop.block.allocation

24.8.7.9. oraoop.import.omit.lobs.and.long

24.8.7.10. oraoop.locations

24.8.7.11. sqoop.connection.factories

24.8.7.12. Expressions in oraoop-site.xml

24.8.8. Troubleshooting The Data Connector for Oracle and Hadoop

24.8.8.1. Quote Oracle Owners And Tables

24.8.8.2. Quote Oracle Columns

24.8.8.3. Confirm The Data Connector for Oracle and Hadoop Can Initialize The Oracle Session

24.8.8.4. Check The Sqoop Debug Logs for Error Messages

24.8.8.5. Export: Check Tables Are Compatible

24.8.8.6. Export: Parallelization

24.8.8.7. Export: Check oraoop.oracle.append.values.hint.usage

24.8.8.8. Turn On Verbose

25. Getting Support

26. Troubleshooting

26.1. General Troubleshooting Process

26.2. Specific Troubleshooting Tips

26.2.1. Oracle: Connection Reset Errors

26.2.2. Oracle: Case-Sensitive Catalog Query Errors

26.2.3. MySQL: Connection Failure

26.2.4. Oracle: ORA-00933 error (SQL command not properly ended)

26.2.5. MySQL: Import of TINYINT(1) from MySQL behaves strangely