Sitelet https://github.com/Philippus/elastic4s/commit/09e7aedfc8051a618a2ca6cba4293f32569fb1dc
Skip to content

Commit 09e7aed

Browse files
chessksamuel
ches
authored and
sksamuel
committed
Stopgap Doc Updates (#1456)
* Remove samples for TcpClient There's probably no sense showing and maintaining examples for deprecated code. * Update samples for 6.3.3 * Update some README documentation for current release/master
1 parent 022b56d commit 09e7aed

14 files changed

Lines changed: 67 additions & 231 deletions

File tree

‎README.md‎

Lines changed: 38 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -75,8 +75,8 @@ https://github.com/sksamuel/elastic4s/tree/master/samples
7575

7676
To get started you will need to add a dependency to either
7777

78-
* [elastic4s-http](http://search.maven.org/#search%7Cga%7C1%7Celastic4s-http)
79-
* [elastic4s-tcp](http://search.maven.org/#search%7Cga%7C1%7Celastic4s-tcp)
78+
* [elastic4s-http](https://mvnrepository.com/artifact/com.sksamuel.elastic4s/elastic4s-http)
79+
* [elastic4s-tcp](https://mvnrepository.com/artifact/com.sksamuel.elastic4s/elastic4s-tcp)
8080

8181
depending on which client you intend you use (or both).
8282

@@ -93,12 +93,12 @@ client classes.
9393
Requests are created using the elastic4s DSL. For example to create a search request, you would do:
9494

9595
```scala
96-
search("index" / "type").query("findthistext")`
96+
search("index" / "type").query("findthistext")
9797
```
9898

9999
The DSL methods are located in the `ElasticDsl` trait which needs to be imported or extended. Although the syntax is
100100
identical whether you use the HTTP or TCP client, you must import the appropriate trait
101-
(`com.sksamuel.elastic4s.ElasticDSL` for TCP or `com.sksamuel.elastic4s.http.ElasticDSL` for HTTP) depending on which
101+
(`com.sksamuel.elastic4s.ElasticDsl` for TCP or `com.sksamuel.elastic4s.http.ElasticDsl` for HTTP) depending on which
102102
client you are using.
103103

104104
### Example SBT Setup
@@ -123,18 +123,23 @@ libraryDependencies ++= Seq(
123123

124124
### Example Application
125125

126-
An example is worth 1000 characters so here is a quick example of how to connect to a node with a client, create and
126+
An example is worth 1000 characters so here is a quick example of how to connect to a node with a client, create an
127127
index and index a one field document. Then we will search for that document using a simple text query.
128128

129129
```scala
130+
import com.sksamuel.elastic4s.RefreshPolicy
131+
import com.sksamuel.elastic4s.embedded.LocalNode
132+
import com.sksamuel.elastic4s.http.{RequestFailure, RequestSuccess}
133+
import com.sksamuel.elastic4s.http.search.SearchResponse
134+
130135
object ArtistIndex extends App {
131136

132137
// spawn an embedded node for testing
133138
val localNode = LocalNode("mycluster", "/tmp/datapath")
134139

135140
// in this example we create a client attached to the embedded node, but
136-
// in a real application you would provide the HTTP address to the HttpClient constructor.
137-
val client = localNode.http(true)
141+
// in a real application you would provide the HTTP address to the ElasticClient constructor.
142+
val client = localNode.client(shutdownNodeOnClose = true)
138143

139144
// we must import the dsl
140145
import com.sksamuel.elastic4s.http.ElasticDsl._
@@ -152,27 +157,30 @@ object ArtistIndex extends App {
152157
}.await
153158

154159
// Next we index a single document which is just the name of an Artist.
155-
// The RefreshPolicy.IMMEDIATE means that we want this document to flush to the disk immmediately.
160+
// The RefreshPolicy.Immediate means that we want this document to flush to the disk immmediately.
156161
// see the section on Eventual Consistency.
157162
client.execute {
158-
indexInto("artists" / "modern").doc("name" -> "L.S. Lowry").refresh(RefreshPolicy.IMMEDIATE)
163+
indexInto("artists" / "modern").fields("name" -> "L.S. Lowry").refresh(RefreshPolicy.Immediate)
159164
}.await
160165

161166
// now we can search for the document we just indexed
162167
val resp = client.execute {
163168
search("artists") query "lowry"
164169
}.await
165170

166-
// resp is an Either of a RequestFailure instance containing the elasticsearch error details,
167-
// or a RequestSuccess instance that depends on the type of request.
171+
// resp is a Response[+U] ADT consisting of either a RequestFailure containing the
172+
// Elasticsearch error details, or a RequestSuccess[U] that depends on the type of request.
168173
// In this case it is a RequestSuccess[SearchResponse]
169174

170175
println("---- Search Results ----")
171176
resp match {
172-
case Left(failure) => println("We failed " + failure.error)
173-
case Right(results) => println(results.result.hits)
177+
case failure: RequestFailure => println("We failed " + failure.error)
178+
case results: RequestSuccess[_] => println(results.result.hits)
174179
}
175180

181+
// Response also supports familiar combinators like map / flatMap / foreach:
182+
resp foreach (search => println(s"There were ${search.totalHits} total hits"))
183+
176184
client.close()
177185
}
178186
```
@@ -334,12 +342,12 @@ resolvers += "elasticsearch-releases" at "https://artifacts.elastic.co/maven"
334342

335343
## Embedded Node
336344

337-
A locally configured node and client can be created by including the elastic4s-embedded module. Then a local node can be started by invoking `LocalNode()` with the cluster name and data path. From the local node we can return a handle to the client by invoking the `elastic4sclient` function.
345+
A locally configured node and client can be created by including the elastic4s-embedded module. Then a local node can be started by invoking `LocalNode()` with the cluster name and data path. From the local node we can return a handle to the client by invoking the `client` function.
338346

339347
```scala
340-
import com.sksamuel.elastic4s.ElasticClient
348+
import com.sksamuel.elastic4s.embedded.LocalNode
341349
val node = LocalNode(clusterName, pathHome)
342-
val client = node.elastic4sclient()
350+
val client = node.client(shutdownNodeOnClose = true)
343351
```
344352

345353
To specify settings for the local node you can pass in a settings object like this:
@@ -350,7 +358,7 @@ val settings = Settings.builder()
350358
.put("http.enabled", false)
351359
.build()
352360
val node = LocalNode(settings)
353-
val client = node.elastic4sclient(<shutdownNodeOnClose>)
361+
val client = node.client(<shutdownNodeOnClose>)
354362
```
355363

356364
If `shutdownNodeOnClose` is true, then once close is called on the client, the local node will be stopped. Otherwise you will manage the lifecycle of the local node yourself (stopping it before exiting the process).
@@ -380,16 +388,16 @@ To do this we add mappings:
380388

381389
```scala
382390
import com.sksamuel.elastic4s.mappings.FieldType._
383-
import com.sksamuel.elastic4s.StopAnalyzer
391+
import com.sksamuel.elastic4s.analyzers.StopAnalyzer
384392

385393
client.execute {
386-
createIndex("places") mappings (
387-
mapping("cities") as (
388-
keywordField("id"),
389-
textField("name") boost 4,
390-
textField("content") analyzer StopAnalyzer
391-
)
394+
createIndex("places") mappings (
395+
mapping("cities") as (
396+
keywordField("id"),
397+
textField("name") boost 4,
398+
textField("content") analyzer StopAnalyzer
392399
)
400+
)
393401
}
394402
```
395403

@@ -464,7 +472,7 @@ Simply add the import for your chosen library below and then with those implicit
464472
## Searching
465473

466474
Searching is naturally the most involved operation.
467-
There are many ways to do [searching in elastic search](http://www.elasticsearch.org/guide/reference/api/search/) and that is reflected
475+
There are many ways to do [searching in Elasticsearch](http://www.elasticsearch.org/guide/reference/api/search/) and that is reflected
468476
in the higher complexity of the query DSL.
469477

470478
To do a simple text search, where the query is parsed from a single string
@@ -538,8 +546,7 @@ val resp = client.execute {
538546

539547
// .to[Character] will look for an implicit HitReader[Character] in scope
540548
// and then convert all the hits into Characters for us.
541-
val characters :Seq[Character] = resp.to[Character]
542-
549+
val characters: Seq[Character] = resp.to[Character]
543550
```
544551

545552
This is basically the inverse of the `Indexable` typeclass. And just like Indexable, the json modules provide implementations
@@ -616,7 +623,7 @@ We can update existing documents without having to do a full index, by updating
616623

617624
```scala
618625
client.execute {
619-
update(25).in("scifi" / "starwars"). docAsUpsert (
626+
update("25").in("scifi" / "starwars").docAsUpsert (
620627
"character" -> "chewie",
621628
"race" -> "wookie"
622629
)
@@ -648,9 +655,9 @@ wrap index, delete and update requests using the `bulk` keyword and pass to the
648655
```scala
649656
client.execute {
650657
bulk (
651-
index into "bands/rock" fields "name"->"coldplay",
652-
index into "bands/rock" fields "name"->"kings of leon",
653-
index into "bands/pop" fields (
658+
indexInto("bands" / "rock") fields "name"->"coldplay",
659+
indexInto("bands" / "rock") fields "name"->"kings of leon",
660+
indexInto("bands" / "pop") fields (
654661
"name" -> "elton john",
655662
"best_album" -> "tumbleweed connection"
656663
)

‎samples/elastic4s-http-client-gradle/.gitignore‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.gradle/
2+
build/

‎samples/elastic4s-http-client-gradle/build.gradle‎

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,8 @@ allprojects {
1111
}
1212

1313
dependencies {
14-
compile 'org.scala-lang:scala-library:2.12.2'
15-
compile 'com.sksamuel.elastic4s:elastic4s-core_2.12:5.4.2'
16-
compile 'com.sksamuel.elastic4s:elastic4s-http_2.12:5.4.2'
14+
compile 'org.scala-lang:scala-library:2.12.6'
15+
compile 'com.sksamuel.elastic4s:elastic4s-http_2.12:6.3.3'
1716
compile 'org.apache.lucene:lucene-core:6.5.1'
1817
compile 'joda-time:joda-time:2.9.9'
1918
}

‎samples/elastic4s-http-client-gradle/src/main/scala/com/sksamuel/elastic4s/samples/HttpClientExampleApp.scala‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,30 @@
11
package com.sksamuel.elastic4s.samples
22

3-
import com.sksamuel.elastic4s.ElasticsearchClientUri
4-
import com.sksamuel.elastic4s.http.HttpClient
3+
import com.sksamuel.elastic4s.RefreshPolicy
4+
import com.sksamuel.elastic4s.http.{ElasticClient, ElasticProperties}
5+
import com.sksamuel.elastic4s.http.Response
56
import com.sksamuel.elastic4s.http.search.SearchResponse
6-
import org.elasticsearch.action.support.WriteRequest.RefreshPolicy
77

88
object HttpClientExampleApp extends App {
99

1010
// you must import the DSL to use the syntax helpers
1111
import com.sksamuel.elastic4s.http.ElasticDsl._
1212

13-
val client = HttpClient(ElasticsearchClientUri("localhost", 9200))
13+
val client = ElasticClient(ElasticProperties("http://localhost:9200"))
1414

1515
client.execute {
1616
bulk(
1717
indexInto("myindex" / "mytype").fields("country" -> "Mongolia", "capital" -> "Ulaanbaatar"),
1818
indexInto("myindex" / "mytype").fields("country" -> "Namibia", "capital" -> "Windhoek")
19-
).refresh(RefreshPolicy.WAIT_UNTIL)
19+
).refresh(RefreshPolicy.WaitFor)
2020
}.await
2121

22-
val result: SearchResponse = client.execute {
22+
val response: Response[SearchResponse] = client.execute {
2323
search("myindex").matchQuery("capital", "ulaanbaatar")
2424
}.await
2525

2626
// prints out the original json
27-
println(result.hits.hits.head.sourceAsString)
27+
println(response.result.hits.hits.head.sourceAsString)
2828

2929
client.close()
3030

‎samples/elastic4s-http-client-maven/pom.xml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@
77
<version>1.0.1</version>
88

99
<properties>
10-
<scalaVersion>2.12.2</scalaVersion>
11-
<elastic4sVersion>5.4.2</elastic4sVersion>
10+
<scalaVersion>2.12.6</scalaVersion>
11+
<elastic4sVersion>6.3.3</elastic4sVersion>
1212
</properties>
1313

1414
<dependencies>

‎samples/elastic4s-http-client-maven/src/main/scala/com/sksamuel/elastic4s/samples/HttpClientExampleApp.scala‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,30 @@
11
package com.sksamuel.elastic4s.samples
22

3-
import com.sksamuel.elastic4s.ElasticsearchClientUri
4-
import com.sksamuel.elastic4s.http.HttpClient
3+
import com.sksamuel.elastic4s.RefreshPolicy
4+
import com.sksamuel.elastic4s.http.{ElasticClient, ElasticProperties}
5+
import com.sksamuel.elastic4s.http.Response
56
import com.sksamuel.elastic4s.http.search.SearchResponse
6-
import org.elasticsearch.action.support.WriteRequest.RefreshPolicy
77

88
object HttpClientExampleApp extends App {
99

1010
// you must import the DSL to use the syntax helpers
1111
import com.sksamuel.elastic4s.http.ElasticDsl._
1212

13-
val client = HttpClient(ElasticsearchClientUri("localhost", 9200))
13+
val client = ElasticClient(ElasticProperties("http://localhost:9200"))
1414

1515
client.execute {
1616
bulk(
1717
indexInto("myindex" / "mytype").fields("country" -> "Mongolia", "capital" -> "Ulaanbaatar"),
1818
indexInto("myindex" / "mytype").fields("country" -> "Namibia", "capital" -> "Windhoek")
19-
).refresh(RefreshPolicy.WAIT_UNTIL)
19+
).refresh(RefreshPolicy.WaitFor)
2020
}.await
2121

22-
val result: SearchResponse = client.execute {
22+
val response: Response[SearchResponse] = client.execute {
2323
search("myindex").matchQuery("capital", "ulaanbaatar")
2424
}.await
2525

2626
// prints out the original json
27-
println(result.hits.hits.head.sourceAsString)
27+
println(response.result.hits.hits.head.sourceAsString)
2828

2929
client.close()
3030

‎samples/elastic4s-http-client-sbt/build.sbt‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
lazy val root = Project("elastic4s-http-client-sbt", file("."))
22
.settings(name := "elastic4s-http-client-sbt")
3-
.settings(scalaVersion := "2.12.2")
3+
.settings(scalaVersion := "2.12.6")
44
.settings(libraryDependencies ++= Seq(
5-
"com.sksamuel.elastic4s" %% "elastic4s-http" % "5.4.2"
5+
"com.sksamuel.elastic4s" %% "elastic4s-http" % "6.3.3"
66
))

‎samples/elastic4s-http-client-sbt/src/main/scala/com/sksamuel/elastic4s/samples/HttpClientExampleApp.scala‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,30 @@
11
package com.sksamuel.elastic4s.samples
22

3-
import com.sksamuel.elastic4s.ElasticsearchClientUri
4-
import com.sksamuel.elastic4s.http.HttpClient
3+
import com.sksamuel.elastic4s.RefreshPolicy
4+
import com.sksamuel.elastic4s.http.{ElasticClient, ElasticProperties}
5+
import com.sksamuel.elastic4s.http.Response
56
import com.sksamuel.elastic4s.http.search.SearchResponse
6-
import org.elasticsearch.action.support.WriteRequest.RefreshPolicy
77

88
object HttpClientExampleApp extends App {
99

1010
// you must import the DSL to use the syntax helpers
1111
import com.sksamuel.elastic4s.http.ElasticDsl._
1212

13-
val client = HttpClient(ElasticsearchClientUri("localhost", 9200))
13+
val client = ElasticClient(ElasticProperties("http://localhost:9200"))
1414

1515
client.execute {
1616
bulk(
1717
indexInto("myindex" / "mytype").fields("country" -> "Mongolia", "capital" -> "Ulaanbaatar"),
1818
indexInto("myindex" / "mytype").fields("country" -> "Namibia", "capital" -> "Windhoek")
19-
).refresh(RefreshPolicy.WAIT_UNTIL)
19+
).refresh(RefreshPolicy.WaitFor)
2020
}.await
2121

22-
val result: SearchResponse = client.execute {
22+
val response: Response[SearchResponse] = client.execute {
2323
search("myindex").matchQuery("capital", "ulaanbaatar")
2424
}.await
2525

2626
// prints out the original json
27-
println(result.hits.hits.head.sourceAsString)
27+
println(response.result.hits.hits.head.sourceAsString)
2828

2929
client.close()
3030

‎samples/elastic4s-tcp-client-gradle/build.gradle‎

Lines changed: 0 additions & 20 deletions
This file was deleted.

‎samples/elastic4s-tcp-client-gradle/src/main/scala/com/sksamuel/elastic4s/samples/TcpClientExampleApp.scala‎

Lines changed: 0 additions & 29 deletions
This file was deleted.

0 commit comments

Comments
 (0)