mirror of
https://github.com/elastic/kibana.git
synced 2025-04-23 09:19:04 -04:00
[Data Views] Documentation for create data view REST API (#138068)
* data view rest api request body field documentation * document sub-fields of the api request body * add examples of different ways to create the data view * switch order of 2 examples * Update docs/api/data-views/create.asciidoc * data_view properties documentation * update documentation * fix broken link * Apply suggestions from code review Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> * Update docs/api/data-views/create.asciidoc * Update docs/api/data-views/create.asciidoc Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co> Co-authored-by: Kaarina Tungseth <kaarina.tungseth@elastic.co>
This commit is contained in:
Tim Sullivan
GitHub
parent
247d2fb557
commit
f5133d449c
1 changed files with 181 additions and 34 deletions
|
|
@ -28,9 +28,6 @@ experimental[] Create data views.
|
|||
`override`:: (Optional, boolean) Overrides an existing data view if a
|
||||
data view with the provided title already exists. The default is `false`.
|
||||
|
||||
`refresh_fields`:: (Optional, boolean) Reloads data view fields after
|
||||
the data view is stored. The default is `false`.
|
||||
|
||||
`data_view`:: (Required, object) The data view object. All fields are optional.
|
||||
|
||||
|
||||
|
|
@ -44,60 +41,137 @@ the data view is stored. The default is `false`.
|
|||
[[data-views-api-create-example]]
|
||||
==== Examples
|
||||
|
||||
Create a data view with a custom title:
|
||||
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": "hello"
|
||||
"title": "logstash-*",
|
||||
"name": "My Logstash Data View"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
Customize the creation behavior:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/data_views/data_view
|
||||
{
|
||||
"override": false,
|
||||
"refresh_fields": true,
|
||||
"data_view": {
|
||||
"title": "hello"
|
||||
}
|
||||
}
|
||||
--------------------------------------------------
|
||||
// KIBANA
|
||||
|
||||
At creation, all data view fields are optional:
|
||||
To create custom field formats, use the `data_view.fieldFormats` property:
|
||||
|
||||
[source,sh]
|
||||
--------------------------------------------------
|
||||
$ curl -X POST api/data_views/data_view
|
||||
{
|
||||
"data_view": {
|
||||
"id": "...",
|
||||
"version": "...",
|
||||
"title": "...",
|
||||
"type": "...",
|
||||
"timeFieldName": "...",
|
||||
"sourceFilters": [],
|
||||
"fields": {},
|
||||
"typeMeta": {},
|
||||
"fieldFormats": {},
|
||||
"fieldAttrs": {},
|
||||
"runtimeFieldMap": {}
|
||||
"allowNoIndex": "..."
|
||||
"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:
|
||||
|
||||
The API returns the data view object:
|
||||
[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]
|
||||
--------------------------------------------------
|
||||
|
|
@ -105,3 +179,76 @@ The API returns the data view object:
|
|||
"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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue