SQOOP-3309: Implement HiveServer2 client
[sqoop.git] / src / docs / user / hive.txt
1
2 ////
3   Licensed to the Apache Software Foundation (ASF) under one
4   or more contributor license agreements.  See the NOTICE file
5   distributed with this work for additional information
6   regarding copyright ownership.  The ASF licenses this file
7   to you under the Apache License, Version 2.0 (the
8   "License"); you may not use this file except in compliance
9   with the License.  You may obtain a copy of the License at
10  
11       http://www.apache.org/licenses/LICENSE-2.0
12  
13   Unless required by applicable law or agreed to in writing, software
14   distributed under the License is distributed on an "AS IS" BASIS,
15   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16   See the License for the specific language governing permissions and
17   limitations under the License.
18 ////
19
20
21 Importing Data Into Hive
22 ^^^^^^^^^^^^^^^^^^^^^^^^
23
24 Sqoop's import tool's main function is to upload your data into files
25 in HDFS. If you have a Hive metastore associated with your HDFS
26 cluster, Sqoop can also import the data into Hive by generating and
27 executing a +CREATE TABLE+ statement to define the data's layout in
28 Hive. Importing data into Hive is as simple as adding the
29 *+\--hive-import+* option to your Sqoop command line.
30
31 If the Hive table already exists, you can specify the
32 *+\--hive-overwrite+* option to indicate that existing table in hive must
33 be replaced. After your data is imported into HDFS or this step is
34 omitted, Sqoop will generate a Hive script containing a +CREATE TABLE+
35 operation defining your columns using Hive's types, and a +LOAD DATA INPATH+
36 statement to move the data files into Hive's warehouse directory.
37
38 The script can be executed in two ways:
39
40 - By the default the script will be executed by calling
41 the installed copy of hive on the machine where Sqoop is run. If you have
42 multiple Hive installations, or +hive+ is not in your +$PATH+, use the
43 *+\--hive-home+* option to identify the Hive installation directory.
44 Sqoop will use +$HIVE_HOME/bin/hive+ from here.
45
46 - If the user specifies the *+\--hs2-url+* parameter then the script will
47  be sent to HiveServer2 through a JDBC connection. Note that the data itself
48  will not be transferred via the JDBC connection it is written directly to HDFS
49  just like in case of the default hive import. As HiveServer2 provides proper
50  authorization and auditing features it is recommended to use this instead of
51  the default. Currently only Kerberos authentication and text file format is
52  supported with this option.
53
54 NOTE: This function is incompatible with +\--as-avrodatafile+ and
55 +\--as-sequencefile+.
56
57 Even though Hive supports escaping characters, it does not
58 handle escaping of new-line character. Also, it does not support
59 the notion of enclosing characters that may include field delimiters
60 in the enclosed string.  It is therefore recommended that you choose
61 unambiguous field and record-terminating delimiters without the help
62 of escaping and enclosing characters when working with Hive; this is
63 due to limitations of Hive's input parsing abilities. If you do use
64 +\--escaped-by+, +\--enclosed-by+, or +\--optionally-enclosed-by+ when
65 importing data into Hive, Sqoop will print a warning message.
66
67 Hive will have problems using Sqoop-imported data if your database's
68 rows contain string fields that have Hive's default row delimiters
69 (+\n+ and +\r+ characters) or column delimiters (+\01+ characters)
70 present in them.  You can use the +\--hive-drop-import-delims+ option
71 to drop those characters on import to give Hive-compatible text data.
72 Alternatively, you can use the +\--hive-delims-replacement+ option
73 to replace those characters with a user-defined string on import to give
74 Hive-compatible text data.  These options should only be used if you use
75 Hive's default delimiters and should not be used if different delimiters
76 are specified.
77
78 Sqoop will pass the field and record delimiters through to Hive. If you do
79 not set any delimiters and do use +\--hive-import+, the field delimiter will
80 be set to +^A+ and the record delimiter will be set to +\n+ to be consistent
81 with Hive's defaults.
82
83 Sqoop will by default import NULL values as string +null+. Hive is however
84 using string +\N+ to denote +NULL+ values and therefore predicates dealing
85 with +NULL+ (like +IS NULL+) will not work correctly. You should append
86 parameters +\--null-string+ and +\--null-non-string+ in case of import job or
87 +--input-null-string+ and +--input-null-non-string+ in case of an export job if
88 you wish to properly preserve +NULL+ values. Because sqoop is using those
89 parameters in generated code, you need to properly escape value +\N+ to +\\N+:
90
91 ----
92 $ sqoop import  ... --null-string '\\N' --null-non-string '\\N'
93 ----
94
95 The table name used in Hive is, by default, the same as that of the
96 source table. You can control the output table name with the +\--hive-table+
97 option.
98
99 Hive can put data into partitions for more efficient query
100 performance.  You can tell a Sqoop job to import data for Hive into a
101 particular partition by specifying the +\--hive-partition-key+ and
102 +\--hive-partition-value+ arguments.  The partition value must be a
103 string.  Please see the Hive documentation for more details on
104 partitioning.
105
106 You can import compressed tables into Hive using the +\--compress+ and
107 +\--compression-codec+ options. One downside to compressing tables imported
108 into Hive is that many codecs cannot be split for processing by parallel map
109 tasks. The lzop codec, however, does support splitting. When importing tables
110 with this codec, Sqoop will automatically index the files for splitting and
111 configuring a new Hive table with the correct InputFormat. This feature
112 currently requires that all partitions of a table be compressed with the lzop
113 codec.