Skip to content

Commit ff91d11

Browse files
nik9000jbaiera
nik9000
authored and
jbaiera
committed
Docs: Drop inline callouts (#1270)
Drops the inline callouts from the docs. This is when you write `<1>` anywhere but the end of a line. Asciidoctor doesn't support them and we'd very much like to move to Asciidoctor to generate the docs because it is being actively maintained.
1 parent a915497 commit ff91d11

File tree

6 files changed

+149
-104
lines changed

6 files changed

+149
-104
lines changed

‎docs/src/reference/asciidoc/core/cascading.adoc

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -95,7 +95,8 @@ Simply hook `EsTap` into the Cascading flow:
9595
----
9696
Tap in = new Lfs(new TextDelimited(new Fields("id", "name", "url", "picture")),
9797
"/resources/artists.dat");
98-
Tap out = new EsTap("radio/artists" <1>, new Fields("name", "url", "picture") <2>);
98+
Tap out = new EsTap("radio/artists", <1>
99+
new Fields("name", "url", "picture")); <2>
99100
new HadoopFlowConnector().connect(in, out, new Pipe("write-to-Es")).complete();
100101
----
101102

@@ -140,8 +141,8 @@ One can index the data to a different resource, depending on the tuple being rea
140141

141142
[source,java]
142143
----
143-
Tap out = new EsTap("my-collection/{media.type}" <1>,
144-
new Fields("name", "media.type", "year") <2>);
144+
Tap out = new EsTap("my-collection/{media.type}", <1>
145+
new Fields("name", "media.type", "year")); <2>
145146
----
146147

147148
<1> Resource pattern using field `media.type`
@@ -154,7 +155,7 @@ The functionality is available when dealing with raw JSON as well - in this case
154155
[source,js]
155156
----
156157
{
157-
"media_type":"book",<1>
158+
"media_type":"book", <1>
158159
"title":"Harry Potter",
159160
"year":"2010"
160161
}
@@ -167,7 +168,8 @@ the `Tap` declaration can be as follows:
167168
----
168169
props.setProperty("es.input.json", "true");
169170
Tap in = new Lfs(new TextLine(new Fields("line")),"/archives/collection.json");
170-
Tap out = new EsTap("my-collection/{media_type}" <1>, new Fields("line") <2>);
171+
Tap out = new EsTap("my-collection/{media_type}", <1>
172+
new Fields("line")); <2>
171173
----
172174

173175
<1> Resource pattern relying on fields _within_ the JSON document and _not_ on the `Tap` schema
@@ -180,7 +182,8 @@ Just the same, add `EsTap` on the other end of a pipe, to read (instead of writi
180182

181183
[source,java]
182184
----
183-
Tap in = new EsTap("radio/artists/"<1>,"?q=me*"<2>);
185+
Tap in = new EsTap("radio/artists/", <1>
186+
"?q=me*"); <2>
184187
Tap out = new StdOut(new TextLine());
185188
new LocalFlowConnector().connect(in, out, new Pipe("read-from-Es")).complete();
186189
----

‎docs/src/reference/asciidoc/core/hive.adoc

Lines changed: 11 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,7 @@ When using Hive, one can use `TBLPROPERTIES` to specify the <<configuration,conf
5959
CREATE EXTERNAL TABLE artists (...)
6060
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
6161
TBLPROPERTIES('es.resource' = 'radio/artists',
62-
'es.index.auto.create' = 'false') <1>;
62+
'es.index.auto.create' = 'false'); <1>
6363
----
6464

6565
<1> {eh} setting
@@ -78,12 +78,10 @@ To wit:
7878
CREATE EXTERNAL TABLE artists (...)
7979
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
8080
TBLPROPERTIES('es.resource' = 'radio/artists',
81-
<1>'es.mapping.names' = 'date:@timestamp <2>, url:url_123 <3>');
81+
'es.mapping.names' = 'date:@timestamp, url:url_123'); <1>
8282
----
8383

