runtime.asciidoc 25 KB

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