Перейти к содержимому
Последнее обновление

STR_TO_DATE

Описание​

Функция преобразует входную строку с датой и временем в значение типа DATETIME в соответствии с указанным форматом.

Поведение этой функции соответствует поведению функции str_to_date в MySQL.

Синтаксис​

STR_TO_DATE(<datetime_str>, <format>)

Параметры​

ПараметрОписание
<datetime_str>Обязательный параметр. Входная строка с датой и временем, представляющая дату или время для преобразования. Поддерживаемые входные форматы описаны в разделах Преобразование даты и времени и Преобразование даты
<format>Обязательный параметр. Строка, задающая формат даты и времени, например %Y-%m-%d %H:%i:%s. Подробное описание параметров формата приведено в документации DATE_FORMAT

Кроме того, <format> поддерживает следующие альтернативные форматы и интерпретирует их как соответствующие стандартные форматы:

Альтернативный форматИнтерпретируется как
yyyyMMdd%Y%m%d
yyyy-MM-dd%Y-%m-%d
yyyy-MM-dd HH:mm:ss%Y-%m-%d %H:%i:%s

Возвращаемое значение​

Возвращает значение DATETIME, представляющее преобразованные дату и время.

Для сопоставления даты и времени используются два указателя, изначально указывающие на начало соответствующих строк:

  1. Когда в строке формата встречается символ %, следующая за % буква используется для сопоставления с соответствующей частью строки даты и времени. Если сопоставление не удалось (например, %Y сопоставляется с частью времени, такой как 10:10:10, или за % следует неподдерживаемый символ, как в %*), возвращается ошибка. Если сопоставление прошло успешно, разбор продолжается со следующего символа.
  2. Если на любом этапе в одной из строк встречается пробел, он пропускается, и разбор продолжается со следующего символа.
  3. При сопоставлении обычных букв проверяется, совпадают ли символы, на которые указывают оба указателя. Если они не совпадают, возвращается ошибка; если совпадают, разбор продолжается со следующего символа.
  4. Когда указатель в строке даты достигает конца строки и строка даты и времени содержит только дату, проверяется, содержит ли строка формата спецификаторы времени (например, %H). Если содержит, для времени устанавливается значение 00:00:00.
  5. Когда указатель в строке формата достигает её конца, сопоставление завершается.
  6. В завершение проверяется корректность сопоставленных компонентов даты и времени (например, месяц должен находиться в диапазоне [1,12]). Если они некорректны, возвращается ошибка; если корректны, возвращаются разобранные дата и время.

Обработка ошибок:

  • Если какой-либо параметр равен NULL, возвращается NULL;
  • Если <format> — пустая строка, возвращается NULL;
  • Если сопоставление <datetime_str> и <format> не удалось, возвращается NULL.

Примеры​

-- Parse using standard format specifiers
SELECT STR_TO_DATE('2025-01-23 12:34:56', '%Y-%m-%d %H:%i:%s') AS result;
+---------------------+
| result              |
+---------------------+
| 2025-01-23 12:34:56 |
+---------------------+

-- Parse using alternative format
SELECT STR_TO_DATE('2025-01-23 12:34:56', 'yyyy-MM-dd HH:mm:ss') AS result;
+---------------------+
| result              |
+---------------------+
| 2025-01-23 12:34:56 |
+---------------------+

-- Date string only (time defaults to 00:00:00)
SELECT STR_TO_DATE('20230713', 'yyyyMMdd') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-07-13 00:00:00 |
+---------------------+

-- Parse string with week number and weekday
SELECT STR_TO_DATE('200442 Monday', '%X%V %W') AS result;
+------------+
| result     |
+------------+
| 2004-10-18 |
+------------+

-- Parse abbreviated month name and 12-hour time
SELECT STR_TO_DATE('Oct 5 2023 3:45:00 PM', '%b %d %Y %h:%i:%s %p') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-10-05 15:45:00 |
+---------------------+

-- Format does not match string (returns NULL)
SELECT STR_TO_DATE('2023/01/01', '%Y-%m-%d') AS result;
+--------+
| result |
+--------+
| NULL   |
+--------+

-- String contains extra characters (automatically ignored)
SELECT STR_TO_DATE('2023-01-01 10:00:00 (GMT)', '%Y-%m-%d %H:%i:%s') AS result;
+---------------------+
| result              |
+---------------------+
| 2023-01-01 10:00:00 |
+---------------------+

-- Parse microseconds (precision preserved)
SELECT STR_TO_DATE('2023-07-13 12:34:56.789', '%Y-%m-%d %H:%i:%s.%f') AS result;
+----------------------------+
| result                     |
+----------------------------+
| 2023-07-13 12:34:56.789000 |
+----------------------------+

-- Any parameter is NULL (returns NULL)
SELECT STR_TO_DATE(NULL, '%Y-%m-%d'), STR_TO_DATE('2023-01-01', NULL) AS result;
+--------------------------------+--------+
| str_to_date(NULL, '%Y-%m-%d')  | result |
+--------------------------------+--------+
| NULL                           | NULL   |
+--------------------------------+--------+

-- Format is an empty string (returns NULL)
SELECT STR_TO_DATE('2023-01-01', '') AS result;
+--------+
| result |
+--------+
| NULL   |
+--------+
Report issue