From c115e74241de11a336c8ad18ad73f55cd6fea988 Mon Sep 17 00:00:00 2001 From: logstashmachine <43502315+logstashmachine@users.noreply.github.com> Date: Tue, 9 Sep 2025 21:50:12 +0000 Subject: [PATCH 1/2] updated docs for 9.1 --- docs/plugins/filters/elasticsearch.asciidoc | 146 ++++++++++++++++++-- docs/plugins/inputs/beats.asciidoc | 8 +- docs/plugins/inputs/elastic_agent.asciidoc | 8 +- docs/plugins/inputs/http.asciidoc | 8 +- docs/plugins/inputs/jms.asciidoc | 8 +- docs/plugins/inputs/kafka.asciidoc | 8 +- docs/plugins/inputs/tcp.asciidoc | 8 +- docs/plugins/integrations/kafka.asciidoc | 8 +- docs/plugins/outputs/kafka.asciidoc | 8 +- 9 files changed, 168 insertions(+), 42 deletions(-) diff --git a/docs/plugins/filters/elasticsearch.asciidoc b/docs/plugins/filters/elasticsearch.asciidoc index 03c9366e9..b12145be3 100644 --- a/docs/plugins/filters/elasticsearch.asciidoc +++ b/docs/plugins/filters/elasticsearch.asciidoc @@ -5,10 +5,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v4.2.0 -:release_date: 2025-05-07 -:changelog_url: https://github.com/logstash-plugins/logstash-filter-elasticsearch/blob/v4.2.0/CHANGELOG.md -include_path: ../include +:version: v4.3.0 +:release_date: 2025-07-21 +:changelog_url: https://github.com/logstash-plugins/logstash-filter-elasticsearch/blob/v4.3.0/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// @@ -55,7 +55,7 @@ if [type] == "end" { The example below reproduces the above example but utilises the query_template. This query_template represents a full Elasticsearch query DSL and supports the -standard Logstash field substitution syntax. The example below issues +standard {ls} field substitution syntax. The example below issues the same query as the first example but uses the template shown. [source,ruby] @@ -119,6 +119,110 @@ Authentication to a secure Elasticsearch cluster is possible using _one_ of the Authorization to a secure Elasticsearch cluster requires `read` permission at index level and `monitoring` permissions at cluster level. The `monitoring` permission at cluster level is necessary to perform periodic connectivity checks. +[id="plugins-{type}s-{plugin}-esql"] +==== {esql} support + +.Technical Preview +**** +The {esql} feature that allows using ES|QL queries with this plugin is in Technical Preview. +Configuration options and implementation details are subject to change in minor releases without being preceded by deprecation warnings. +**** + +{es} Query Language ({esql}) provides a SQL-like interface for querying your {es} data. + +To use {esql}, this plugin needs to be installed in {ls} 8.17.4 or newer, and must be connected to {es} 8.11 or newer. + +To configure {esql} query in the plugin, set your {esql} query in the `query` parameter. + +IMPORTANT: We recommend understanding {ref}/esql-limitations.html[{esql} current limitations] before using it in production environments. + +The following is a basic {esql} query that sets the food name to transaction event based on upstream event's food ID: +[source, ruby] + filter { + elasticsearch { + hosts => [ 'https://..'] + api_key => '....' + query => ' + FROM food-index + | WHERE id == ?food_id + ' + query_params => { + "food_id" => "[food][id]" + } + } + } + +Set `config.support_escapes: true` in `logstash.yml` if you need to escape special chars in the query. + +In the result event, the plugin sets total result size in `[@metadata][total_values]` field. + +[id="plugins-{type}s-{plugin}-esql-event-mapping"] +===== Mapping {esql} result to {ls} event +{esql} returns query results in a structured tabular format, where data is organized into _columns_ (fields) and _values_ (entries). +The plugin maps each value entry to an event, populating corresponding fields. +For example, a query might produce a table like: + +[cols="2,1,1,1,2",options="header"] +|=== +|`timestamp` |`user_id` | `action` | `status.code` | `status.desc` + +|2025-04-10T12:00:00 |123 |login |200 | Success +|2025-04-10T12:05:00 |456 |purchase |403 | Forbidden (unauthorized user) +|=== + +For this case, the plugin creates two JSON look like objects as below and places them into the `target` field of the event if `target` is defined. +If `target` is not defined, the plugin places the _only_ first result at the root of the event. +[source, json] +[ + { + "timestamp": "2025-04-10T12:00:00", + "user_id": 123, + "action": "login", + "status": { + "code": 200, + "desc": "Success" + } + }, + { + "timestamp": "2025-04-10T12:05:00", + "user_id": 456, + "action": "purchase", + "status": { + "code": 403, + "desc": "Forbidden (unauthorized user)" + } + } +] + +NOTE: If your index has a mapping with sub-objects where `status.code` and `status.desc` actually dotted fields, they appear in {ls} events as a nested structure. + +[id="plugins-{type}s-{plugin}-esql-multifields"] +===== Conflict on multi-fields + +{esql} query fetches all parent and sub-fields fields if your {es} index has https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/multi-fields[multi-fields] or https://www.elastic.co/docs/reference/elasticsearch/mapping-reference/subobjects[subobjects]. +Since {ls} events cannot contain parent field's concrete value and sub-field values together, the plugin ignores sub-fields with warning and includes parent. +We recommend using the `RENAME` (or `DROP` to avoid warning) keyword in your {esql} query explicitly rename the fields to include sub-fields into the event. + +This is a common occurrence if your template or mapping follows the pattern of always indexing strings as "text" (`field`) + " keyword" (`field.keyword`) multi-field. +In this case it's recommended to do `KEEP field` if the string is identical and there is only one subfield as the engine will optimize and retrieve the keyword, otherwise you can do `KEEP field.keyword | RENAME field.keyword as field`. + +To illustrate the situation with example, assuming your mapping has a time `time` field with `time.min` and `time.max` sub-fields as following: +[source, ruby] + "properties": { + "time": { "type": "long" }, + "time.min": { "type": "long" }, + "time.max": { "type": "long" } + } + +The {esql} result will contain all three fields but the plugin cannot map them into {ls} event. +To avoid this, you can use the `RENAME` keyword to rename the `time` parent field to get all three fields with unique fields. +[source, ruby] + ... + query => 'FROM my-index | RENAME time AS time.current' + ... + +For comprehensive ES|QL syntax reference and best practices, see the https://www.elastic.co/guide/en/elasticsearch/reference/current/esql-syntax.html[{esql} documentation]. + [id="plugins-{type}s-{plugin}-options"] ==== Elasticsearch Filter Configuration Options @@ -144,6 +248,8 @@ NOTE: As of version `4.0.0` of this plugin, a number of previously deprecated se | <> |<>|No | <> |<>|No | <> |<>|No +| <> |<>, one of `["dsl", "esql"]`|No +| <> |<> or <>|No | <> |<>|No | <> |<>|No | <> |<>|No @@ -340,11 +446,30 @@ environment variables e.g. `proxy => '${LS_PROXY:}'`. * Value type is <> * There is no default value for this setting. -Elasticsearch query string. More information is available in the -{ref}/query-dsl-query-string-query.html#query-string-syntax[Elasticsearch query -string documentation]. -Use either `query` or `query_template`. +The query to be executed. +The accepted query shape is DSL query string or ES|QL. +For the DSL query string, use either `query` or `query_template`. +Read the {ref}/query-dsl-query-string-query.html[{es} query +string documentation] or {ref}/esql.html[{es} ES|QL documentation] for more information. + +[id="plugins-{type}s-{plugin}-query_type"] +===== `query_type` + +* Value can be `dsl` or `esql` +* Default value is `dsl` + +Defines the <> shape. +When `dsl`, the query shape must be valid {es} JSON-style string. +When `esql`, the query shape must be a valid {esql} string and `index`, `query_template` and `sort` parameters are not allowed. + +[id="plugins-{type}s-{plugin}-query_params"] +===== `query_params` + +* The value type is <> or <>. When an array provided, the array elements are pairs of `key` and `value`. +* There is no default value for this setting +Named parameters in {esql} to send to {es} together with <>. +Visit {ref}/esql-rest.html#esql-rest-params[passing parameters to query page] for more information. [id="plugins-{type}s-{plugin}-query_template"] ===== `query_template` @@ -541,8 +666,9 @@ Tags the event on failure to look up previous log event information. This can be Define the target field for placing the result data. If this setting is omitted, the target will be the root (top level) of the event. +It is highly recommended to set when using `query_type=>'esql'` to set all query results into the event. -The destination fields specified in <>, <>, and <> are relative to this target. +When `query_type=>'dsl'`, the destination fields specified in <>, <>, and <> are relative to this target. For example, if you want the data to be put in the `operation` field: [source,ruby] diff --git a/docs/plugins/inputs/beats.asciidoc b/docs/plugins/inputs/beats.asciidoc index 0d4d58532..366cf622f 100644 --- a/docs/plugins/inputs/beats.asciidoc +++ b/docs/plugins/inputs/beats.asciidoc @@ -8,10 +8,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v7.0.2 -:release_date: 2025-02-12 -:changelog_url: https://github.com/logstash-plugins/logstash-input-beats/blob/v7.0.2/CHANGELOG.md -:include_path: ../include +:version: v7.0.3 +:release_date: 2025-09-04 +:changelog_url: https://github.com/logstash-plugins/logstash-input-beats/blob/v7.0.3/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/elastic_agent.asciidoc b/docs/plugins/inputs/elastic_agent.asciidoc index bdbfcb6ca..7448d3d6b 100644 --- a/docs/plugins/inputs/elastic_agent.asciidoc +++ b/docs/plugins/inputs/elastic_agent.asciidoc @@ -8,10 +8,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v7.0.2 -:release_date: 2025-02-12 -:changelog_url: https://github.com/logstash-plugins/logstash-input-beats/blob/v7.0.2/CHANGELOG.md -:include_path: ../include +:version: v7.0.3 +:release_date: 2025-09-04 +:changelog_url: https://github.com/logstash-plugins/logstash-input-beats/blob/v7.0.3/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/http.asciidoc b/docs/plugins/inputs/http.asciidoc index 050541bad..d18fd5410 100644 --- a/docs/plugins/inputs/http.asciidoc +++ b/docs/plugins/inputs/http.asciidoc @@ -6,10 +6,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v4.1.2 -:release_date: 2025-02-12 -:changelog_url: https://github.com/logstash-plugins/logstash-input-http/blob/v4.1.2/CHANGELOG.md -:include_path: ../include +:version: v4.1.3 +:release_date: 2025-09-04 +:changelog_url: https://github.com/logstash-plugins/logstash-input-http/blob/v4.1.3/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/jms.asciidoc b/docs/plugins/inputs/jms.asciidoc index c9092b004..0e3146fc8 100644 --- a/docs/plugins/inputs/jms.asciidoc +++ b/docs/plugins/inputs/jms.asciidoc @@ -6,10 +6,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v3.3.0 -:release_date: 2025-03-07 -:changelog_url: https://github.com/logstash-plugins/logstash-input-jms/blob/v3.3.0/CHANGELOG.md -:include_path: ../include +:version: v3.3.1 +:release_date: 2025-09-08 +:changelog_url: https://github.com/logstash-plugins/logstash-input-jms/blob/v3.3.1/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/kafka.asciidoc b/docs/plugins/inputs/kafka.asciidoc index 24efd7b0d..6ae52e3b5 100644 --- a/docs/plugins/inputs/kafka.asciidoc +++ b/docs/plugins/inputs/kafka.asciidoc @@ -9,10 +9,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v11.6.3 -:release_date: 2025-06-12 -:changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.3/CHANGELOG.md -:include_path: ../include +:version: v11.6.4 +:release_date: 2025-08-28 +:changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.4/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/tcp.asciidoc b/docs/plugins/inputs/tcp.asciidoc index 0ac049b10..be2c96092 100644 --- a/docs/plugins/inputs/tcp.asciidoc +++ b/docs/plugins/inputs/tcp.asciidoc @@ -6,10 +6,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v7.0.2 -:release_date: 2025-02-12 -:changelog_url: https://github.com/logstash-plugins/logstash-input-tcp/blob/v7.0.2/CHANGELOG.md -:include_path: ../include +:version: v7.0.3 +:release_date: 2025-09-04 +:changelog_url: https://github.com/logstash-plugins/logstash-input-tcp/blob/v7.0.3/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/integrations/kafka.asciidoc b/docs/plugins/integrations/kafka.asciidoc index c5d84b9f1..d20ac60df 100644 --- a/docs/plugins/integrations/kafka.asciidoc +++ b/docs/plugins/integrations/kafka.asciidoc @@ -7,10 +7,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v11.6.3 -:release_date: 2025-06-12 -:changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.3/CHANGELOG.md -:include_path: ../include +:version: v11.6.4 +:release_date: 2025-08-28 +:changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.4/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/outputs/kafka.asciidoc b/docs/plugins/outputs/kafka.asciidoc index 73e66749e..a865c12f2 100644 --- a/docs/plugins/outputs/kafka.asciidoc +++ b/docs/plugins/outputs/kafka.asciidoc @@ -9,10 +9,10 @@ /////////////////////////////////////////// START - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// -:version: v11.6.3 -:release_date: 2025-06-12 -:changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.3/CHANGELOG.md -:include_path: ../include +:version: v11.6.4 +:release_date: 2025-08-28 +:changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.4/CHANGELOG.md +:include_path: ../../../../logstash/docs/include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// From 1a497dac4969cab02ea4651bb5abf5f11b16dc80 Mon Sep 17 00:00:00 2001 From: Karen Metts <35154725+karenzone@users.noreply.github.com> Date: Fri, 19 Sep 2025 13:54:47 -0400 Subject: [PATCH 2/2] Fix `include_path` --- docs/plugins/filters/elasticsearch.asciidoc | 4 ++-- docs/plugins/inputs/beats.asciidoc | 2 +- docs/plugins/inputs/elastic_agent.asciidoc | 2 +- docs/plugins/inputs/http.asciidoc | 2 +- docs/plugins/inputs/jms.asciidoc | 2 +- docs/plugins/inputs/kafka.asciidoc | 2 +- docs/plugins/inputs/tcp.asciidoc | 2 +- docs/plugins/integrations/kafka.asciidoc | 2 +- docs/plugins/outputs/kafka.asciidoc | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/plugins/filters/elasticsearch.asciidoc b/docs/plugins/filters/elasticsearch.asciidoc index b12145be3..7eeec10ff 100644 --- a/docs/plugins/filters/elasticsearch.asciidoc +++ b/docs/plugins/filters/elasticsearch.asciidoc @@ -8,7 +8,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v4.3.0 :release_date: 2025-07-21 :changelog_url: https://github.com/logstash-plugins/logstash-filter-elasticsearch/blob/v4.3.0/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// @@ -248,8 +248,8 @@ NOTE: As of version `4.0.0` of this plugin, a number of previously deprecated se | <> |<>|No | <> |<>|No | <> |<>|No -| <> |<>, one of `["dsl", "esql"]`|No | <> |<> or <>|No +| <> |<>, one of `["dsl", "esql"]`|No | <> |<>|No | <> |<>|No | <> |<>|No diff --git a/docs/plugins/inputs/beats.asciidoc b/docs/plugins/inputs/beats.asciidoc index 366cf622f..995305ba3 100644 --- a/docs/plugins/inputs/beats.asciidoc +++ b/docs/plugins/inputs/beats.asciidoc @@ -11,7 +11,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v7.0.3 :release_date: 2025-09-04 :changelog_url: https://github.com/logstash-plugins/logstash-input-beats/blob/v7.0.3/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/elastic_agent.asciidoc b/docs/plugins/inputs/elastic_agent.asciidoc index 7448d3d6b..2dd966af5 100644 --- a/docs/plugins/inputs/elastic_agent.asciidoc +++ b/docs/plugins/inputs/elastic_agent.asciidoc @@ -11,7 +11,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v7.0.3 :release_date: 2025-09-04 :changelog_url: https://github.com/logstash-plugins/logstash-input-beats/blob/v7.0.3/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/http.asciidoc b/docs/plugins/inputs/http.asciidoc index d18fd5410..c7773aa5a 100644 --- a/docs/plugins/inputs/http.asciidoc +++ b/docs/plugins/inputs/http.asciidoc @@ -9,7 +9,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v4.1.3 :release_date: 2025-09-04 :changelog_url: https://github.com/logstash-plugins/logstash-input-http/blob/v4.1.3/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/jms.asciidoc b/docs/plugins/inputs/jms.asciidoc index 0e3146fc8..b6786802a 100644 --- a/docs/plugins/inputs/jms.asciidoc +++ b/docs/plugins/inputs/jms.asciidoc @@ -9,7 +9,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v3.3.1 :release_date: 2025-09-08 :changelog_url: https://github.com/logstash-plugins/logstash-input-jms/blob/v3.3.1/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/kafka.asciidoc b/docs/plugins/inputs/kafka.asciidoc index 6ae52e3b5..3f174bfa7 100644 --- a/docs/plugins/inputs/kafka.asciidoc +++ b/docs/plugins/inputs/kafka.asciidoc @@ -12,7 +12,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v11.6.4 :release_date: 2025-08-28 :changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.4/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/inputs/tcp.asciidoc b/docs/plugins/inputs/tcp.asciidoc index be2c96092..49df7b09f 100644 --- a/docs/plugins/inputs/tcp.asciidoc +++ b/docs/plugins/inputs/tcp.asciidoc @@ -9,7 +9,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v7.0.3 :release_date: 2025-09-04 :changelog_url: https://github.com/logstash-plugins/logstash-input-tcp/blob/v7.0.3/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/integrations/kafka.asciidoc b/docs/plugins/integrations/kafka.asciidoc index d20ac60df..6a889b1fb 100644 --- a/docs/plugins/integrations/kafka.asciidoc +++ b/docs/plugins/integrations/kafka.asciidoc @@ -10,7 +10,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v11.6.4 :release_date: 2025-08-28 :changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.4/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! /////////////////////////////////////////// diff --git a/docs/plugins/outputs/kafka.asciidoc b/docs/plugins/outputs/kafka.asciidoc index a865c12f2..85f1e92a7 100644 --- a/docs/plugins/outputs/kafka.asciidoc +++ b/docs/plugins/outputs/kafka.asciidoc @@ -12,7 +12,7 @@ START - GENERATED VARIABLES, DO NOT EDIT! :version: v11.6.4 :release_date: 2025-08-28 :changelog_url: https://github.com/logstash-plugins/logstash-integration-kafka/blob/v11.6.4/CHANGELOG.md -:include_path: ../../../../logstash/docs/include +:include_path: ../include /////////////////////////////////////////// END - GENERATED VARIABLES, DO NOT EDIT! ///////////////////////////////////////////