[discrete]
[[esql-substring]]
=== `SUBSTRING`

*Syntax*

[.text-center]
image::esql/functions/signature/substring.svg[Embedded,opts=inline]

*Parameters*

`str`::
String expression. If `null`, the function returns `null`.

`start`::
Start position.

`length`::
Length of the substring from the start position. Optional; if omitted, all
positions after `start` are returned.

*Description*

Returns a substring of a string, specified by a start position and an optional
length.

include::types/substring.asciidoc[]

*Examples*

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]
|===