[Index Patterns] Runtime fields CRUD REST API (#101164)

Part of index pattern REST API

docs/api/index-patterns.asciidoc

@@ -20,6 +20,12 @@ The following index patterns APIs are available:
     ** <<index-patterns-api-default-set, Set default index pattern API>> to set a default index pattern
 * Fields
     ** <<index-patterns-fields-api-update, Update index pattern field>> to change field metadata, such as `count`, `customLabel` and `format`
+* Runtime fields
+    ** <<index-patterns-runtime-field-api-get, Get runtime field API>> to retrieve a runtime field
+    ** <<index-patterns-runtime-field-api-create, Create runtime field API>> to create a runtime field
+    ** <<index-patterns-runtime-field-api-upsert, Upsert runtime field API>> to create or update a runtime field
+    ** <<index-patterns-runtime-field-api-update, Update runtime field API>> to partially update an existing runtime field
+    ** <<index-patterns-runtime-field-api-delete, Delete runtime field API>> to delete a runtime field
 
 include::index-patterns/get.asciidoc[]
 include::index-patterns/create.asciidoc[]
@@ -28,3 +34,9 @@ include::index-patterns/delete.asciidoc[]
 include::index-patterns/default-get.asciidoc[]
 include::index-patterns/default-set.asciidoc[]
 include::index-patterns/update-fields.asciidoc[]
+include::index-patterns/runtime-fields/get.asciidoc[]
+include::index-patterns/runtime-fields/create.asciidoc[]
+include::index-patterns/runtime-fields/upsert.asciidoc[]
+include::index-patterns/runtime-fields/update.asciidoc[]
+include::index-patterns/runtime-fields/delete.asciidoc[]
+

docs/api/index-patterns/create.asciidoc

@@ -84,6 +84,7 @@ $ curl -X POST api/index_patterns/index_pattern
       "typeMeta": {},
       "fieldFormats": {},
       "fieldAttrs": {},
+      "runtimeFieldMap": {}
       "allowNoIndex": "..."
     }
 }

docs/api/index-patterns/get.asciidoc

@@ -58,6 +58,7 @@ The API returns an index pattern object:
         "typeMeta": {},
         "fieldFormats": {},
         "fieldAttrs": {},
+        "runtimeFieldMap" {},
         "allowNoIndex: "..."
     }
 }

docs/api/index-patterns/runtime-fields/create.asciidoc

