[pull] main from elastic:main

docs/changelog/116944.yaml

@@ -0,0 +1,11 @@
+pr: 116944
+summary: "Remove support for type, fields, `copy_to` and boost in metadata field definition"
+area: Mapping
+type: breaking
+issues: []
+breaking:
+  title: "Remove support for type, fields, copy_to and boost in metadata field definition"
+  area: Mapping
+  details: The type, fields, copy_to and boost parameters are no longer supported in metadata field definition
+  impact: Users providing type, fields, copy_to or boost as part of metadata field definition should remove them from their mappings.
+  notable: false

docs/changelog/90529.yaml

@@ -0,0 +1,26 @@
+pr: 90529
+summary: Output a consistent format when generating error json
+area: Infra/REST API
+type: "breaking"
+issues:
+ - 89387
+breaking:
+  title: Error JSON structure has changed when detailed errors are disabled
+  area: REST API
+  details: |-
+    This change modifies the JSON format of error messages returned to REST clients
+    when detailed messages are turned off.
+    Previously, JSON returned when an exception occurred, and `http.detailed_errors.enabled: false` was set,
+    just consisted of a single `"error"` text field with some basic information.
+    Setting `http.detailed_errors.enabled: true` (the default) changed this field
+    to an object with more detailed information.
+    With this change, non-detailed errors now have the same structure as detailed errors. `"error"` will now always
+    be an object with, at a minimum, a `"type"` and `"reason"` field. Additional fields are included when detailed
+    errors are enabled.
+    To use the previous structure for non-detailed errors, use the v8 REST API.
+  impact: |-
+    If you have set `http.detailed_errors.enabled: false` (the default is `true`)
+    the structure of JSON when any exceptions occur now matches the structure when
+    detailed errors are enabled.
+    To use the previous structure for non-detailed errors, use the v8 REST API.
+  notable: false

docs/reference/esql/esql-language.asciidoc

@@ -14,6 +14,7 @@ Detailed reference documentation for the {esql} language:
 * <<esql-enrich-data>>
 * <<esql-process-data-with-dissect-and-grok>>
 * <<esql-implicit-casting>>
+* <<esql-time-spans>>
 
 include::esql-syntax.asciidoc[]
 include::esql-commands.asciidoc[]
@@ -23,3 +24,4 @@ include::multivalued-fields.asciidoc[]
 include::esql-process-data-with-dissect-grok.asciidoc[]
 include::esql-enrich-data.asciidoc[]
 include::implicit-casting.asciidoc[]
+include::time-spans.asciidoc[]

docs/reference/esql/esql-syntax.asciidoc

@@ -157,21 +157,15 @@ FROM employees
 ==== Timespan literals
 
 Datetime intervals and timespans can be expressed using timespan literals.
-Timespan literals are a combination of a number and a qualifier. These
-qualifiers are supported:
-
-* `millisecond`/`milliseconds`/`ms`
-* `second`/`seconds`/`sec`/`s`
-* `minute`/`minutes`/`min`
-* `hour`/`hours`/`h`
-* `day`/`days`/`d`
-* `week`/`weeks`/`w`
-* `month`/`months`/`mo`
-* `quarter`/`quarters`/`q`
-* `year`/`years`/`yr`/`y`
+Timespan literals are a combination of a number and a temporal unit. The
+supported temporal units are listed in <<esql-time-spans-table, time span unit>>.
+More examples of the usages of time spans can be found in
+<<esql-time-spans, Use time spans in ES|QL>>.
+
 
 Timespan literals are not whitespace sensitive. These expressions are all valid:
 
 * `1day`
 * `1 day`
 * `1       day`
+

docs/reference/esql/functions/binary.asciidoc

@@ -87,6 +87,7 @@ Supported types:
 
 include::types/greater_than_or_equal.asciidoc[]
 
+[[esql-add]]
 ==== Add `+`
 [.text-center]
 image::esql/functions/signature/add.svg[Embedded,opts=inline]
@@ -98,6 +99,7 @@ Supported types:
 
 include::types/add.asciidoc[]
 
