---
type: api
title: Upsert a data view
description: Creates the data view with the ID in the path, or replaces its definition if it already exists. Returns `201` when the request creates a data view and `200` when it replaces one. A replacement removes any optional property you omit, such as `time_field`.<br/><br/>[Required authorization] Route required privileges: indexPatterns:manage.
url: https://www.elastic.co/docs/api/doc/kibana/operation/operation-put-data-views-v2-id
resource: https://www.elastic.co/docs/api/doc/kibana/operation/operation-put-data-views-v2-id
products:
  - Kibana
---

# Upsert a data view

Authentication: required

Availability: Planned

- Server: `https://{kibana_url}`

## Paths

- `PUT` `/api/data_views/v2/{id}`
- `PUT` `/s/{space_id}/api/data_views/v2/{id}`

#### Path parameters

- `space_id` (string) — optional
  An identifier for the space. If `space_id` is not provided in the URL, the default space is used. Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- `id` (string · min length: 1 · max length: 1000) — required
  The ID of the data view to create or update.

## Description

Creates the data view with the ID in the path, or replaces its definition if it already exists. Returns `201` when the request creates a data view and `200` when it replaces one. A replacement removes any optional property you omit, such as `time_field`.

## Required privileges

- Privileges: `indexPatterns:manage`

## Header parameters

- `kbn-xsrf` (string) — required
  A required header to protect against CSRF attacks

## Request body

`application/json`

- `allow_hidden_indices` (boolean) — optional
  When `true`, allows the data view to match hidden indices.
- `field_filters` (string[] · max items: 10000) — optional
  Field filters can be used to exclude one or more fields when fetching a document. They may contain wildcards, such as `user*` which filters fields starting with 'user'.
