SQOOP-319. Support for replacing Hive delimiters.
[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 Alternatively, you can use the +\--hive-delims-replacement+ option
62 to replace those characters with a user-defined string on import to give
63 Hive-compatible text data.  These options should only be used if you use
64 Hive's default delimiters and should not be used if different delimiters
65 are specified.
66
67 Sqoop will pass the field and record delimiters through to Hive. If you do
68 not set any delimiters and do use +\--hive-import+, the field delimiter will
69 be set to +^A+ and the record delimiter will be set to +\n+ to be consistent
70 with Hive's defaults.
71
72 The table name used in Hive is, by default, the same as that of the
73 source table. You can control the output table name with the +\--hive-table+
74 option.
75
76 Hive can put data into partitions for more efficient query
77 performance.  You can tell a Sqoop job to import data for Hive into a
78 particular partition by specifying the +\--hive-partition-key+ and
79 +\--hive-partition-value+ arguments.  The partition value must be a
80 string.  Please see the Hive documentation for more details on
81 partitioning.
82
83 You can import compressed tables into Hive using the +\--compress+ and
84 +\--compression-codec+ options. One downside to compressing tables imported
85 into Hive is that many codecs cannot be split for processing by parallel map
86 tasks. The lzop codec, however, does support splitting. When importing tables
87 with this codec, Sqoop will automatically index the files for splitting and
88 configuring a new Hive table with the correct InputFormat. This feature
89 currently requires that all partitions of a table be compressed with the lzop
90 codec.