+[[esql-subtract]]
 ==== Subtract `-`
 [.text-center]
 image::esql/functions/signature/sub.svg[Embedded,opts=inline]

docs/reference/esql/implicit-casting.asciidoc

@@ -5,7 +5,7 @@
 <titleabbrev>Implicit casting</titleabbrev>
 ++++
 
-Often users will input `date`, `ip`, `version`, `date_period` or `time_duration` as simple strings in their queries for use in predicates, functions, or expressions. {esql} provides <<esql-type-conversion-functions, type conversion functions>> to explicitly convert these strings into the desired data types.
+Often users will input `date`, `date_period`, `time_duration`, `ip` or `version` as simple strings in their queries for use in predicates, functions, or expressions. {esql} provides <<esql-type-conversion-functions, type conversion functions>> to explicitly convert these strings into the desired data types.
 
 Without implicit casting users must explicitly code these `to_X` functions in their queries, when string literals don't match the target data types they are assigned or compared to. Here is an example of using `to_datetime` to explicitly perform a data type conversion.
 
@@ -18,7 +18,10 @@ FROM employees
 | LIMIT 1
 ----
 
-Implicit casting improves usability, by automatically converting string literals to the target data type. This is most useful when the target data type is `date`, `ip`, `version`, `date_period` or `time_duration`. It is natural to specify these as a string in queries.
+[discrete]
+[[esql-implicit-casting-example]]
+==== Implicit casting example
+Implicit casting automatically converts string literals to the target data type. This allows users to specify string values for types like `date`, `date_period`, `time_duration`, `ip` and `version` in their queries.
 
 The first query can be coded without calling the `to_datetime` function, as follows:
 
@@ -31,35 +34,36 @@ FROM employees
 | LIMIT 1
 ----
 
-[float]
-=== Implicit casting support
+[discrete]
+[[esql-implicit-casting-supported-operations]]
+==== Operations that support implicit casting
 
 The following table details which {esql} operations support implicit casting for different data types.
 
 [%header.monospaced.styled,format=dsv,separator=|]
 |===
-||ScalarFunction*|Operator*|<<esql-group-functions, GroupingFunction>>|<<esql-agg-functions, AggregateFunction>>
-|DATE|Y|Y|Y|N
-|IP|Y|Y|Y|N
-|VERSION|Y|Y|Y|N
-|BOOLEAN|Y|Y|Y|N
-|DATE_PERIOD/TIME_DURATION|Y|N|Y|N
+|ScalarFunctions|Operators|<<esql-group-functions, GroupingFunctions>>|<<esql-agg-functions, AggregateFunctions>>
+DATE|Y|Y|Y|N
+DATE_PERIOD/TIME_DURATION|Y|N|Y|N
+IP|Y|Y|Y|N
+VERSION|Y|Y|Y|N
+BOOLEAN|Y|Y|Y|N
 |===
 
-ScalarFunction* includes:
+ScalarFunctions includes:
 
-<<esql-conditional-functions-and-expressions, Conditional Functions and Expressions>>
+* <<esql-conditional-functions-and-expressions, Conditional Functions and Expressions>>
 
-<<esql-date-time-functions, Date and Time Functions>>
+* <<esql-date-time-functions, Date and Time Functions>>
 
-<<esql-ip-functions, IP Functions>>
+* <<esql-ip-functions, IP Functions>>
 
 
-Operator* includes:
+Operators includes:
 
-<<esql-binary-operators, Binary Operators>>
+* <<esql-binary-operators, Binary Operators>>
 
-<<esql-unary-operators, Unary Operator>>
+* <<esql-unary-operators, Unary Operator>>
 
-<<esql-in-operator, IN>>
+* <<esql-in-operator, IN>>
 

docs/reference/esql/time-spans.asciidoc

