SQOOP-931: Integrate HCatalog with Sqoop
[sqoop.git] / src / docs / user / hcatalog.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 Sqoop-HCatalog Integration
21 --------------------------
22
23 HCatalog Background
24 ~~~~~~~~~~~~~~~~~~~
25
26 HCatalog is a table and storage management service for Hadoop that enables
27 users with different data processing tools – Pig, MapReduce, and Hive –
28 to more easily read and write data on the grid. HCatalog’s table abstraction
29 presents users with a relational view of data in the Hadoop distributed
30 file system (HDFS) and ensures that users need not worry about where or
31 in what format their data is stored: RCFile format, text files, or
32 SequenceFiles.
33
34 HCatalog supports reading and writing files in any format for which a Hive
35 SerDe (serializer-deserializer) has been written. By default, HCatalog
36 supports RCFile, CSV, JSON, and SequenceFile formats. To use a custom
37 format, you must provide the InputFormat and OutputFormat as well as the SerDe.
38
39 The ability of HCatalog to abstract various storage formats is used in
40 providing the RCFile (and future file types) support to Sqoop.
41
42 Exposing HCatalog Tables to Sqoop
43 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
44
45 HCatalog integration with Sqoop is patterned on an existing feature set that
46 supports Avro and Hive tables. Five new command line options are introduced,
47 and some command line options defined for Hive are reused.
48
49 New Command Line Options
50 ^^^^^^^^^^^^^^^^^^^^^^^^
51
52 +--hcatalog-database+::
53 Specifies the database name for the HCatalog table. If not specified,
54 the default database name +default+ is used. Providing the
55 +--hcatalog-database+ option without +--hcatalog-table+ is an error.
56 This is not a required option.
57
58 +--hcatalog-table+::
59 The argument value for this option is the HCatalog tablename.
60 The presence of the +--hcatalog-table+ option signifies that the import
61 or export job is done using HCatalog tables, and it is a required option for
62 HCatalog jobs.
63
64 +--hcatalog-home+::
65 The home directory for the HCatalog installation. The directory is
66 expected to have a +lib+ subdirectory and a +share/hcatalog+ subdirectory
67 with necessary HCatalog libraries. If not specified, the system property
68 +hcatalog.home+ will be checked and failing that, a system environment
69 variable +HCAT_HOME+ will be checked.  If none of these are set, the
70 default value will be used and currently the default is set to
71 +/usr/lib/hcatalog+.
72 This is not a required option.
73
74 +--create-hcatalog-table+::
75
76 This option specifies whether an HCatalog table should be created
77 automatically when importing data. By default, HCatalog tables are assumed
78 to exist. The table name will be the same as the database table name
79 translated to lower case. Further described in +Automatic Table Creation+
80 below.
81
82 +--hcatalog-storage-stanza+::
83
84 This option specifies the storage stanza to be appended to the table.
85 Further described in +Automatic Table Creation+ below.
86
87 Supported Sqoop Hive Options
88 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
89
90 The following Sqoop options are also used along with the +--hcatalog-table+
91 option to provide additional input to the HCatalog jobs. Some of the existing
92 Hive import job options are reused with HCatalog jobs instead of creating
93 HCatalog-specific options for the same purpose.
94
95 +--map-column-hive+::
96 This option maps a database column to HCatalog with a specific HCatalog
97 type.
98
99 +--hive-home+::
100 The Hive home location.
101
102 +--hive-partition-key+::
103 Used for static partitioning filter. The partitioning key should be of
104 type STRING. There can be only one static partitioning key.
105
106 +--hive-partition-value+::
107 The value associated with the partition.
108
109 Unsupported Sqoop Options
110 ^^^^^^^^^^^^^^^^^^^^^^^^^
111
112 Unsupported Sqoop Hive Import Options
113 +++++++++++++++++++++++++++++++++++++
114
115 The following Sqoop Hive import options are not supported with HCatalog jobs.
116
117 * +--hive-import+
118 * +--hive-overwrite+
119
120 Unsupported Sqoop Export and Import Options
121 +++++++++++++++++++++++++++++++++++++++++++
122
123 The following Sqoop export and import options are not supported with HCatalog jobs.
124
125 * +--direct+
126 * +--export-dir+
127 * +--target-dir+
128 * +--warehouse-dir+
129 * +--append+
130 * +--as-sequencefile+
131 * +--as-avrofile+
132
133 Ignored Sqoop Options
134 ^^^^^^^^^^^^^^^^^^^^^
135
136 The following options are ignored with HCatalog jobs.
137
138 * All input delimiter options are ignored.
139
140 * Output delimiters are generally ignored unless either
141 +--hive-drop-import-delims+ or +--hive-delims-replacement+ is used. When the
142 +--hive-drop-import-delims+ or +--hive-delims-replacement+ option is
143 specified, all +CHAR+ type database table columns will be post-processed
144 to either remove or replace the delimiters, respectively. See +Delimited Text
145 Formats and Field and Line Delimiter Characters+ below. This is only needed
146 if the HCatalog table uses text formats.
147
148 Automatic Table Creation
149 ~~~~~~~~~~~~~~~~~~~~~~~~
150
151 One of the key features of Sqoop is to manage and create the table metadata
152 when importing into Hadoop. HCatalog import jobs also provide for this
153 feature with the option +--create-hcatalog-table+. Furthermore, one of the
154 important benefits of the HCatalog integration is to provide storage
155 agnosticism to Sqoop data movement jobs. To provide for that feature,
156 HCatalog import jobs provide an option that lets a user specifiy the
157 storage format for the created table.
158
159 The option +--create-hcatalog-table+ is used as an indicator that a table
160 has to be created as part of the HCatalog import job.  If the option 
161 +--create-hcatalog-table+ is specified and the table exists, then the
162 table creation will fail and the job will be aborted.
163
164 The option +--hcatalog-storage-stanza+ can be used to specify the storage
165 format of the newly created table. The default value for this option is
166 +stored as rcfile+. The value specified for this option is assumed to be a
167 valid Hive storage format expression. It will be appended to the +create table+
168 command generated by the HCatalog import job as part of automatic table
169 creation. Any error in the storage stanza will cause the table creation to
170 fail and the import job will be aborted.
171
172 Any additional resources needed to support the storage format referenced in
173 the option +--hcatalog-storage-stanza+ should be provided to the job either
174 by placing them in +$HIVE_HOME/lib+ or by providing them in +HADOOP_CLASSPATH+
175 and +LIBJAR+ files.
176
177 If the option +--hive-partition-key+ is specified, then the value of this
178 option is used as the partitioning key for the newly created table. Only
179 one partitioning key can be specified with this option.
180
181 Object names are mapped to the lowercase equivalents as specified below
182 when mapped to an HCatalog table. This includes the table name (which
183 is the same as the external store table name converted to lower case)
184 and field names.
185
186 Delimited Text Formats and Field and Line Delimiter Characters
187 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
188
189 HCatalog supports delimited text format as one of the table storage formats.
190 But when delimited text is used and the imported data has fields that contain
191 those delimiters, then the data may be parsed into a different number of
192 fields and records by Hive, thereby losing data fidelity.
193
194 For this case, one of these existing Sqoop import options can be used:
195
196 * +--hive-delims-replacement+
197
198 * +--hive-drop-import-delims+
199
200 If either of these options is provided for import, then any column of type
201 STRING will be formatted with the Hive delimiter processing and then written
202 to the HCatalog table.
203
204 HCatalog Table Requirements
205 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
206
207 The HCatalog table should be created before using it as part of a Sqoop job
208 if the default table creation options (with optional storage stanza) are not
209 sufficient. All storage formats supported by HCatalog can be used with the
210 creation of the HCatalog tables. This makes this feature readily adopt new
211 storage formats that come into the Hive project, such as ORC files.
212
213 Support for Partitioning
214 ~~~~~~~~~~~~~~~~~~~~~~~~
215
216 The Sqoop HCatalog feature supports the following table types:
217
218 * Unpartitioned tables
219
220 * Partitioned tables with a static partitioning key specified
221
222 * Partitioned tables with dynamic partition keys from the database
223 result set
224
225 * Partitioned tables with a combination of a static key and additional
226 dynamic partitioning keys
227
228 Schema Mapping
229 ~~~~~~~~~~~~~~
230
231 Sqoop currently does not support column name mapping. However, the user
232 is allowed to override the type mapping. Type mapping loosely follows
233 the Hive type mapping already present in Sqoop except that SQL types
234 “FLOAT” and “REAL” are mapped to HCatalog type “float”. In the Sqoop type
235 mapping for Hive, these two are mapped to “double”. Type mapping is primarily
236 used for checking the column definition correctness only and can be overridden
237 with the --map-column-hive option.
238
239 All types except binary are assignable to a String type.
240
241 Any field of number type (int, shortint, tinyint, bigint and bigdecimal,
242 float and double) is assignable to another field of any number type during
243 exports and imports. Depending on the precision and scale of the target type
244 of assignment, truncations can occur.
245
246 Furthermore, date/time/timestamps are mapped to string (the full
247 date/time/timestamp representation) or bigint (the number of milliseconds
248 since epoch) during imports and exports.
249
250 BLOBs and CLOBs are only supported for imports. The BLOB/CLOB objects when
251 imported are stored in a Sqoop-specific format and knowledge of this format
252 is needed for processing these objects in a Pig/Hive job or another Map Reduce
253 job.
254
255 Database column names are mapped to their lowercase equivalents when mapped
256 to the HCatalog fields. Currently, case-sensitive database object names are
257 not supported.
258
259 Projection of a set of columns from a table to an HCatalog table or loading
260 to a column projection is allowed, subject to table constraints. The dynamic
261 partitioning columns, if any, must be part of the projection when importing
262 data into HCatalog tables.
263
264 Dynamic partitioning fields should be mapped to database columns that are
265 defined with the NOT NULL attribute (although this is not validated). A null
266 value during import for a dynamic partitioning column will abort the Sqoop
267 job.
268
269 Support for HCatalog Data Types
270 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
271
272 All the primitive HCatalog types are supported. Currently all the complex
273 HCatalog types are unsupported.
274
275 BLOB/CLOB database types are only supported for imports.
276
277 Providing Hive and HCatalog Libraries for the Sqoop Job
278 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
279
280 With the support for HCatalog added to Sqoop, any HCatalog job depends on a
281 set of jar files being available both on the Sqoop client host and where the
282 Map/Reduce tasks run. To run HCatalog jobs, the environment variable
283 +HADOOP_CLASSPATH+ must be set up as shown below before launching the Sqoop
284 HCatalog jobs.
285
286 +HADOOP_CLASSPATH=$(hcat -classpath)+
287 +export HADOOP_CLASSPATH+
288
289
290 The necessary HCatalog dependencies will be copied to the distributed cache
291 automatically by the Sqoop job.
292
293 Examples
294 ~~~~~~~~
295
296 Create an HCatalog table, such as:
297
298 +hcat -e "create table txn(txn_date string, cust_id string, amount float,
299 store_id int) partitioned by (cust_id string) stored as rcfile;"+
300
301
302 Then Sqoop import and export of the "txn" HCatalog table can be invoked as
303 follows:
304
305 Import
306 ~~~~~~
307
308 +$SQOOP_HOME/bin/sqoop import --connect <jdbc-url> -table <table-name> --hcatalog-table txn <other sqoop options>+
309
310 Export
311 ~~~~~~
312
313 +$SQOOP_HOME/bin/sqoop export --connect <jdbc-url> -table <table-name> --hcatalog-table txn <other sqoop options>+