- `field_settings` (map string to anyOf) — optional
  Settings for individual fields, keyed by field name. To change how Kibana displays a field from the backing indices, set its label, description, format, or popularity. To define a runtime field, use the runtime field name and set `type`.
  Map values (union anyOf)
  Any of:
  - **Saved composite runtime field**
    - `fields` (map string to object) — required
      Map values (object)
      - `custom_description` (string · min length: 1) — optional
        Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
      - `custom_label` (string · min length: 1) — optional
        Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
      - `format` (union anyOf) — optional
        Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
        - **Boolean field format**
          Formats a field into a true/false value.
          - `type` (enum) — required
            Values: `boolean`
        - **Bytes field format**
          Formats a field into a bytes value following the numeral.js format pattern. The default pattern is defined by the format:bytes:defaultPattern advanced setting.
          - `params` (object) — optional
            - `pattern` (string) — optional
              Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
          - `type` (enum) — required
            Values: `bytes`
        - **Color field format**
          Formats a field into a color value.
          - `params` (union oneOf) — required
            - **field_type: string** (`field_type: string`)
              - `field_type` (enum) — required
                Values: `string`
              - `colors` (object[]) — required
                - `background` (string) — required
                  The background color to use for the field.
                - `regex` (string) — required
                  When the field type is a string, this regex is used to determine the color.
                - `text` (string) — required
                  The text color to use for the field.
            - **field_type: number** (`field_type: number`)
              - `field_type` (enum) — required
                Values: `number`
              - `colors` (object[]) — required
                - `background` (string) — required
                  The background color to use for the field.
                - `range` (string) — required
                  When the field type is a number, this range is used to determine the color.
                - `text` (string) — required
                  The text color to use for the field.
              - `pattern` (string) — optional
                Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
            - **field_type: boolean** (`field_type: boolean`)
              - `field_type` (enum) — required
                Values: `boolean`
              - `colors` (object[]) — required
                - `background` (string) — required
                  The background color to use for the field.
                - `boolean` (boolean) — required
                  When the field type is a boolean, this boolean is used to determine the color.
                - `text` (string) — required
                  The text color to use for the field.
          - `type` (enum) — required
            Values: `color`
        - **Currency field format**
          Formats a field into a currency value. The format is determined by the pattern of the format:currency:defaultPattern advanced setting.
          - `type` (enum) — required
            Values: `currency`
        - **Date nanos field format**
          Formats a field into a date nanos value following the defined pattern.
          - `params` (object) — optional
            - `pattern` (string · default: MMM D, YYYY @ HH:mm:ss.SSSSSSSSS) — optional
              Moment.js format pattern. See https://momentjs.com/ to learn more.
          - `type` (enum) — required
            Values: `date_nanos`
        - **Date field format**
          Formats a field into a date value following the defined pattern.
          - `params` (object) — optional
            - `pattern` (string · default: MMM D, YYYY @ HH:mm:ss.SSS) — optional
              Moment.js format pattern. See https://momentjs.com/ to learn more.
          - `type` (enum) — required
            Values: `date`
        - **Duration field format**
          Formats a field into a duration value.
          - `params` (object) — required
            - `include_space_with_suffix` (boolean · default: true) — optional
              When true or not provided, the formatted duration includes a space between the value and suffix. When false, no space is included.
            - `input_format` (enum) — required
              The unit of the field value before formatting.
              Values: `picoseconds`, `nanoseconds`, `microseconds`, `milliseconds`, `seconds`, `minutes`, `hours`, `days`, `weeks`, `months`, `years`
            - `output_format` (enum) — required
              The unit to convert the field value into for display.
              Values: `humanize`, `humanize_precise`, `as_milliseconds`, `as_seconds`, `as_minutes`, `as_hours`, `as_days`, `as_weeks`, `as_months`, `as_years`
            - `output_precision` (number · default: 2) — optional
              The number of decimal places to display in the duration value.
            - `show_suffix` (boolean) — optional
              When true, the formatted duration includes a suffix (such as "seconds", "milliseconds", or "years"). When false or not provided, no suffix is shown.
            - `use_short_suffix` (boolean · default: false) — optional
              When true, the formatted duration uses short suffixes (such as "s", "ms", or "h"). When false or not provided, full suffixes are used.
          - `type` (enum) — required
            Values: `duration`
        - **Geo point field format**
          Formats a field into a geo point value.
          - `params` (object) — optional
            - `transform` (enum) — required
              The transform to apply to the geo point value.
              Values: `lat_lon_string`, `wkt`, `dms`, `mgrs`, `multi`
          - `type` (enum) — required
            Values: `geo_point`
        - **Histogram field format**
          Formats a histogram field into a numeric value following the defined pattern. The default pattern is defined by format:bytes:defaultPattern, format:percent:defaultPattern or format:number:defaultPattern advanced settings depending on the selected format.
          - `params` (object) — required
            - `format` (enum) — required
              Values: `bytes`, `percent`, `number`
            - `pattern` (string) — optional
              Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
          - `type` (enum) — required
            Values: `histogram`
        - **IP field format**
          Formats a field into an IP address.
          - `type` (enum) — required
            Values: `ip`
        - **Number field format**
          Formats a field into a numeric value following the defined pattern. The default pattern is defined by format:number:defaultPattern advanced setting.
          - `params` (object) — optional
            - `pattern` (string) — optional
              Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
          - `type` (enum) — required
            Values: `number`
        - **Percent field format**
          Formats a field into a percentage value following the defined pattern. The default pattern is defined by format:percent:defaultPattern advanced setting.
          - `params` (object) — optional
            - `pattern` (string) — optional
              Numeral.js format pattern. See https://www.elastic.co/docs/explore-analyze/numeral-formatting to learn more.
          - `type` (enum) — required
            Values: `percent`
        - **Relative date field format**
          Formats a field into a relative date value. For example: "1 day ago".
          - `type` (enum) — required
            Values: `relative_date`
        - **Static lookup field format**
          Formats a field into a static value based on the lookup entries or the unknown key value.
          - `params` (object) — required
            - `lookup_entries` (object[]) — required
              The lookup entries to use for the static lookup. The key refers to the field value, and the value refers to the new value to display.
              - `key` (string) — required
              - `value` (string) — required
            - `unknown_key_value` (string) — optional
              The value to display for unknown key values. If not provided, the field value will be displayed.
          - `type` (enum) — required
            Values: `static_lookup`
        - **String field format**
          Formats a field into a string value.
          - `params` (object) — optional
            - `transform` (enum) — optional
              Values: `lower`, `upper`, `title`, `short`, `base64`, `urlparam`
          - `type` (enum) — required
            Values: `string`
        - **Truncate field format**
          Truncates the field value to the specified length. If the field value is longer than the specified length, it will be truncated and the remaining text will be replaced with "...".
          - `params` (object) — optional
            - `field_length` (number) — optional
          - `type` (enum) — required
            Values: `truncate`
        - **URL field format**
          Formats a field into a link, image or audio.
          - `params` (union oneOf) — required
            - **type: a** (`type: a`)
              - `type` (enum) — required
                Displays the field value as a hyperlink.
                Values: `a`
              - `label_template` (string) — optional
                The template to use for the label. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are: `{{value}}`, `{{rawValue}}` and `{{url}}`. For example: "`{{value}}`".
              - `open_link_in_current_tab` (boolean) — optional
                When true, the URL opens in the current tab. When false or not provided, the URL opens in a new tab.
              - `url_template` (string) — optional
                The template to use for the URL. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are: `{{value}}`, `{{rawValue}}` and `{{risonValue}}`. Use `{{risonValue}}` when embedding the field value inside Kibana app URL rison state (for example: query:'`{{risonValue}}`'). For example: "https://example.com/`{{value}}`".
            - **type: img** (`type: img`)
              - `type` (enum) — required
                Displays the field value as an image.
                Values: `img`
              - `height` (number) — optional
                The height of the image. If not provided, the image will be displayed at the original height.
              - `label_template` (string) — optional
                The template to use for the label. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are: `{{value}}`, `{{rawValue}}` and `{{url}}`. For example: "`{{value}}`".
              - `url_template` (string) — optional
                The template to use for the URL. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are: `{{value}}`, `{{rawValue}}` and `{{risonValue}}`. Use `{{risonValue}}` when embedding the field value inside Kibana app URL rison state (for example: query:'`{{risonValue}}`'). For example: "https://example.com/`{{value}}`".
              - `width` (number) — optional
                The width of the image. If not provided, the image will be displayed at the original width.
            - **type: audio** (`type: audio`)
              - `type` (enum) — required
                Displays the field value as an audio player.
                Values: `audio`
              - `label_template` (string) — optional
                The template to use for the label. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are: `{{value}}`, `{{rawValue}}` and `{{url}}`. For example: "`{{value}}`".
              - `url_template` (string) — optional
                The template to use for the URL. The template is a string that contains the field value. The field value is replaced with the template. The available placeholders are: `{{value}}`, `{{rawValue}}` and `{{risonValue}}`. Use `{{risonValue}}` when embedding the field value inside Kibana app URL rison state (for example: query:'`{{risonValue}}`'). For example: "https://example.com/`{{value}}`".
          - `type` (enum) — required
            Values: `url`
        - **Extensible format**
          Fallback for custom formatter IDs only. Known formatter IDs must match their dedicated schema and are validated at runtime.
          - `params` (object) — optional
          - `type` (string) — required
      - `popularity` (number · min: 0) — optional
        Adjust the popularity to make the field appear higher or lower in the fields list. By default, Discover orders fields from most selected to least selected.
      - `type` (enum) — required
        The type of the runtime field (e.g., "keyword", "long", "date").
        Values: `keyword`, `long`, `double`, `date`, `ip`, `boolean`, `geo_point`
    - `script` (string · min length: 1) — optional
      The script that defines the runtime field. This should be a painless script that computes the field value at query time. Runtime fields without a script retrieve values from _source. If the field doesn't exist in _source, a search request returns no value.
    - `type` (enum) — required
      Values: `composite`
  - **Saved runtime field**
    - `custom_description` (string · min length: 1) — optional
      Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
    - `custom_label` (string · min length: 1) — optional
      Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
    - `format` (union anyOf) — optional
      Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
      Same options as `format` in `fields`
    - `popularity` (number · min: 0) — optional
      Adjust the popularity to make the field appear higher or lower in the fields list. By default, Discover orders fields from most selected to least selected.
    - `script` (string · min length: 1) — optional
      The script that defines the runtime field. This should be a painless script that computes the field value at query time. Runtime fields without a script retrieve values from _source. If the field doesn't exist in _source, a search request returns no value.
    - `type` (enum) — required
      The type of the runtime field (e.g., "keyword", "long", "date").
      Values: `keyword`, `long`, `double`, `date`, `ip`, `boolean`, `geo_point`
  - **Field settings**
    Display overrides for a field. These settings can define a custom label, description, format and popularity.
    - `custom_description` (string · min length: 1) — optional
      Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
    - `custom_label` (string · min length: 1) — optional
      Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
    - `format` (union anyOf) — optional
      Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
      Same options as `format` in `fields`
    - `popularity` (number · min: 0) — optional
      Adjust the popularity to make the field appear higher or lower in the fields list. By default, Discover orders fields from most selected to least selected.
