anchor.diff:  
   |===
   
  -NOTE: While {es} understands Hive types up to version 0.12, it is backwards compatible with Hive 0.9
  -
  -[float]
  -=== Writing data to {es}
  -
  -With {eh}, {es} becomes just an external https://cwiki.apache.org/confluence/display/Hive/LanguageManual`DDL#LanguageManualDDL-CreateTable[table] in which data can be loaded or read from:
  -
  -[source,sql]
  -----
  -CREATE EXTERNAL TABLE artists (
  -    id      BIGINT,
  -    name    STRING,
  -    links   STRUCT<url:STRING, picture:STRING>)
  -STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'<1>
  -TBLPROPERTIES('es.resource' = 'radio/artists/'<2>);
  -
  --- insert data to Elasticsearch from another table called 'source'
  -INSERT OVERWRITE TABLE artists 
  -    SELECT NULL, s.name, named_struct('url', s.url, 'picture', s.picture)
  -                    FROM source s;
  -----
  -
  -<1> {es} Hive `StorageHandler`
  -<2> {es} resource (index and type) associated with the given storage
  -
  -[float]
  -[[writing-json-hive]]
  -==== Writing JSON directly to {es}
  -
  -For cases where the job output data is already in JSON, {eh} allows direct indexing _without_ applying any transformation; the data is taken as is and sent directly to {es}. In such cases, one needs to indicate the json input by setting
  -the `es.input.json` parameter. As such, in this case {eh} expects the output table to contain only one field, who
  -s content is used as the JSON document. That is, the library will recognize specific 'textual' types (such as `string` or `binary`) or simply call (`toString`).
  -
  -.Hive types to use for JSON representation
  -
  -[cols="^,^",options="header"]
  -|===
  -| `Hive type` | Comment 
  -
  -| `binary`          | use this when the JSON data is represented as a `byte[]` or similar
  -| `string`          | use this if the JSON data is represented as a `String`
  -| _anything else_   | make sure the `toString()` returns the desired JSON document
  -
  -2+h| Available in Hive 0.12 or higher
  -
  -| `varchar`         | use this as an alternative to Hive `string`
  -
  -|===
  -
  -IMPORTANT: Make sure the data is properly encoded, in `UTF-8`. The field content is considered the final form of the document sent to {es}.
  -
  -[source,java]
  -----
  -CREATE EXTERNAL TABLE json (data STRING<1>)
  -STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
  -TBLPROPERTIES('es.resource' = '...',
  -              'es.input.json` = 'yes'<2>);
  -...
  -----
  -
  -<1> The table declaration only one field of type `STRING`
  -<2> Indicate {eh} the table content is in JSON format
  -
  -[float]
  -=== Reading data from {es}
  -
  -Reading from {es} is strikingly similar:
  -
  -[source,sql]
  -----
  -CREATE EXTERNAL TABLE artists (
  -    id      BIGINT,
  -    name    STRING,
  -    links   STRUCT<url:STRING, picture:STRING>)
  -STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'<1>
  -TBLPROPERTIES('es.resource' = 'radio/artists/_search?q=me*'<2>);
  -
  --- stream data from Elasticsearch
  -SELECT * FROM artists;
  -----
  -
  -<1> same {es} Hive `StorageHandler`
  -<2> {es} resource (in case of reading, a query) associated with the given storage
  +NOTE: While {es} understands Hive types up to version 0.12, it is backwards compatible with Hive 0.9
positive.code: | `struct`          | `map`
  | `map`             | `map`
  | `array`           | `array`
  | `union`           | not supported yet
  
  2+h| Available in Hive 0.11 or higher
  
  
negative.code: 
  TIP: {es} accepts only lower-case field name and, as such, {eh} will always convert Hive column names to lower-case. This poses no issue as Hive is **case insensitive**
  however it is recommended to use the default Hive style and use upper-case names only for Hive commands and avoid mixed-case names.
  
  [float]
  === Writing data to {es}
  
  With {eh}, {es} becomes just an external https://cwiki.apache.org/confluence/display/Hive/LanguageManual`DDL#LanguageManualDDL-CreateTable[table] in which data can be loaded or read from:
  
  [source,sql]
  ----
  CREATE EXTERNAL TABLE artists (
      id      BIGINT,
      name    STRING,
      links   STRUCT<url:STRING, picture:STRING>)
  STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'<1>
  TBLPROPERTIES('es.resource' = 'radio/artists/'<2>);
  
  -- insert data to Elasticsearch from another table called 'source'
  INSERT OVERWRITE TABLE artists 
      SELECT NULL, s.name, named_struct('url', s.url, 'picture', s.picture)
                      FROM source s;
  ----
  
  <1> {es} Hive `StorageHandler`
  <2> {es} resource (index and type) associated with the given storage
  
  [float]
  [[writing-json-hive]]
  ==== Writing JSON directly to {es}
  
  For cases where the job output data is already in JSON, {eh} allows direct indexing _without_ applying any transformation; the data is taken as is and sent directly to {es}. In such cases, one needs to indicate the json input by setting
  the `es.input.json` parameter. As such, in this case {eh} expects the output table to contain only one field, who
  s content is used as the JSON document. That is, the library will recognize specific 'textual' types (such as `string` or `binary`) or simply call (`toString`).
  
  .Hive types to use for JSON representation
  
  [cols="^,^",options="header"]
  |===
  | `Hive type` | Comment 
  
  | `binary`          | use this when the JSON data is represented as a `byte[]` or similar
  | `string`          | use this if the JSON data is represented as a `String`
  | _anything else_   | make sure the `toString()` returns the desired JSON document
  
  2+h| Available in Hive 0.12 or higher
  
  | `varchar`         | use this as an alternative to Hive `string`
  
  |===
  
  IMPORTANT: Make sure the data is properly encoded, in `UTF-8`. The field content is considered the final form of the document sent to {es}.
  
  [source,java]
  ----
  CREATE EXTERNAL TABLE json (data STRING<1>)
  STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
  TBLPROPERTIES('es.resource' = '...',
                'es.input.json` = 'yes'<2>);
  ...
  ----
  
  <1> The table declaration only one field of type `STRING`
  <2> Indicate {eh} the table content is in JSON format
  
  [float]
  === Reading data from {es}
  
  Reading from {es} is strikingly similar:
  
  [source,sql]
  ----
  CREATE EXTERNAL TABLE artists (
      id      BIGINT,
      name    STRING,
      links   STRUCT<url:STRING, picture:STRING>)
  STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'<1>
  TBLPROPERTIES('es.resource' = 'radio/artists'<2>, 'es.query' = '?q=me*'<3>);
  
  -- stream data from Elasticsearch
  SELECT * FROM artists;
  ----
  
  <1> same {es} Hive `StorageHandler`
  <2> {es} resource
  <3> {es} query
  
  [[hive-type-conversion]]
  [float]
  