kibana/docs/api/data-views/create.asciidoc

[[data-views-api-create]]
=== Create data view API
++++
<titleabbrev>Create data view</titleabbrev>
++++

experimental[] Create data views.

[NOTE]
====
For the most up-to-date API details, refer to the
{kib-repo}/tree/{branch}/src/plugins/data_views/docs/openapi[open API specification].
====

[[data-views-api-create-request]]
==== Request

`POST <kibana host>:<port>/api/data_views/data_view`

`POST <kibana host>:<port>/s/<space_id>/api/data_views/data_view`


[[data-views-api-create-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.


[[data-views-api-create-body-params]]
==== Request body

`override`:: (Optional, boolean) Overrides an existing data view if a
data view with the provided title already exists. The default is `false`.

`data_view`:: (Required, object) The data view object. All fields are optional.


[[data-views-api-create-request-codes]]
==== Response code

`200`::
    Indicates a successful call.


[[data-views-api-create-example]]
==== Examples

To explore the data in the `logstash-*` indices, create a {data-source}:

[source,sh]
--------------------------------------------------
$ curl -X POST api/data_views/data_view
{
  "data_view": {
     "title": "logstash-*",
     "name": "My Logstash Data View"
  }
}
--------------------------------------------------
// KIBANA

To create custom field formats, use the `data_view.fieldFormats` property:

[source,sh]
--------------------------------------------------
$ curl -X POST api/data_views/data_view
{
  "data_view": {
    "title": "logstash-*",
    "name": "My Logstash data view 2",
    "fieldFormats": {
      "event_time": {
        "id": "date_nanos"
      },
      "machine.ram": {
        "id": "number",
        "params": {
          "pattern": "0,0.[000] b"
        }
      }
    }
  }
}
--------------------------------------------------
// KIBANA

To create custom labels, use the `data_view.fieldAttrs` property:

[source,sh]
--------------------------------------------------
$ curl -X POST api/data_views/data_view
{
  "data_view": {
    "title": "logstash-*",
    "name": "My Logstash data view 3",
    "fieldAttrs": {
      "utc_time": {
        "customLabel": "Time (UTC)"
      }
    }
  }
}
--------------------------------------------------
// KIBANA

To create a {data-source} with {ref}/runtime-search-request.html[runtime fields], use the `data_view.runtimeFieldMap` property:

[source,sh]
--------------------------------------------------
$ curl -X POST api/data_views/data_view
{
  "data_view": {
    "title": "logstash-*",
    "name": "My Logstash data view 3",
    "runtimeFieldMap": {
      "runtime_shape_name": {
        "type": "keyword",
        "script": {
          "source": "emit(doc['shape_name'].value)"
        }
      }
    }
  }
}
--------------------------------------------------
// KIBANA

To create {data-sources} based on {ref}/xpack-rollup.html[rollup indices], use the `data_view.type` and `data_view.typeMeta` properties :

[source,sh]
--------------------------------------------------
$ curl -X POST api/data_views/data_view
{
  "data_view": {
    "title": "logstash-*",
    "name": "My Logstash rollup data view",
    "type": "rollup",
    "typeMeta": {
      "params": {
        "rollup_index": "rollup_logstash"
      },
      "aggs": {
        "terms": {
          "geo.dest": { "agg": "terms" },
          "extension.keyword": { "agg": "terms" },
          "geo.src": { "agg": "terms" },
          "machine.os.keyword": { "agg": "terms" }
        },
        "date_histogram": {
          "@timestamp": {
            "agg": "date_histogram",
            "fixed_interval": "20m",
            "delay": "10m",
            "time_zone": "UTC"
          }
        },
        "avg": {
          "memory": { "agg": "avg" },
          "bytes": { "agg": "avg" }
        },
        "max": { "memory": { "agg": "max" } },
        "min": { "memory": { "agg": "min" } },
        "sum": { "memory": { "agg": "sum" } },
        "value_count": { "memory": { "agg": "value_count" } },
        "histogram": {
          "machine.ram": {
            "agg": "histogram",
            "interval": 5
          }
        }
      }
    }
  }
}
--------------------------------------------------
// KIBANA

The API returns the {data-source} object:

[source,sh]
--------------------------------------------------
{
    "data_view": {...}
}
--------------------------------------------------


[[data-views-api-properties]]

==== Properties of the `data_view` object:

`title`::
(Optional, string) Comma-separated list of data streams, indices, and aliases that you want to search. Supports wildcards
(`*`).

`name`::
(Optional, string) The {data-source} name.

`id`::
(Optional, string) Saved object ID.

`type`::
(Optional, string) When set to `rollup`, identifies the rollup {data-sources}.

`typeMeta`::
(Optional, object) When you use rollup indices, contains the field list for the rollup
{data-source} API endpoints.
+
.Properties of the typeMeta objects:
[%collapsible%open]
=====
`aggs`:::
(Required, object) A map of rollup restrictions by aggregation type and field name.

`params`:::
(Required, object) Properties for retrieving rollup fields.
=====

`timeFieldName`::
(Optional, string) Timestamp field name, which you use for time-based {data-sources}.

`sourceFilters`::
(Optional, string[]) Array of field names you want to filter out in <<discover, **Discover**>>.

`fieldAttrs`::
(Optional, object) Map of field attributes by field name.
+
.Properties of the fieldAttrs[fieldName] objects:
[%collapsible%open]
=====
`customLabel`:::
(Optional, string) Custom label for the field.

`count`:::
(Optional, number) Popularity count for the field.
=====

`runtimeFieldMap`::
(Optional, object) Map of runtime field definitions by field name.
+
.Properties of the runtimeFieldMap[fieldName] objects:
[%collapsible%open]
=====
`type`:::
(Required, string) Mapping type of the runtime field. For more information, check {ref}/mapping-types.html[Field data types].

`script.source`:::
(Required, string) Script of the runtime field.
=====

`fieldFormats`::
(Optional, object) Map of field formats by field name.

`allowNoIndex`::
(Optional, boolean) Allows the {data-source} saved object to exist before the data is available.

`namespaces`::
(Optional, string[]) Array of {kibana-ref}/xpack-spaces.html[space] IDs for sharing the {data-source} between multiple spaces.