- `index_pattern` (string · min length: 1) — required
  The index pattern (Elasticsearch index expression) to use as the data source. Example: "my-index-*".
- `name` (string · min length: 1 · max length: 256) — optional
  The name of the data view. Example: "Sample data view".
- `time_field` (string) — optional
  The name of the time field in the index. Used for time-based filtering. Example: "@timestamp".

## Responses

#### `200`

updated

`application/json`

- `data` (object)
  Defines an stored data source with a mandatory index pattern and optional settings like id, name, show hidden indices and field settings.
  - `allow_hidden_indices` (boolean)
    When `true`, allows the data view to match hidden indices.
  - `field_filters` (string[] · max items: 10000)
    Field filters can be used to exclude one or more fields when fetching a document. They may contain wildcards, such as `user*` which filters fields starting with 'user'.
  - `field_settings` (map string to anyOf)
    Settings for individual fields, keyed by field name. To change how Kibana displays a field from the backing indices, set its label, description, format, or popularity. To define a runtime field, use the runtime field name and set `type`.
    Map values (union anyOf)
    Any of:
    - **Saved composite runtime field**
      - `fields` (map string to object)
        Map values (object)
        - `custom_description` (string · min length: 1)
          Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
        - `custom_label` (string · min length: 1)
          Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
        - `format` (union anyOf)
          Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
          Same options as `format` in `fields`
        - `popularity` (number · min: 0)
          Adjust the popularity to make the field appear higher or lower in the fields list. By default, Discover orders fields from most selected to least selected.
        - `type` (enum)
          The type of the runtime field (e.g., "keyword", "long", "date").
          Values: `keyword`, `long`, `double`, `date`, `ip`, `boolean`, `geo_point`
      - `script` (string · min length: 1)
        The script that defines the runtime field. This should be a painless script that computes the field value at query time. Runtime fields without a script retrieve values from _source. If the field doesn't exist in _source, a search request returns no value.
      - `type` (enum)
        Values: `composite`
    - **Saved runtime field**
      - `custom_description` (string · min length: 1)
        Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
      - `custom_label` (string · min length: 1)
        Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
      - `format` (union anyOf)
        Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
        Same options as `format` in `fields`
      - `popularity` (number · min: 0)
        Adjust the popularity to make the field appear higher or lower in the fields list. By default, Discover orders fields from most selected to least selected.
      - `script` (string · min length: 1)
        The script that defines the runtime field. This should be a painless script that computes the field value at query time. Runtime fields without a script retrieve values from _source. If the field doesn't exist in _source, a search request returns no value.
      - `type` (enum)
        The type of the runtime field (e.g., "keyword", "long", "date").
        Values: `keyword`, `long`, `double`, `date`, `ip`, `boolean`, `geo_point`
    - **Field settings**
      Display overrides for a field. These settings can define a custom label, description, format and popularity.
      - `custom_description` (string · min length: 1)
        Add a description to the field. It's displayed next to the field on the Discover, Lens, and Data View Management pages.
      - `custom_label` (string · min length: 1)
        Create a label to display in place of the field name in Discover, Maps, Lens, Visualize, and TSVB. Useful for shortening a long field name. Queries and filters use the original field name.
      - `format` (union anyOf)
        Set your preferred format for displaying the value. Changing the format can affect the value and prevent highlighting in Discover.
        Same options as `format` in `fields`
      - `popularity` (number · min: 0)
        Adjust the popularity to make the field appear higher or lower in the fields list. By default, Discover orders fields from most selected to least selected.
  - `id` (string · min length: 1 · max length: 256)
    Kibana provides a unique identifier for each data view, or you can create your own.
  - `index_pattern` (string · min length: 1)
    The index pattern (Elasticsearch index expression) to use as the data source. Example: "my-index-*".
  - `name` (string · min length: 1 · max length: 256)
    The name of the data view. Example: "Sample data view".
  - `time_field` (string)
    The name of the time field in the index. Used for time-based filtering. Example: "@timestamp".