84-
<1> name mapping for two fields
85-
<2> Hive column `date` mapped in {es} to `@timestamp`
86-
<3> Hive column `url` mapped in {es} to `url_123`
84+
<1> Hive column `date` mapped in {es} to `@timestamp`; Hive column `url` mapped in {es} to `url_123`
8785

8886
TIP: Hive is case **insensitive** while {es} is not. The loss of information can create invalid queries (as the column in Hive might not match the one in {es}). To avoid this, {eh} will always convert Hive column names to lower-case.
8987
This being said, it is recommended to use the default Hive style and use upper-case names only for Hive commands and avoid mixed-case names.
@@ -102,7 +100,7 @@ CREATE EXTERNAL TABLE artists (
102100
name STRING,
103101
links STRUCT<url:STRING, picture:STRING>)
104102
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'<1>
105-
TBLPROPERTIES('es.resource' = 'radio/artists'<2>);
103+
TBLPROPERTIES('es.resource' = 'radio/artists'); <2>
106104
107105
-- insert data to Elasticsearch from another table called 'source'
108106
INSERT OVERWRITE TABLE artists
@@ -148,10 +146,10 @@ IMPORTANT: Make sure the data is properly encoded, in `UTF-8`. The field content
148146

149147
[source,java]
150148
----
151-
CREATE EXTERNAL TABLE json (data STRING<1>)
149+
CREATE EXTERNAL TABLE json (data STRING) <1>
152150
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
153151
TBLPROPERTIES('es.resource' = '...',
154-
'es.input.json` = 'yes'<2>);
152+
'es.input.json` = 'yes'); <2>
155153
...
156154
----
157155

@@ -170,7 +168,7 @@ CREATE EXTERNAL TABLE media (
170168
type STRING,<1>
171169
year STRING,
172170
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
173-
TBLPROPERTIES('es.resource' = 'my-collection/{type}'<2>);
171+
TBLPROPERTIES('es.resource' = 'my-collection/{type}'); <2>
174172
----
175173

176174
<1> Table field used by the resource pattern. Any of the declared fields can be used.
@@ -195,9 +193,9 @@ the table declaration can be as follows:
195193

196194
[source,sql]
197195
----
198-
CREATE EXTERNAL TABLE json (data STRING<1>)
196+
CREATE EXTERNAL TABLE json (data STRING) <1>
199197
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'
200-
TBLPROPERTIES('es.resource' = 'my-collection/{media_type}'<2>,
198+
TBLPROPERTIES('es.resource' = 'my-collection/{media_type}', <2>
201199
'es.input.json` = 'yes');
202200
----
203201

@@ -216,7 +214,8 @@ CREATE EXTERNAL TABLE artists (
216214
name STRING,
217215
links STRUCT<url:STRING, picture:STRING>)
218216
STORED BY 'org.elasticsearch.hadoop.hive.EsStorageHandler'<1>
219-
TBLPROPERTIES('es.resource' = 'radio/artists'<2>, 'es.query' = '?q=me*'<3>);
217+
TBLPROPERTIES('es.resource' = 'radio/artists', <2>
218+
'es.query' = '?q=me*'); <3>
220219
221220
-- stream data from Elasticsearch
222221
SELECT * FROM artists;

‎docs/src/reference/asciidoc/core/intro/download.adoc

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ These are available under the same `groupId`, using an `artifactId` with the pat
2828
----
2929
<dependency>
3030
<groupId>org.elasticsearch</groupId>
31-
<artifactId>elasticsearch-hadoop-mr<1></artifactId>
31+
<artifactId>elasticsearch-hadoop-mr</artifactId> <1>
3232
<version>{ver}</version>
3333
</dependency>
3434
----
@@ -40,7 +40,7 @@ These are available under the same `groupId`, using an `artifactId` with the pat
4040
----
4141
<dependency>
4242
<groupId>org.elasticsearch</groupId>
43-
<artifactId>elasticsearch-hadoop-hive<1></artifactId>
43+
<artifactId>elasticsearch-hadoop-hive</artifactId> <1>
4444
<version>{ver}</version>
4545
</dependency>
4646
----
@@ -52,7 +52,7 @@ These are available under the same `groupId`, using an `artifactId` with the pat
5252
----
5353
<dependency>
5454
<groupId>org.elasticsearch</groupId>
55-
<artifactId>elasticsearch-hadoop-pig<1></artifactId>
55+
<artifactId>elasticsearch-hadoop-pig</artifactId> <1>
5656
<version>{ver}</version>
5757
</dependency>
5858
----
@@ -64,13 +64,16 @@ These are available under the same `groupId`, using an `artifactId` with the pat
6464
----
6565
<dependency>
6666
<groupId>org.elasticsearch</groupId>
67-
<artifactId>elasticsearch-spark-20<1>_2.10<2></artifactId>
67+
<artifactId>elasticsearch-spark-20_2.10</artifactId> <1>
6868
<version>{ver}</version>
6969
</dependency>
7070
----
7171

72-
<1> 'spark' artifact. Notice the `-20` part of the suffix which indicates the Spark version compatible with the artifact. Use `20` for Spark 2.0+ and `13` for Spark 1.3-1.6.
73-
<2> Notice the `_2.10` suffix which indicates the Scala version compatible with the artifact. Currently it is the same as the version used by Spark itself.
72+
<1> 'spark' artifact. Notice the `-20` part of the suffix which indicates the
73+
Spark version compatible with the artifact. Use `20` for Spark 2.0+ and `13` for
74+
Spark 1.3-1.6. Notice the `_2.10` suffix which indicates the Scala version
75+
compatible with the artifact. Currently it is the same as the version used by
76+
Spark itself.
7477

7578
The Spark connector framework is the most sensitive to version incompatibilities. For your convenience, a version compatibility matrix has been provided below:
7679
[cols="2,2,10",options="header",]
@@ -89,7 +92,7 @@ The Spark connector framework is the most sensitive to version incompatibilities
8992
----
9093
<dependency>
9194
<groupId>org.elasticsearch</groupId>
92-
<artifactId>elasticsearch-hadoop-cascading<1></artifactId>
95+
<artifactId>elasticsearch-hadoop-cascading</artifactId> <1>
9396
<version>{ver}</version>
9497
</dependency>
9598
----
@@ -114,7 +117,7 @@ in order for the Cascading dependencies to be properly resolved:
114117
----
115118
<dependency>
116119
<groupId>org.elasticsearch</groupId>
117-
<artifactId>elasticsearch-storm<1></artifactId>
120+
<artifactId>elasticsearch-storm</artifactId> <1>
118121
<version>{ver}</version>
119122
</dependency>
120123
----

‎docs/src/reference/asciidoc/core/pig.adoc

Lines changed: 19 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -44,9 +44,10 @@ With Pig, one can specify the <<configuration,configuration>> properties (as an
4444

4545
[source,sql]
4646
----
47-
STORE B INTO 'radio/artists'<1> USING org.elasticsearch.hadoop.pig.EsStorage
48-
('es.http.timeout = 5m<2>',
49-
'es.index.auto.create = false' <3>);
47+
STORE B INTO 'radio/artists' <1>
48+
USING org.elasticsearch.hadoop.pig.EsStorage
49+
('es.http.timeout = 5m', <2>
50+
'es.index.auto.create = false'); <3>
5051
----
5152

5253
<1> {eh} configuration (target resource)
@@ -163,12 +164,10 @@ For example:
163164
[source,sql]
164165
----
165166
STORE B INTO '...' USING org.elasticsearch.hadoop.pig.EsStorage(
166-
'<1>es.mapping.names=date:@timestamp<2>, uRL:url<3>')
167+
'es.mapping.names=date:@timestamp, uRL:url') <1>
167168
----
168169

169-
<1> name mapping for two fields
170-
<2> Pig column `date` mapped in {es} to `@timestamp`
171-
<3> Pig column `uRL` mapped in {es} to `url`
170+
<1> Pig column `date` mapped in {es} to `@timestamp`; Pig column `uRL` mapped in {es} to `url`
172171

173172
TIP: Since {eh} 2.1, the Pig schema case sensitivity is preserved to {es} and back.
174173

@@ -185,11 +184,13 @@ A = LOAD 'src/test/resources/artists.dat' USING PigStorage()
185184
-- transform data
186185
B = FOREACH A GENERATE name, TOTUPLE(url, picture) AS links;
187186
-- save the result to Elasticsearch
188-
STORE B INTO 'radio/artists'<1> USING org.elasticsearch.hadoop.pig.EsStorage(<2>);
187+
STORE B INTO 'radio/artists'<1>
188+
USING org.elasticsearch.hadoop.pig.EsStorage(); <2>
189189
----
190190

191191
<1> {es} resource (index and type) associated with the given storage
192-
<2> additional configuration parameters can be passed here - in this case the defaults are used
192+
<2> additional configuration parameters can be passed inside the `()` - in this
193+
case the defaults are used
193194

194195
For cases where the id (or other metadata fields like +ttl+ or +timestamp+) of the document needs to be specified, one can do so by setting the appropriate <<cfg-mapping, mapping>>, namely +es.mapping.id+. Following the previous example, to indicate to {es} to use the field +id+ as the document id, update the +Storage+ configuration:
195196

@@ -219,9 +220,9 @@ IMPORTANT: Make sure the data is properly encoded, in `UTF-8`. The field content
219220

220221
[source,sql]
221222
----
222-
A = LOAD '/resources/artists.json' USING PigStorage() AS (json:chararray<1>);"
223+
A = LOAD '/resources/artists.json' USING PigStorage() AS (json:chararray);" <1>
223224
STORE B INTO 'radio/artists'
224-
USING org.elasticsearch.hadoop.pig.EsStorage('es.input.json=true'<2>...);
225+
USING org.elasticsearch.hadoop.pig.EsStorage('es.input.json=true'...); <2>
225226
----
226227

227228
<1> Load the (JSON) data as a single field (`json`)
@@ -235,8 +236,9 @@ One can index the data to a different resource, depending on the 'row' being rea
235236
[source,sql]
236237
----
237238
A = LOAD 'src/test/resources/media.dat' USING PigStorage()
238-
AS (name:chararray, type:chararray <1>, year: chararray);
239-
STORE B INTO 'my-collection/{type}'<2> USING org.elasticsearch.hadoop.pig.EsStorage();
239+
AS (name:chararray, type:chararray, year: chararray); <1>
240+
STORE B INTO 'my-collection/{type}' <2>
241+
USING org.elasticsearch.hadoop.pig.EsStorage();
240242
----
241243

242244
<1> Tuple field used by the resource pattern. Any of the declared fields can be used.
@@ -262,8 +264,8 @@ the table declaration can be as follows:
262264

263265
[source,sql]
264266
----
265-
A = LOAD '/resources/media.json' USING PigStorage() AS (json:chararray<1>);"
266-
STORE B INTO 'my-collection/{media_type}'<2>
267+
A = LOAD '/resources/media.json' USING PigStorage() AS (json:chararray);" <1>
268+
STORE B INTO 'my-collection/{media_type}' <2>
267269
USING org.elasticsearch.hadoop.pig.EsStorage('es.input.json=true');
268270
----
269271

@@ -278,8 +280,8 @@ As you would expect, loading the data is straight forward:
278280
[source,sql]
279281
----
280282
-- execute Elasticsearch query and load data into Pig
281-
A = LOAD 'radio/artists'<1>
282-
USING org.elasticsearch.hadoop.pig.EsStorage('es.query=?me*'<2>);
283+
A = LOAD 'radio/artists' <1>
284+
USING org.elasticsearch.hadoop.pig.EsStorage('es.query=?me*'); <2>
283285
DUMP A;
284286
----
285287

0 commit comments

Comments
 (0)