@@ -0,0 +1,61 @@
+[[index-patterns-runtime-field-api-create]]
+=== Create runtime field API
+++++
+<titleabbrev>Create runtime field</titleabbrev>
+++++
+
+experimental[] Create a runtime field
+
+[[index-patterns-runtime-field-create-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
+
+`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
+
+[[index-patterns-runtime-field-create-params]]
+==== Path parameters
+
+`space_id`::
+(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
+`index_pattern_id`::
+(Required, string) The ID of the index pattern.
+
+[[index-patterns-runtime-field-create-body]]
+==== Request body
+
+`name`:: (Required, string) The name for a runtime field.
+
+`runtimeField`:: (Required, object) The runtime field definition object.
+
+
+[[index-patterns-runtime-field-create-example]]
+==== Examples
+
+Create a runtime field on an index pattern:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/index_patterns/index_pattern/<index_pattern_id>/runtime_field
+{
+  "name": "runtimeFoo",
+  "runtimeField": {
+     "type": "long",
+     "script": {
+        "source": "emit(doc["foo"].value)"
+      }
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+The API returns created runtime field object and update index pattern object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {...},
+    "field": {...}
+}
+--------------------------------------------------

docs/api/index-patterns/runtime-fields/delete.asciidoc

@@ -0,0 +1,37 @@
+[[index-patterns-runtime-field-api-delete]]
+=== Delete runtime field API
+++++
+<titleabbrev>Delete runtime field</titleabbrev>
+++++
+
+experimental[] Delete a runtime field from an index pattern.
+
+[[index-patterns-runtime-field-api-delete-request]]
+==== Request
+
+`DELETE <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
+
+`DELETE <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
+
+[[index-patterns-runtime-field-api-delete-path-params]]
+==== Path parameters
+
+`space_id`::
+(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
+`index_pattern_id`::
+(Required, string) The ID of the index pattern your want to delete a runtime field from.
+
+`name`::
+(Required, string) The name of the runtime field you want to delete.
+
+
+==== Example
+
+Delete a runtime field from an index pattern:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X DELETE api/index_patterns/index_pattern/<my-pattern>/runtime_field/<runtime-field-name>
+--------------------------------------------------
+// KIBANA

docs/api/index-patterns/runtime-fields/get.asciidoc

@@ -0,0 +1,52 @@
+[[index-patterns-runtime-field-api-get]]
+=== Get runtime field API
+++++
+<titleabbrev>Get runtime field</titleabbrev>
+++++
+
+experimental[] Get a runtime field
+
+[[index-patterns-runtime-field-get-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
+
+`GET <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
+
+[[index-patterns-runtime-field-get-params]]
+==== Path parameters
+
+`space_id`::
+(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
+`index_pattern_id`::
+(Required, string) The ID of the index pattern.
+
+`name`::
+(Required, string) The name of the runtime field you want to retrieve.
+
+
+[[index-patterns-runtime-field-get-example]]
+==== Example
+
+Retrieve a runtime field named `foo` of index pattern with the `my-pattern` ID:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/index_patterns/index_pattern/my-pattern/runtime_field/foo
+--------------------------------------------------
+// KIBANA
+
+The API returns a runtime `field` object, and a `runtimeField` definition object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "field": {
+        ...
+    },
+    "runtimeField": {
+        ...
+    }
+}
+--------------------------------------------------

docs/api/index-patterns/runtime-fields/update.asciidoc

@@ -0,0 +1,66 @@
+[[index-patterns-runtime-field-api-update]]
+=== Update runtime field API
+++++
+<titleabbrev>Update runtime field</titleabbrev>
+++++
+
+experimental[] Update an existing runtime field
+
+[[index-patterns-runtime-field-update-request]]
+==== Request
+
+`POST <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
+
+`POST <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<name>`
+
+[[index-patterns-runtime-field-update-params]]
+==== Path parameters
+
+`space_id`::
+(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
+`index_pattern_id`::
+(Required, string) The ID of the index pattern.
+
+`name`::
+(Required, string) The name of the runtime field you want to update.
+
+[[index-patterns-runtime-field-update-body]]
+==== Request body
+
+`runtimeField`:: (Required, object) The runtime field definition object.
+
+You can update following fields:
+
+* `type`
+* `script`
+
+
+
+[[index-patterns-runtime-field-update-example]]
+==== Examples
+
+Update an existing runtime field on an index pattern:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X POST api/index_patterns/index_pattern/<index_pattern_id>/runtime_field/<runtime_field_name>
+{
+  "runtimeField": {
+     "script": {
+        "source": "emit(doc["bar"].value)"
+      }
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+The API returns updated runtime field object and updated index pattern object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {...},
+    "field": {...}
+}
+--------------------------------------------------

docs/api/index-patterns/runtime-fields/upsert.asciidoc

@@ -0,0 +1,61 @@
+[[index-patterns-runtime-field-api-upsert]]
+=== Upsert runtime field API
+++++
+<titleabbrev>Upsert runtime field</titleabbrev>
+++++
+
+experimental[] Create or update an existing runtime field
+
+[[index-patterns-runtime-field-upsert-request]]
+==== Request
+
+`PUT <kibana host>:<port>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
+
+`PUT <kibana host>:<port>/s/<space_id>/api/index_patterns/index_pattern/<index_pattern_id>/runtime_field`
+
+[[index-patterns-runtime-field-upsert-params]]
+==== Path parameters
+
+`space_id`::
+(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
+
+`index_pattern_id`::
+(Required, string) The ID of the index pattern.
+
+[[index-patterns-runtime-field-upsert-body]]
+==== Request body
+
+`name`:: (Required, string) The name for a new runtime field or a name of an existing runtime field.
+
+`runtimeField`:: (Required, object) The runtime field definition object.
+
+
+[[index-patterns-runtime-field-upsert-example]]
+==== Examples
+
+Create or update an existing runtime field on an index pattern:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X PUT api/index_patterns/index_pattern/<index_pattern_id>/runtime_field
+{
+  "name": "runtimeFoo",
+  "runtimeField": {
+     "type": "long",
+     "script": {
+        "source": "emit(doc["foo"].value)"
+      }
+  }
+}
+--------------------------------------------------
+// KIBANA
+
+The API returns created or updated runtime field object and updated index pattern object:
+
+[source,sh]
+--------------------------------------------------
+{
+    "index_pattern": {...},
+    "field": {...}
+}
+--------------------------------------------------

docs/api/index-patterns/update.asciidoc

@@ -93,7 +93,8 @@ $ curl -X POST api/saved_objects/index-pattern/my-pattern
     "fieldFormats": {},
     "type": "...",
     "typeMeta": {},
-    "fields": {}
+    "fields": {},
+    "runtimeFieldMap": {}
   }
 }
 --------------------------------------------------

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.getruntimefield.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [IndexPattern](./kibana-plugin-plugins-data-public.indexpattern.md) &gt; [getRuntimeField](./kibana-plugin-plugins-data-public.indexpattern.getruntimefield.md)
+
+## IndexPattern.getRuntimeField() method
+
+Returns runtime field if exists
+
+<b>Signature:</b>
+
+```typescript
+getRuntimeField(name: string): RuntimeField | null;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  name | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`RuntimeField | null`
+

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.hasruntimefield.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+[Home](./index.md) &gt; [kibana-plugin-plugins-data-public](./kibana-plugin-plugins-data-public.md) &gt; [IndexPattern](./kibana-plugin-plugins-data-public.indexpattern.md) &gt; [hasRuntimeField](./kibana-plugin-plugins-data-public.indexpattern.hasruntimefield.md)
+
+## IndexPattern.hasRuntimeField() method
+
+Checks if runtime field exists
+
+<b>Signature:</b>
+
+```typescript
+hasRuntimeField(name: string): boolean;
+```
+
+## Parameters
+
+|  Parameter | Type | Description |
+|  --- | --- | --- |
+|  name | <code>string</code> |  |
+
+<b>Returns:</b>
+
+`boolean`
+

docs/development/plugins/data/public/kibana-plugin-plugins-data-public.indexpattern.md

@@ -54,13 +54,16 @@ export declare class IndexPattern implements IIndexPattern
 |  [getFormatterForField(field)](./kibana-plugin-plugins-data-public.indexpattern.getformatterforfield.md) |  | Provide a field, get its formatter |
 |  [getFormatterForFieldNoDefault(fieldname)](./kibana-plugin-plugins-data-public.indexpattern.getformatterforfieldnodefault.md) |  | Get formatter for a given field name. Return undefined if none exists |
 |  [getNonScriptedFields()](./kibana-plugin-plugins-data-public.indexpattern.getnonscriptedfields.md) |  |  |
+|  [getRuntimeField(name)](./kibana-plugin-plugins-data-public.indexpattern.getruntimefield.md) |  | Returns runtime field if exists |
 |  [getScriptedFields()](./kibana-plugin-plugins-data-public.indexpattern.getscriptedfields.md) |  |  |
 |  [getSourceFiltering()](./kibana-plugin-plugins-data-public.indexpattern.getsourcefiltering.md) |  | Get the source filtering configuration for that index. |
 |  [getTimeField()](./kibana-plugin-plugins-data-public.indexpattern.gettimefield.md) |  |  |
+|  [hasRuntimeField(name)](./kibana-plugin-plugins-data-public.indexpattern.hasruntimefield.md) |  | Checks if runtime field exists |
 |  [isTimeBased()](./kibana-plugin-plugins-data-public.indexpattern.istimebased.md) |  |  |
 |  [isTimeNanosBased()](./kibana-plugin-plugins-data-public.indexpattern.istimenanosbased.md) |  |  |
-|  [removeRuntimeField(name)](./kibana-plugin-plugins-data-public.indexpattern.removeruntimefield.md) |  | Remove a runtime field - removed from mapped field or removed unmapped field as appropriate |
+|  [removeRuntimeField(name)](./kibana-plugin-plugins-data-public.indexpattern.removeruntimefield.md) |  | Remove a runtime field - removed from mapped field or removed unmapped field as appropriate. Doesn't clear associated field attributes. |
 |  [removeScriptedField(fieldName)](./kibana-plugin-plugins-data-public.indexpattern.removescriptedfield.md) |  | Remove scripted field from field list |
+|  [replaceAllRuntimeFields(newFields)](./kibana-plugin-plugins-data-public.indexpattern.replaceallruntimefields.md) |  | Replaces all existing runtime fields with new fields |
 |  [setFieldAttrs(fieldName, attrName, value)](./kibana-plugin-plugins-data-public.indexpattern.setfieldattrs.md) |  |  |
 |  [setFieldCount(fieldName, count)](./kibana-plugin-plugins-data-public.indexpattern.setfieldcount.md) |  |  |
 |  [setFieldCustomLabel(fieldName, customLabel)](./kibana-plugin-plugins-data-public.indexpattern.setfieldcustomlabel.md) |  |  |