- `id` (string · max length: 1000)
  The ID of the data view.
- `meta` (object)
  Metadata about the data view.
  - `created_at` (string)
    Timestamp when the object was created (ISO 8601).
  - `created_by` (string)
    User profile ID of the user who created the object.
  - `managed` (boolean)
    When `true`, the object is managed by Kibana and cannot be edited by users.
  - `owner` (string)
    Identifier of the plugin or team that owns this object.
  - `spaces` (string[] · max items: 100)
    The IDs of the spaces where the data view is available.
  - `updated_at` (string)
    Timestamp when the object was last updated (ISO 8601).
  - `updated_by` (string)
    User profile ID of the user who last updated the object.
  - `version` (string)
    Internal version identifier for optimistic concurrency control.
#### `201`

created

`application/json`

- `data` (object)
  Defines an stored data source with a mandatory index pattern and optional settings like id, name, show hidden indices and field settings.
  Same fields as `data`
- `id` (string · max length: 1000)
  The ID of the data view.
- `meta` (object)
  Metadata about the data view.
  - `created_at` (string)
    Timestamp when the object was created (ISO 8601).
  - `created_by` (string)
    User profile ID of the user who created the object.
  - `managed` (boolean)
    When `true`, the object is managed by Kibana and cannot be edited by users.
  - `owner` (string)
    Identifier of the plugin or team that owns this object.
  - `spaces` (string[] · max items: 100)
    The IDs of the spaces where the data view is available.
  - `updated_at` (string)
    Timestamp when the object was last updated (ISO 8601).
  - `updated_by` (string)
    User profile ID of the user who last updated the object.
  - `version` (string)
    Internal version identifier for optimistic concurrency control.
