runtime.asciidoc 25 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769
  1. [[runtime]]
  2. == Runtime fields
  3. A _runtime field_ is a field that is evaluated at query time. Runtime fields
  4. enable you to:
  5. * Add fields to existing documents without reindexing your data
  6. * Start working with your data without understanding how it’s structured
  7. * Override the value returned from an indexed field at query time
  8. * Define fields for a specific use without modifying the underlying schema
  9. You access runtime fields from the search API like any other field, and {es}
  10. sees runtime fields no differently. You can define runtime fields in the
  11. <<runtime-mapping-fields,index mapping>> or in the
  12. <<runtime-search-request,search request>>. Your choice, which is part of the
  13. inherent flexibility of runtime fields.
  14. Runtime fields are useful when working with log data
  15. (see <<runtime-examples,examples>>), especially when you're unsure about the
  16. data structure. Your search speed decreases, but your index size is much
  17. smaller and you can more quickly process logs without having to index them.
  18. [discrete]
  19. [[runtime-benefits]]
  20. === Benefits
  21. Because runtime fields aren't indexed, adding a runtime field doesn't increase
  22. the index size. You define runtime fields directly in the index mapping, saving
  23. storage costs and increasing ingestion speed. You can more quickly ingest
  24. data into the Elastic Stack and access it right away. When you define a runtime
  25. field, you can immediately use it in search requests, aggregations, filtering,
  26. and sorting.
  27. If you make a runtime field an indexed field, you don't need to modify any
  28. queries that refer to the runtime field. Better yet, you can refer to some
  29. indices where the field is a runtime field, and other indices where the field
  30. is an indexed field. You have the flexibility to choose which fields to index
  31. and which ones to keep as runtime fields.
  32. At its core, the most important benefit of runtime fields is the ability to
  33. add fields to documents after you've ingested them. This capability simplifies
  34. mapping decisions because you don't have to decide how to parse your data up
  35. front, and can use runtime fields to amend the mapping at any time. Using
  36. runtime fields allows for a smaller index and faster ingest time, which
  37. combined use less resources and reduce your operating costs.
  38. [discrete]
  39. [[runtime-compromises]]
  40. === Compromises
  41. Runtime fields use less disk space and provide flexibility in how you access
  42. your data, but can impact search performance based on the computation defined in
  43. the runtime script.
  44. To balance search performance and flexibility, index fields that you'll
  45. commonly search for and filter on, such as a timestamp. {es} automatically uses
  46. these indexed fields first when running a query, resulting in a fast response
  47. time. You can then use runtime fields to limit the number of fields that {es}
  48. needs to calculate values for. Using indexed fields in tandem with runtime
  49. fields provides flexibility in the data that you index and how you define
  50. queries for other fields.
  51. Use the <<async-search,asynchronous search API>> to run searches that include
  52. runtime fields. This method of search helps to offset the performance impacts
  53. of computing values for runtime fields in each document containing that field.
  54. If the query can't return the result set synchronously, you'll get results
  55. asynchronously as they become available.
  56. IMPORTANT: Queries against runtime fields are considered expensive. If
  57. <<query-dsl-allow-expensive-queries,`search.allow_expensive_queries`>> is set
  58. to `false`, expensive queries are not allowed and {es} will reject any queries
  59. against runtime fields.
  60. [[runtime-mapping-fields]]
  61. === Map a runtime field
  62. You map runtime fields by adding a `runtime` section under the mapping
  63. definition and defining
  64. <<modules-scripting-using,a Painless script>>. This script has access to the
  65. entire context of a document, including the original `_source` and any mapped
  66. fields plus their values. At query time, the script runs and generates values
  67. for each scripted field that is required for the query.
  68. When defining a Painless script to use with runtime fields, you must include
  69. `emit` to emit calculated values. For example, the script in the following
  70. request extracts the day of the week from the `@timestamp` field, which is
  71. defined as a `date` type. The script calculates the day of the week based on
  72. the value of `timestamp`, and uses `emit` to return the calculated value.
  73. [source,console]
  74. ----
  75. PUT my-index/
  76. {
  77. "mappings": {
  78. "runtime": {
  79. "day_of_week": {
  80. "type": "keyword",
  81. "script": {
  82. "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
  83. }
  84. }
  85. },
  86. "properties": {
  87. "timestamp": {"type": "date"}
  88. }
  89. }
  90. }
  91. ----
  92. The `runtime` section can be any of these data types:
  93. // tag::runtime-data-types[]
  94. * `boolean`
  95. * `date`
  96. * `double`
  97. * `geo_point`
  98. * `ip`
  99. * `keyword`
  100. * `long`
  101. // end::runtime-data-types[]
  102. Runtime fields with a `type` of `date` can accept the
  103. <<mapping-date-format,`format`>> parameter exactly as the `date` field type.
  104. If <<dynamic-field-mapping,dynamic field mapping>> is enabled where the
  105. `dynamic` parameter is set to `runtime`, new fields are automatically added to
  106. the index mapping as runtime fields:
  107. [source,console]
  108. ----
  109. PUT my-index
  110. {
  111. "mappings": {
  112. "dynamic": "runtime",
  113. "properties": {
  114. "timestamp": {
  115. "type": "date"
  116. }
  117. }
  118. }
  119. }
  120. ----
  121. [[runtime-updating-scripts]]
  122. .Updating runtime scripts
  123. ****
  124. Updating a script while a dependent query is running can return
  125. inconsistent results. Each shard might have access to different versions of the
  126. script, depending on when the mapping change takes effect.
  127. Existing queries or visualizations in {kib} that rely on runtime fields can
  128. fail if you change the field type. For example, a bar chart visualization
  129. that uses a runtime field of type `ip` will fail if the type is changed
  130. to `boolean`.
  131. ****
  132. [[runtime-search-request]]
  133. === Define runtime fields in a search request
  134. You can specify a `runtime_mappings` section in a search request to create
  135. runtime fields that exist only as part of the query. You specify a script
  136. as part of the `runtime_mappings` section, just as you would if adding a
  137. runtime field to the mappings.
  138. Fields defined in the search request take precedence over fields defined with
  139. the same name in the index mappings. This flexibility allows you to shadow
  140. existing fields and calculate a different value in the search request, without
  141. modifying the field itself. If you made a mistake in your index mapping, you
  142. can use runtime fields to calculate values that override values in the mapping
  143. during the search request.
  144. In the following request, the values for the `day_of_week` field are calculated
  145. dynamically, and only within the context of this search request:
  146. [source,console]
  147. ----
  148. GET my-index/_search
  149. {
  150. "runtime_mappings": {
  151. "day_of_week": {
  152. "type": "keyword",
  153. "script": {
  154. "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
  155. }
  156. }
  157. },
  158. "aggs": {
  159. "day_of_week": {
  160. "terms": {
  161. "field": "day_of_week"
  162. }
  163. }
  164. }
  165. }
  166. ----
  167. //TEST[continued]
  168. Defining a runtime field in a search request uses the same format as defining
  169. a runtime field in the index mapping. That consistency means you can promote a
  170. runtime field from a search request to the index mapping by moving the field
  171. definition from `runtime_mappings` in the search request to the `runtime`
  172. section of the index mapping.
  173. [[runtime-fields-scriptless]]
  174. ==== Define runtime fields without a script
  175. You can define a runtime field in the mapping definition without a
  176. script. At query time, {es} looks in `_source` for a field with the same name
  177. and returns a value if one exists. If a field with the same name doesn’t
  178. exist, the response doesn't include any values for that runtime field.
  179. [source,console]
  180. ----
  181. PUT my-index/
  182. {
  183. "mappings": {
  184. "runtime": {
  185. "model_number": {
  186. "type": "keyword"
  187. }
  188. }
  189. }
  190. }
  191. ----
  192. [[runtime-override-values]]
  193. === Override field values at query time
  194. If you create a runtime field with the same name as a field that
  195. already exists in the mapping, the runtime field shadows the mapped field. At
  196. query time, {es} evaluates the runtime field, calculates a value based on the
  197. script, and returns the value as part of the query. Because the runtime field
  198. shadows the mapped field, you can override the value returned in search without
  199. modifying the mapped field.
  200. For example, let's say you indexed the following documents into `my-index`:
  201. [source,console]
  202. ----
  203. POST my-index/_bulk?refresh=true
  204. {"index":{}}
  205. {"timestamp":1516729294000,"model_number":"QVKC92Q","measures":{"voltage":5.2}}
  206. {"index":{}}
  207. {"timestamp":1516642894000,"model_number":"QVKC92Q","measures":{"voltage":5.8}}
  208. {"index":{}}
  209. {"timestamp":1516556494000,"model_number":"QVKC92Q","measures":{"voltage":5.1}}
  210. {"index":{}}
  211. {"timestamp":1516470094000,"model_number":"QVKC92Q","measures":{"voltage":5.6}}
  212. {"index":{}}
  213. {"timestamp":1516383694000,"model_number":"HG537PU","measures":{"voltage":4.2}}
  214. {"index":{}}
  215. {"timestamp":1516297294000,"model_number":"HG537PU","measures":{"voltage":4.0}}
  216. ----
  217. You later realize that the `HG537PU` sensors aren't reporting their true
  218. voltage. The indexed values are supposed to be 1.7 times higher than
  219. the reported values! Instead of reindexing your data, you can define a script in
  220. the `runtime_mappings` section of the `_search` request to shadow the `voltage`
  221. field and calculate a new value at query time.
  222. If you search for documents where the model number matches `HG537PU`:
  223. [source,console]
  224. ----
  225. GET my-index/_search
  226. {
  227. "query": {
  228. "match": {
  229. "model_number": "HG537PU"
  230. }
  231. }
  232. }
  233. ----
  234. //TEST[continued]
  235. The response includes indexed values for documents matching model number
  236. `HG537PU`:
  237. [source,console-result]
  238. ----
  239. {
  240. ...
  241. "hits" : {
  242. "total" : {
  243. "value" : 2,
  244. "relation" : "eq"
  245. },
  246. "max_score" : 1.0296195,
  247. "hits" : [
  248. {
  249. "_index" : "my-index",
  250. "_id" : "F1BeSXYBg_szTodcYCmk",
  251. "_score" : 1.0296195,
  252. "_source" : {
  253. "timestamp" : 1516383694000,
  254. "model_number" : "HG537PU",
  255. "measures" : {
  256. "voltage" : 4.2
  257. }
  258. }
  259. },
  260. {
  261. "_index" : "my-index",
  262. "_id" : "l02aSXYBkpNf6QRDO62Q",
  263. "_score" : 1.0296195,
  264. "_source" : {
  265. "timestamp" : 1516297294000,
  266. "model_number" : "HG537PU",
  267. "measures" : {
  268. "voltage" : 4.0
  269. }
  270. }
  271. }
  272. ]
  273. }
  274. }
  275. ----
  276. // TESTRESPONSE[s/\.\.\./"took" : $body.took,"timed_out" : $body.timed_out,"_shards" : $body._shards,/]
  277. // TESTRESPONSE[s/"_id" : "F1BeSXYBg_szTodcYCmk"/"_id": $body.hits.hits.0._id/]
  278. // TESTRESPONSE[s/"_id" : "l02aSXYBkpNf6QRDO62Q"/"_id": $body.hits.hits.1._id/]
  279. The following request defines a runtime field where the script evaluates the
  280. `model_number` field where the value is `HG537PU`. For each match, the script
  281. multiplies the value for the `voltage` field by `1.7`.
  282. Using the <<search-fields,`fields`>> parameter on the `_search` API, you can
  283. retrieve the value that the script calculates for the `measures.voltage` field
  284. for documents matching the search request:
  285. [source,console]
  286. ----
  287. POST my-index/_search
  288. {
  289. "runtime_mappings": {
  290. "measures.voltage": {
  291. "type": "double",
  292. "script": {
  293. "source":
  294. """if (doc['model_number.keyword'].value.equals('HG537PU'))
  295. {emit(1.7 * params._source['measures']['voltage']);}
  296. else{emit(params._source['measures']['voltage']);}"""
  297. }
  298. }
  299. },
  300. "query": {
  301. "match": {
  302. "model_number": "HG537PU"
  303. }
  304. },
  305. "fields": ["measures.voltage"]
  306. }
  307. ----
  308. //TEST[continued]
  309. Looking at the response, the calculated values for `measures.voltage` on each
  310. result are `7.14` and `6.8`. That's more like it! The runtime field calculated
  311. this value as part of the search request without modifying the mapped value,
  312. which still returns in the response:
  313. [source,console-result]
  314. ----
  315. {
  316. ...
  317. "hits" : {
  318. "total" : {
  319. "value" : 2,
  320. "relation" : "eq"
  321. },
  322. "max_score" : 1.0296195,
  323. "hits" : [
  324. {
  325. "_index" : "my-index",
  326. "_id" : "F1BeSXYBg_szTodcYCmk",
  327. "_score" : 1.0296195,
  328. "_source" : {
  329. "timestamp" : 1516383694000,
  330. "model_number" : "HG537PU",
  331. "measures" : {
  332. "voltage" : 4.2
  333. }
  334. },
  335. "fields" : {
  336. "measures.voltage" : [
  337. 7.14
  338. ]
  339. }
  340. },
  341. {
  342. "_index" : "my-index",
  343. "_id" : "l02aSXYBkpNf6QRDO62Q",
  344. "_score" : 1.0296195,
  345. "_source" : {
  346. "timestamp" : 1516297294000,
  347. "model_number" : "HG537PU",
  348. "measures" : {
  349. "voltage" : 4.0
  350. }
  351. },
  352. "fields" : {
  353. "measures.voltage" : [
  354. 6.8
  355. ]
  356. }
  357. }
  358. ]
  359. }
  360. }
  361. ----
  362. // TESTRESPONSE[s/\.\.\./"took" : $body.took,"timed_out" : $body.timed_out,"_shards" : $body._shards,/]
  363. // TESTRESPONSE[s/"_id" : "F1BeSXYBg_szTodcYCmk"/"_id": $body.hits.hits.0._id/]
  364. // TESTRESPONSE[s/"_id" : "l02aSXYBkpNf6QRDO62Q"/"_id": $body.hits.hits.1._id/]
  365. [[runtime-retrieving-fields]]
  366. === Retrieve a runtime field
  367. Use the <<search-fields,`fields`>> parameter on the `_search` API to retrieve
  368. the values of runtime fields. Runtime fields won't display in `_source`, but
  369. the `fields` API works for all fields, even those that were not sent as part of
  370. the original `_source`.
  371. [discrete]
  372. [[runtime-define-field-dayofweek]]
  373. ==== Define a runtime field to calculate the day of week
  374. For example, the following request adds a runtime field called `day_of_week`.
  375. The runtime field includes a script that calculates the day of the week based
  376. on the value of the `@timestamp` field. We'll include `"dynamic":"runtime"` in
  377. the request so that new fields are added to the mapping as runtime fields.
  378. [source,console]
  379. ----
  380. PUT my-index/
  381. {
  382. "mappings": {
  383. "dynamic": "runtime",
  384. "runtime": {
  385. "day_of_week": {
  386. "type": "keyword",
  387. "script": {
  388. "source": "emit(doc['@timestamp'].value.dayOfWeekEnum.getDisplayName(TextStyle.FULL, Locale.ROOT))"
  389. }
  390. }
  391. },
  392. "properties": {
  393. "timestamp": {"type": "date"}
  394. }
  395. }
  396. }
  397. ----
  398. [discrete]
  399. [[runtime-ingest-data]]
  400. ==== Ingest some data
  401. Let's ingest some sample data, which will result in two indexed fields:
  402. `@timestamp` and `message`.
  403. [source,console]
  404. ----
  405. POST /my-index/_bulk?refresh
  406. { "index": {}}
  407. { "@timestamp": "2020-06-21T15:00:01-05:00", "message" : "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"}
  408. { "index": {}}
  409. { "@timestamp": "2020-06-21T15:00:01-05:00", "message" : "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"}
  410. { "index": {}}
  411. { "@timestamp": "2020-04-30T14:30:17-05:00", "message" : "40.135.0.0 - - [2020-04-30T14:30:17-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  412. { "index": {}}
  413. { "@timestamp": "2020-04-30T14:30:53-05:00", "message" : "232.0.0.0 - - [2020-04-30T14:30:53-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  414. { "index": {}}
  415. { "@timestamp": "2020-04-30T14:31:12-05:00", "message" : "26.1.0.0 - - [2020-04-30T14:31:12-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  416. { "index": {}}
  417. { "@timestamp": "2020-04-30T14:31:19-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:19-05:00] \"GET /french/splash_inet.html HTTP/1.0\" 200 3781"}
  418. { "index": {}}
  419. { "@timestamp": "2020-04-30T14:31:27-05:00", "message" : "252.0.0.0 - - [2020-04-30T14:31:27-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  420. { "index": {}}
  421. { "@timestamp": "2020-04-30T14:31:29-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:29-05:00] \"GET /images/hm_brdl.gif HTTP/1.0\" 304 0"}
  422. { "index": {}}
  423. { "@timestamp": "2020-04-30T14:31:29-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:29-05:00] \"GET /images/hm_arw.gif HTTP/1.0\" 304 0"}
  424. { "index": {}}
  425. { "@timestamp": "2020-04-30T14:31:32-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:32-05:00] \"GET /images/nav_bg_top.gif HTTP/1.0\" 200 929"}
  426. { "index": {}}
  427. { "@timestamp": "2020-04-30T14:31:43-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:43-05:00] \"GET /french/images/nav_venue_off.gif HTTP/1.0\" 304 0"}
  428. ----
  429. //TEST[continued]
  430. [discrete]
  431. [[runtime-search-dayofweek]]
  432. ==== Search for the calculated day of week
  433. The following request uses the search API to retrieve the `day_of_week` field
  434. that the original request defined as a runtime field in the mapping. The value
  435. for this field is calculated dynamically at query time without reindexing
  436. documents or indexing the `day_of_week` field. This flexibility allows you to
  437. modify the mapping without changing any field values.
  438. [source,console]
  439. ----
  440. GET my-index/_search
  441. {
  442. "fields": [
  443. "@timestamp",
  444. "day_of_week"
  445. ],
  446. "_source": false
  447. }
  448. ----
  449. // TEST[continued]
  450. The previous request returns the `day_of_week` field for all matching documents.
  451. We can define another runtime field called `client_ip` that also operates on
  452. the `message` field and will further refine the query:
  453. [source,console]
  454. ----
  455. PUT /my-index/_mapping
  456. {
  457. "runtime": {
  458. "client_ip": {
  459. "type": "ip",
  460. "script" : {
  461. "source" : "String m = doc[\"message\"].value; int end = m.indexOf(\" \"); emit(m.substring(0, end));"
  462. }
  463. }
  464. }
  465. }
  466. ----
  467. //TEST[continued]
  468. Run another query, but search for a specific IP address using the `client_ip`
  469. runtime field:
  470. [source,console]
  471. ----
  472. GET my-index/_search
  473. {
  474. "size": 1,
  475. "query": {
  476. "match": {
  477. "client_ip": "211.11.9.0"
  478. }
  479. },
  480. "fields" : ["*"]
  481. }
  482. ----
  483. //TEST[continued]
  484. This time, the response includes only two hits. The value for `day_of_week`
  485. (`Sunday`) was calculated at query time using the runtime script defined in the
  486. mapping, and the result includes only documents matching the `211.11.9.0` IP
  487. address.
  488. [source,console-result]
  489. ----
  490. {
  491. ...
  492. "hits" : {
  493. "total" : {
  494. "value" : 2,
  495. "relation" : "eq"
  496. },
  497. "max_score" : 1.0,
  498. "hits" : [
  499. {
  500. "_index" : "my-index",
  501. "_id" : "oWs5KXYB-XyJbifr9mrz",
  502. "_score" : 1.0,
  503. "_source" : {
  504. "@timestamp" : "2020-06-21T15:00:01-05:00",
  505. "message" : "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"
  506. },
  507. "fields" : {
  508. "@timestamp" : [
  509. "2020-06-21T20:00:01.000Z"
  510. ],
  511. "client_ip" : [
  512. "211.11.9.0"
  513. ],
  514. "message" : [
  515. "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"
  516. ],
  517. "day_of_week" : [
  518. "Sunday"
  519. ]
  520. }
  521. }
  522. ]
  523. }
  524. }
  525. ----
  526. // TESTRESPONSE[s/\.\.\./"took" : $body.took,"timed_out" : $body.timed_out,"_shards" : $body._shards,/]
  527. // TESTRESPONSE[s/"_id" : "oWs5KXYB-XyJbifr9mrz"/"_id": $body.hits.hits.0._id/]
  528. // TESTRESPONSE[s/"day_of_week" : \[\n\s+"Sunday"\n\s\]/"day_of_week": $body.hits.hits.0.fields.day_of_week/]
  529. [[runtime-examples]]
  530. === Explore your data with runtime fields
  531. Consider a large set of log data that you want to extract fields from.
  532. Indexing the data is time consuming and uses a lot of disk space, and you just
  533. want to explore the data structure without committing to a schema up front.
  534. You know that your log data contains specific fields that you want to extract.
  535. In this case, we want to focus on the `@timestamp` and `message` fields. By
  536. using runtime fields, you can define scripts to calculate values at search
  537. time for these fields.
  538. [[runtime-examples-define-fields]]
  539. ==== Define indexed fields as a starting point
  540. You can start with a simple example by adding the `@timestamp` and `message`
  541. fields to the `my-index` mapping as indexed fields. To remain flexible, use
  542. `wildcard` as the field type for `message`:
  543. [source,console]
  544. ----
  545. PUT /my-index/
  546. {
  547. "mappings": {
  548. "properties": {
  549. "@timestamp": {
  550. "format": "strict_date_optional_time||epoch_second",
  551. "type": "date"
  552. },
  553. "message": {
  554. "type": "wildcard"
  555. }
  556. }
  557. }
  558. }
  559. ----
  560. [[runtime-examples-ingest-data]]
  561. ==== Ingest some data
  562. After mapping the fields you want to retrieve, index a few records from
  563. your log data into {es}. The following request uses the <<docs-bulk,bulk API>>
  564. to index raw log data into `my-index`. Instead of indexing all of your log
  565. data, you can use a small sample to experiment with runtime fields.
  566. [source,console]
  567. ----
  568. POST /my-index/_bulk?refresh
  569. { "index": {}}
  570. { "@timestamp": "2020-06-21T15:00:01-05:00", "message" : "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"}
  571. { "index": {}}
  572. { "@timestamp": "2020-06-21T15:00:01-05:00", "message" : "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"}
  573. { "index": {}}
  574. { "@timestamp": "2020-04-30T14:30:17-05:00", "message" : "40.135.0.0 - - [2020-04-30T14:30:17-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  575. { "index": {}}
  576. { "@timestamp": "2020-04-30T14:30:53-05:00", "message" : "232.0.0.0 - - [2020-04-30T14:30:53-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  577. { "index": {}}
  578. { "@timestamp": "2020-04-30T14:31:12-05:00", "message" : "26.1.0.0 - - [2020-04-30T14:31:12-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  579. { "index": {}}
  580. { "@timestamp": "2020-04-30T14:31:19-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:19-05:00] \"GET /french/splash_inet.html HTTP/1.0\" 200 3781"}
  581. { "index": {}}
  582. { "@timestamp": "2020-04-30T14:31:27-05:00", "message" : "252.0.0.0 - - [2020-04-30T14:31:27-05:00] \"GET /images/hm_bg.jpg HTTP/1.0\" 200 24736"}
  583. { "index": {}}
  584. { "@timestamp": "2020-04-30T14:31:29-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:29-05:00] \"GET /images/hm_brdl.gif HTTP/1.0\" 304 0"}
  585. { "index": {}}
  586. { "@timestamp": "2020-04-30T14:31:29-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:29-05:00] \"GET /images/hm_arw.gif HTTP/1.0\" 304 0"}
  587. { "index": {}}
  588. { "@timestamp": "2020-04-30T14:31:32-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:32-05:00] \"GET /images/nav_bg_top.gif HTTP/1.0\" 200 929"}
  589. { "index": {}}
  590. { "@timestamp": "2020-04-30T14:31:43-05:00", "message" : "247.37.0.0 - - [2020-04-30T14:31:43-05:00] \"GET /french/images/nav_venue_off.gif HTTP/1.0\" 304 0"}
  591. ----
  592. // TEST[continued]
  593. At this point, you can view how {es} stores your raw data.
  594. [source,console]
  595. ----
  596. GET /my-index
  597. ----
  598. // TEST[continued]
  599. The mapping contains two fields: `@timestamp` and `message`.
  600. [source,console-result]
  601. ----
  602. {
  603. "my-index" : {
  604. "aliases" : { },
  605. "mappings" : {
  606. "properties" : {
  607. "@timestamp" : {
  608. "type" : "date",
  609. "format" : "strict_date_optional_time||epoch_second"
  610. },
  611. "message" : {
  612. "type" : "wildcard"
  613. }
  614. }
  615. },
  616. ...
  617. }
  618. }
  619. ----
  620. // TESTRESPONSE[s/\.\.\./"settings": $body.my-index.settings/]
  621. [[runtime-examples-runtime-field]]
  622. ==== Define a runtime field to search by IP address
  623. If you want to retrieve results that include `clientip`, you can add that field
  624. as a runtime field in the mapping. The runtime script operates on the `clientip`
  625. field at runtime to calculate values for that field.
  626. [source,console]
  627. ----
  628. PUT /my-index/_mapping
  629. {
  630. "runtime": {
  631. "clientip": {
  632. "type": "ip",
  633. "script" : {
  634. "source" : "String m = doc[\"message\"].value; int end = m.indexOf(\" \"); emit(m.substring(0, end));"
  635. }
  636. }
  637. }
  638. }
  639. ----
  640. // TEST[continued]
  641. Using the `clientip` runtime field, you can define a simple query to run a
  642. search for a specific IP address and return all related fields.
  643. [source,console]
  644. ----
  645. GET my-index/_search
  646. {
  647. "size": 1,
  648. "query": {
  649. "match": {
  650. "clientip": "211.11.9.0"
  651. }
  652. },
  653. "fields" : ["*"]
  654. }
  655. ----
  656. // TEST[continued]
  657. The API returns the following result. Without building your data structure in
  658. advance, you can search and explore your data in meaningful ways to experiment
  659. and determine which fields to index.
  660. [source,console-result]
  661. ----
  662. {
  663. ...
  664. "hits" : {
  665. "total" : {
  666. "value" : 2,
  667. "relation" : "eq"
  668. },
  669. "max_score" : 1.0,
  670. "hits" : [
  671. {
  672. "_index" : "my-index",
  673. "_id" : "oWs5KXYB-XyJbifr9mrz",
  674. "_score" : 1.0,
  675. "_source" : {
  676. "@timestamp" : "2020-06-21T15:00:01-05:00",
  677. "message" : "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"
  678. },
  679. "fields" : {
  680. "@timestamp" : [
  681. "2020-06-21T20:00:01.000Z"
  682. ],
  683. "clientip" : [
  684. "211.11.9.0"
  685. ],
  686. "message" : [
  687. "211.11.9.0 - - [2020-06-21T15:00:01-05:00] \"GET /english/index.html HTTP/1.0\" 304 0"
  688. ]
  689. }
  690. }
  691. ]
  692. }
  693. }
  694. ----
  695. // TESTRESPONSE[s/\.\.\./"took" : $body.took,"timed_out" : $body.timed_out,"_shards" : $body._shards,/]
  696. // TESTRESPONSE[s/"_id" : "oWs5KXYB-XyJbifr9mrz"/"_id": $body.hits.hits.0._id/]