elasticsearch/docs/reference/esql/functions/substring.asciidoc

[discrete]
[[esql-substring]]
=== `SUBSTRING`
Returns a substring of a string, specified by a start position and an optional
length. This example returns the first three characters of every last name:

[source.merge.styled,esql]
----
include::{esql-specs}/docs.csv-spec[tag=substring]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/docs.csv-spec[tag=substring-result]
|===

A negative start position is interpreted as being relative to the end of the
string. This example returns the last three characters of of every last name:

[source.merge.styled,esql]
----
include::{esql-specs}/docs.csv-spec[tag=substringEnd]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/docs.csv-spec[tag=substringEnd-result]
|===

If length is omitted, substring returns the remainder of the string. This
example returns all characters except for the first:

[source.merge.styled,esql]
----
include::{esql-specs}/docs.csv-spec[tag=substringRemainder]
----
[%header.monospaced.styled,format=dsv,separator=|]
|===
include::{esql-specs}/docs.csv-spec[tag=substringRemainder-result]
|===