Skip to content

Commit f9aa812

Browse files
szabostevepicandocodigo
szabosteve
and
picandocodigo
authored
[DOCS] Adds examples section to Ruby book (#1277) (#1278)
Co-authored-by: Fernando Briano <[email protected]>
1 parent 7f47962 commit f9aa812

File tree

2 files changed

+213
-0
lines changed

2 files changed

+213
-0
lines changed

‎docs/examples.asciidoc

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
[[examples]]
2+
== Examples
3+
4+
Below you can find examples of how to use the most frequently called APIs with
5+
the Ruby client.
6+
7+
* <<ex-index>>
8+
* <<ex-get>>
9+
* <<ex-update>>
10+
* <<ex-delete>>
11+
* <<ex-bulk>>
12+
* <<ex-search>>
13+
* <<ex-scroll>>
14+
* <<ex-reindex>>
15+
16+
17+
[discrete]
18+
[[ex-index]]
19+
=== Indexing a document
20+
21+
Let's index a document with the following fields: `name`, `author`,
22+
`release_date`, and `page_count`:
23+
24+
```ruby
25+
body = {
26+
name: "The Hitchhiker's Guide to the Galaxy",
27+
author: "Douglas Adams",
28+
release_date: "1979-10-12",
29+
page_count: 180
30+
}
31+
32+
client.index(index: 'books', body: body)
33+
```
34+
35+
36+
[discrete]
37+
[[ex-get]]
38+
=== Getting a document
39+
40+
You can get a document by ID:
41+
42+
```ruby
43+
id = 'l7LRjXgB2_ry9btNEv_V'
44+
client.get(index: 'books', id: id)
45+
```
46+
47+
48+
[discrete]
49+
[[ex-update]]
50+
=== Updating a document
51+
52+
Assume you have the following document:
53+
54+
```
55+
book = {"name": "Foundation", "author": "Isaac Asimov", "release_date": "1951-06-01", "page_count": 224}
56+
```
57+
58+
You can update the document by using the following script:
59+
60+
```ruby
61+
response = client.index(index: 'books', body: book)
62+
id = response['_id']
63+
client.update(index: 'books', id: id, body: { doc: { page_count: 225 } })
64+
```
65+
66+
67+
[discrete]
68+
[[ex-delete]]
69+
=== Deleting a document
70+
71+
You can delete a document by ID:
72+
73+
```ruby
74+
id = 'l7LRjXgB2_ry9btNEv_V'
75+
client.delete(index: 'books', id: id)
76+
```
77+
78+
79+
[discrete]
80+
[[ex-bulk]]
81+
=== Bulk requests
82+
83+
The `bulk` operation of the client supports various different formats of the
84+
payload: array of strings, header/data pairs, or the combined format where data
85+
is passed along with the header in a single item in a custom `:data` key.
86+
87+
Index several documents in one request:
88+
89+
```ruby
90+
body = [
91+
{ index: { _index: 'books', _id: '42' } },
92+
{ name: "The Hitchhiker's Guide to the Galaxy", author: 'Douglas Adams', release_date: '1979-10-12', page_count: 180},
93+
{ index: { _index: 'books', _id: '43' } },
94+
{ name: 'Snow Crash', author: 'Neal Stephenson', release_date: '1992-06-01', page_count: 470 },
95+
{ index: { _index: 'books', _id: '44' } },
96+
{ name: 'Starship Troopers', author: 'Robert A. Heinlein', release_date: '1959-12-01', page_count: 335}
97+
]
98+
client.bulk(body: body)
99+
```
100+
101+
Delete several documents:
102+
103+
```ruby
104+
body = [
105+
{ delete: { _index: 'books', _id: '42' } },
106+
{ delete: { _index: 'books', _id: '43' } },
107+
]
108+
client.bulk(body: body)
109+
```
110+
111+
As mentioned, you can perform several operations in a single request with the
112+
combined format passing data in the `:data` option:
113+
114+
```ruby
115+
body = [
116+
{ index: { _index: 'books', _id: 45, data: { name: '1984', author: 'George Orwell', release_date: '1985-06-01', page_count: 328 } } },
117+
{ update: { _index: 'books', _id: 43, data: { doc: { page_count: 471 } } } },
118+
{ delete: { _index: 'books', _id: 44 } }
119+
]
120+
client.bulk(body: body)
121+
```
122+
123+
124+
[discrete]
125+
[[ex-search]]
126+
=== Searching for a document
127+
128+
This example uses the same data that is used in the
129+
https://www.elastic.co/guide/en/elasticsearch/reference/current/find-structure.html#find-structure-example-nld-json[Find structure API documentation].
130+
131+
First, bulk index it:
132+
133+
[source,ruby]
134+
----
135+
body = [
136+
{ index: { _index: 'books', data: {name: "Leviathan Wakes", "author": "James S.A. Corey", "release_date": "2011-06-02", "page_count": 561} } },
137+
{ index: { _index: 'books', data: {name: "Hyperion", "author": "Dan Simmons", "release_date": "1989-05-26", "page_count": 482} } },
138+
{ index: { _index: 'books', data: {name: "Dune", "author": "Frank Herbert", "release_date": "1965-06-01", "page_count": 604} } },
139+
{ index: { _index: 'books', data: {name: "Dune Messiah", "author": "Frank Herbert", "release_date": "1969-10-15", "page_count": 331} } },
140+
{ index: { _index: 'books', data: {name: "Children of Dune", "author": "Frank Herbert", "release_date": "1976-04-21", "page_count": 408} } },
141+
{ index: { _index: 'books', data: {name: "God Emperor of Dune", "author": "Frank Herbert", "release_date": "1981-05-28", "page_count": 454} } },
142+
{ index: { _index: 'books', data: {name: "Consider Phlebas", "author": "Iain M. Banks", "release_date": "1987-04-23", "page_count": 471} } },
143+
{ index: { _index: 'books', data: {name: "Pandora's Star", "author": "Peter F. Hamilton", "release_date": "2004-03-02", "page_count": 768} } },
144+
{ index: { _index: 'books', data: {name: "Revelation Space", "author": "Alastair Reynolds", "release_date": "2000-03-15", "page_count": 585} } },
145+
{ index: { _index: 'books', data: {name: "A Fire Upon the Deep", "author": "Vernor Vinge", "release_date": "1992-06-01", "page_count": 613} } },
146+
{ index: { _index: 'books', data: {name: "Ender's Game", "author": "Orson Scott Card", "release_date": "1985-06-01", "page_count": 324} } },
147+
{ index: { _index: 'books', data: {name: "1984", "author": "George Orwell", "release_date": "1985-06-01", "page_count": 328} } },
148+
{ index: { _index: 'books', data: {name: "Fahrenheit 451", "author": "Ray Bradbury", "release_date": "1953-10-15", "page_count": 227} } },
149+
{ index: { _index: 'books', data: {name: "Brave New World", "author": "Aldous Huxley", "release_date": "1932-06-01", "page_count": 268} } },
150+
{ index: { _index: 'books', data: {name: "Foundation", "author": "Isaac Asimov", "release_date": "1951-06-01", "page_count": 224} } },
151+
{ index: { _index: 'books', data: {name: "The Giver", "author": "Lois Lowry", "release_date": "1993-04-26", "page_count": 208} } },
152+
{ index: { _index: 'books', data: {name: "Slaughterhouse-Five", "author": "Kurt Vonnegut", "release_date": "1969-06-01", "page_count": 275} } },
153+
{ index: { _index: 'books', data: {name: "The Hitchhiker's Guide to the Galaxy", "author": "Douglas Adams", "release_date": "1979-10-12", "page_count": 180} } },
154+
{ index: { _index: 'books', data: {name: "Snow Crash", "author": "Neal Stephenson", "release_date": "1992-06-01", "page_count": 470} } },
155+
{ index: { _index: 'books', data: {name: "Neuromancer", "author": "William Gibson", "release_date": "1984-07-01", "page_count": 271} } },
156+
{ index: { _index: 'books', data: {name: "The Handmaid's Tale", "author": "Margaret Atwood", "release_date": "1985-06-01", "page_count": 311} } },
157+
{ index: { _index: 'books', data: {name: "Starship Troopers", "author": "Robert A. Heinlein", "release_date": "1959-12-01", "page_count": 335} } },
158+
{ index: { _index: 'books', data: {name: "The Left Hand of Darkness", "author": "Ursula K. Le Guin", "release_date": "1969-06-01", "page_count": 304} } },
159+
{ index: { _index: 'books', data: {name: "The Moon is a Harsh Mistress", "author": "Robert A. Heinlein", "release_date": "1966-04-01", "page_count": 288 } } }
160+
]
161+
client.bulk(body: body)
162+
----
163+
164+
The `field` parameter is a common parameter, so it can be passed in directly in
165+
the following way:
166+
167+
```ruby
168+
client.search(index: 'books', q: 'dune', field: 'name')
169+
```
170+
171+
You can do the same by using body request parameters:
172+
173+
```ruby
174+
client.search(index: 'books', q: 'dune', body: { fields: [{ field: 'name' }] })
175+
response = client.search(index: 'books', body: { size: 15 })
176+
response['hits']['hits'].count # => 15
177+
```
178+
179+
180+
[discrete]
181+
[[ex-scroll]]
182+
=== Scrolling
183+
184+
Submit a search API request that includes an argument for the scroll query
185+
parameter, save the search ID, then print out the book names you found:
186+
187+
```ruby
188+
# Search request with a scroll argument:
189+
response = client.search(index: 'books', scroll: '10m')
190+
191+
# Save the scroll id:
192+
scroll_id = response['_scroll_id']
193+
194+
# Print out the names of all the books we find:
195+
while response['hits']['hits'].size.positive?
196+
response = client.scroll(scroll: '5m', body: { scroll_id: scroll_id })
197+
puts(response['hits']['hits'].map { |r| r['_source']['name'] })
198+
end
199+
```
200+
201+
202+
[discrete]
203+
[[ex-reindex]]
204+
=== Reindexing
205+
206+
The following example shows how to reindex the `books` index into a new index
207+
called `books-reindexed`:
208+
209+
```ruby
210+
client.reindex(body: {source: { index: 'books'}, dest: {index: 'books-reindexed' } })
211+
```

‎docs/index.asciidoc

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,4 +18,6 @@ include::advanced-config.asciidoc[]
1818

1919
include::integrations.asciidoc[]
2020

21+
include::examples.asciidoc[]
22+
2123
include::release_notes/index.asciidoc[]

0 commit comments

Comments
 (0)