#### `400`

invalid request

#### `403`

forbidden

#### `409`

conflict

## Code examples

#### Console

```console
PUT kbn:/api/data_views/v2/ID
{
  "index_pattern": "logs-*",
  "name": "Web logs",
  "time_field": "@timestamp"
}
```

#### curl

```curl
curl -X PUT "${KIBANA_URL}/api/data_views/v2/${ID}" \
  -H "kbn-xsrf: true" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "index_pattern": "logs-*",
    "name": "Web logs",
    "time_field": "@timestamp"
  }'
```

## Response examples

#### Data view response

`application/json`

```json
{
  "data": {
    "index_pattern": "logs-*",
    "name": "Web logs",
    "time_field": "@timestamp"
  },
  "id": "c0ffee00-d57a-11ef-9a52-4f3c2a8d0e1b",
  "meta": {
    "managed": false,
    "spaces": [
      "default"
    ],
    "version": "WzEsMV0="
  }
}
```

#### Data view response

`application/json`

```json
{
  "data": {
    "index_pattern": "logs-*",
    "name": "Web logs",
    "time_field": "@timestamp"
  },
  "id": "c0ffee00-d57a-11ef-9a52-4f3c2a8d0e1b",
  "meta": {
    "managed": false,
    "spaces": [
      "default"
    ],
    "version": "WzEsMV0="
  }
}
```