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