@@ -0,0 +1,111 @@
+[[esql-time-spans]]
+=== {esql} time spans
+
+++++
+<titleabbrev>Time spans</titleabbrev>
+++++
+
+Time spans represent intervals between two datetime values. There are currently two supported types of time spans:
+
+* `DATE_PERIOD` specifies intervals in years, quarters, months, weeks and days
+* `TIME_DURATION` specifies intervals in hours, minutes, seconds and milliseconds
+
+A time span requires two elements: an integer value and a temporal unit.
+
+Time spans work with grouping functions such as <<esql-bucket, BUCKET>>, scalar functions such as <<esql-date_trunc, DATE_TRUNC>> and arithmetic operators such as <<esql-add, `+`>> and <<esql-subtract, `-`>>. Convert strings to time spans using <<esql-to_dateperiod, TO_DATEPERIOD>>, <<esql-to_timeduration, TO_TIMEDURATION>>, or the cast operators `::DATE_PERIOD`, `::TIME_DURATION`.
+
+[discrete]
+[[esql-time-spans-examples]]
+==== Examples of using time spans in {esql}
+
+
+With `BUCKET`:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogramWithSpan]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/bucket.csv-spec[tag=docsBucketWeeklyHistogramWithSpan-result]
+|===
+
+
+With `DATE_TRUNC`:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=docsDateTrunc]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=docsDateTrunc-result]
+|===
+
+
+With `+` and/or `-`:
+[source.merge.styled,esql]
+----
+include::{esql-specs}/date.csv-spec[tag=docsNowWhere]
+----
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+include::{esql-specs}/date.csv-spec[tag=docsNowWhere-result]
+|===
+
+
+When a time span is provided as a named parameter in string format, `TO_DATEPERIOD`, `::DATE_PERIOD`, `TO_TIMEDURATION` or `::TIME_DURATION` can be used to convert to its corresponding time span value for arithmetic operations like `+` and/or `-`.
+[source, esql]
+----
+POST /_query
+{
+   "query": """
+   FROM employees
+   | EVAL x = hire_date + ?timespan::DATE_PERIOD, y = hire_date - TO_DATEPERIOD(?timespan)
+   """,
+   "params": [{"timespan" : "1 day"}]
+}
+----
+
+When a time span is provided as a named parameter in string format, it can be automatically converted to its corresponding time span value in grouping functions and scalar functions, like `BUCKET` and `DATE_TRUNC`.
+[source, esql]
+----
+POST /_query
+{
+   "query": """
+   FROM employees
+   | WHERE hire_date >= "1985-01-01T00:00:00Z" AND hire_date < "1986-01-01T00:00:00Z"
+   | STATS hires_per_week = COUNT(*) BY week = BUCKET(hire_date, ?timespan)
+   | SORT week
+   """,
+   "params": [{"timespan" : "1 week"}]
+}
+----
+
+[source, esql]
+----
+POST /_query
+{
+   "query": """
+   FROM employees
+   | KEEP first_name, last_name, hire_date
+   | EVAL year_hired = DATE_TRUNC(?timespan, hire_date)
+   """,
+   "params": [{"timespan" : "1 year"}]
+}
+----
+
+[discrete]
+[[esql-time-spans-table]]
+==== Supported temporal units
+[%header.monospaced.styled,format=dsv,separator=|]
+|===
+Temporal Units|Valid Abbreviations
+year|y, yr, years
+quarter|q, quarters
+month|mo, months
+week|w, weeks
+day|d, days
+hour|h, hours
+minute|min, minutes
+second|s, sec, seconds
+millisecond|ms, milliseconds
+|===

docs/reference/modules/http.asciidoc

@@ -145,11 +145,9 @@ NOTE: This header is only returned when the setting is set to `true`.
 
 `http.detailed_errors.enabled`::
 (<<static-cluster-setting,Static>>, boolean)
-Configures whether detailed error reporting in HTTP responses is enabled.
-Defaults to `true`, which means that HTTP requests that include the
-<<common-options-error-options,`?error_trace` parameter>> will return a
-detailed error message including a stack trace if they encounter an exception.
-If set to `false`, requests with the `?error_trace` parameter are rejected.
+Configures whether detailed error reporting in HTTP responses is enabled. Defaults to `true`.
+When this option is set to `false`, only basic information is returned if an error occurs in the request,
+and requests with <<common-options-error-options,`?error_trace` parameter>> set are rejected.
 
 `http.pipelining.max_events`::
 (<<static-cluster-setting,Static>>, integer)