Функции даты

AQL предлагает функциональность для работы с датами, но не имеет специального типа данных для дат (как и JSON, который обычно используется в качестве формата для передачи данных в ArangoDB и обратно). Вместо этого даты в AQL представляются либо числами, либо строками.

Все операции с датами выполняются в системе Unix time. Время Unix отсчитывает все невисокосные секунды, начиная с 1 января 1970 года 00:00:00.000 UTC, также известное как эпоха Unix. Точка во времени называется временной меткой. Временная метка имеет одно и то же значение в каждой точке Земли. Функции даты используют миллисекундную точность для временных меток.

Определения единиц времени:

• миллисекунда: 1/1000 секунды
• секунда: одна секунда СИ
• минута: одна минута определяется как 60 секунд
• час: один час определяется как 60 минут
• день: один день определяется как 24 часа
• неделя: одна неделя определяется как 7 дней
• месяц: один месяц определяется как 1/12 часть года
• год: один год равен 365,2425 дня.

Все функции, требующие в качестве аргументов даты, принимают следующие входные значения:

• числовые временные метки, точность миллисекунд.

  Пример значения временной метки - 1399472349522, что переводится как 2014-05-07T14:19:09.522Z.

  Допустимый диапазон: -62167219200000 ... 253402300799999 (включительно)

• строки даты-времени в формате ISO 8601:

  • YYYY-MM-DDTHH:MM:SS.MMM.
  • YYYY-MM-DDHH:MM:SS.MMM
  • ГГГГ-ММ-ДД

  Миллисекунды (.МММ) всегда необязательны. Две цифры для часов (HH), минут (MM) и секунд (SS) являются обязательными, т.е. для значений от 0 до 9 требуется добавление нуля (например, 05 вместо 5). Ведущие нули для года (YYYY), месяца (MM) и дня (DD) можно не указывать, но это не рекомендуется.

  В конце строки по желанию может быть добавлено смещение времени с указанием часов и минут, которые нужно прибавить или вычесть к значению времени даты. Например, 2014-05-07T14:19:09+01:00 может использоваться для указания смещения на один час, а 2014-05-07T14:19:09+07:30 - для смещения на семь с половиной часов. Возможны также отрицательные смещения. В качестве альтернативы смещению можно использовать Z для указания времени UTC / Zulu. Пример значения: 2014-05-07T14:19:09.522Z означает 7 мая 2014 года, 14:19:09 и 522 миллисекунды, время UTC / Zulu. Другой пример значения без компонента времени - 2014-05-07Z.

  Допустимый диапазон: "0000-01-01T00:00:00.000Z" ... "9999-12-31T23:59:59.999Z" (включительно).

Любые значения даты/времени вне допустимого диапазона, переданные в функцию даты AQL, заставят функцию вернуть null и вызовут предупреждение для запроса, которое может быть переведено в ошибку и прервать запрос. Это также относится к операциям, которые выдают недопустимое значение.

DATE_HOUR( 2 * 60 * 60 * 1000 ) // 2
DATE_HOUR("1970-01-01T02:00:00") // 2

Конечно, вы можете хранить определения возраста образцов, неполные или нечеткие даты и т.п. другими, более подходящими способами. Функции даты AQL для таких дат, конечно, не помогут, но вы можете использовать такие конструкции языка, как SORT (который также поддерживает сортировку массивов) и indexes.

Текущая дата и время

DATE_NOW()

DATE_NOW() → timestamp

Получение текущего времени unix в виде числовой метки времени.

• возвращает timestamp (число): текущее время unix в виде временной метки. Возвращаемое значение имеет миллисекундную точность. Чтобы преобразовать возвращаемое значение в секунды, разделите его на 1000.

Обратите внимание, что эта функция оценивается при каждом вызове и может возвращать разные значения при многократном вызове в одном и том же запросе. Чтобы использовать одну и ту же временную метку несколько раз, присвойте ее переменной.

Преобразование

DATE_TIMESTAMP() и DATE_ISO8601() могут использоваться для преобразования строк времени даты ISO 8601 в числовые временные метки и числовых временных меток в строки времени даты ISO 8601.

Обе функции также поддерживают отдельные компоненты даты как отдельные аргументы функции, в следующем порядке:

• год
• месяц
• день
• час
• минута
• секунда
• миллисекунда

Все компоненты после day являются необязательными и могут быть опущены. Обратите внимание, что при использовании отдельных компонентов даты не может быть задано смещение времени, и будет использоваться время UTC / Zulu.

Следующие вызовы DATE_TIMESTAMP() эквивалентны и все вернут 1399472349522:

DATE_TIMESTAMP("2014-05-07T14:19:09.522")
DATE_TIMESTAMP("2014-05-07T14:19:09.522Z")
DATE_TIMESTAMP("2014-05-07 14:19:09.522")
DATE_TIMESTAMP("2014-05-07 14:19:09.522Z")
DATE_TIMESTAMP(2014, 5, 7, 14, 19, 9, 522)
DATE_TIMESTAMP(1399472349522)

То же самое справедливо для вызовов DATE_ISO8601(), которые также принимают переменные форматы ввода:

DATE_ISO8601("2014-05-07T14:19:09.522Z")
DATE_ISO8601("2014-05-07 14:19:09.522Z")
DATE_ISO8601(2014, 5, 7, 14, 19, 9, 522)
DATE_ISO8601(1399472349522)

Все приведенные выше функции эквивалентны и вернут "2014-05-07T14:19:09.522Z ".

DATE_ISO8601()

DATE_ISO8601(date) → dateString.

Возвращает строку времени даты ISO 8601 из date. Строка времени даты всегда будет использовать время UTC / Zulu, на что указывает Z в ее конце.

• date (number|string): числовая метка времени или строка времени даты ISO 8601
• возвращает dateString: дату и время, выраженные в соответствии с ISO 8601, во времени Зулу.

---

DATE_ISO8601(год, месяц, день, час, минута, секунда, миллисекунда) → dateString

Возвращает строку времени даты ISO 8601 из date, но позволяет указать отдельные компоненты даты отдельно. Все параметры после day являются необязательными.

• год (число): обычно в диапазоне 0...9999, например, 2017.
• месяц (число): 1...12 для января-декабря.
• день (число): 1...31 (верхняя граница зависит от количества дней в месяце)
• час (число, опционально): 0..23
• минута (число, опционально): 0..59
• секунда (число, опционально): 0..59
• миллисекунды (число, опционально): 0..999
• возвращает dateString: дату и время, выраженные в соответствии с ISO 8601, в зулусском времени

DATE_TIMESTAMP()

DATE_TIMESTAMP(date) → timestamp

Создает значение временной метки из даты. Возвращаемое значение имеет миллисекундную точность. Чтобы преобразовать возвращаемое значение в секунды, разделите его на 1000.

• date (число|строка): числовая временная метка или строка времени даты ISO 8601
• возвращает timestamp (число): числовая временная метка

---

DATE_TIMESTAMP(год, месяц, день, час, минута, секунда, миллисекунда) → timestamp

Создает значение временной метки, но позволяет указать отдельные компоненты даты отдельно. Все параметры после day являются необязательными.

• год (число): обычно в диапазоне 0...9999, например 2017.
• месяц (число): 1...12 для января-декабря.
• день (число): 1...31 (верхняя граница зависит от количества дней в месяце)
• час (число, опционально): 0..23
• минута (число, опционально): 0..59

• секунда (число, опционально): 0..59
• миллисекунды (число, опционально): 0..999
• возвращает timestamp (число): числовая метка времени.

Отрицательные значения не допускаются, приводят к null и вызывают предупреждение. Значения, превышающие верхнюю границу диапазона, переполняются на большие компоненты (например, час из 26 автоматически превращается в дополнительный день и два часа):

DATE_TIMESTAMP(2016, 12, -1) // returns null and issues a warning
DATE_TIMESTAMP(2016, 2, 32) // returns 1456963200000, which is March 3rd, 2016
DATE_TIMESTAMP(1970, 1, 1, 26) // returns 93600000, which is January 2nd, 1970, at 2 a.m.

IS_DATESTRING()

IS_DATESTRING(value) → bool

Проверяет, подходит ли произвольная строка для интерпретации в качестве строки даты-времени.

• значение (строка): произвольная строка
• возвращает bool (bool): true, если value является строкой, которая может быть использована в функции даты. Сюда входят неполные даты, такие как 2015 или 2015-10, а также строки, содержащие недопустимые даты, такие как 2015-02-31. Функция вернет false для всех нестроковых значений, даже если некоторые из них могут быть использованы в функции даты.

Обработка

DATE_DAYOFWEEK()

DATE_DAYOFWEEK(date) → WeekdayNumber

Возвращает номер дня недели даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает weekdayNumber (число): 0...6 следующим образом:
  • 0 - воскресенье
  • 1 - понедельник
  • 2 - вторник
  • 3 - среда
  • 4 - четверг
  • 5 - пятница
  • 6 - суббота

ДАТА_ГОД()

DATE_YEAR(дата) → год

Возвращает год даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает год (число): часть года даты в виде числа.

ДАТА_МЕСЯЦ()

DATE_MONTH(дата) → месяц

Возвращает месяц даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает месяц (число): месячную часть даты в виде числа.

ДАТА_ДЕНЬ()

DATE_DAY(date) → day

Возвращает день даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает day (число): дневную часть даты в виде числа.

DATE_HOUR()

Возвращает час даты.

DATE_HOUR(дата) → час

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает час (число): часовую часть даты в виде числа.

DATE_MINUTE()

DATE_MINUTE(date) → minute

Возвращает минуту от даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает минуту (число): минутную часть даты в виде числа.

ДАТА_СЕКУНДА()

DATE_SECOND(date) → second

Возвращает второе значение даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает секунду (число): секундную часть даты в виде числа.

DATE_MILLISECOND()

DATE_MILLISECOND(date) → миллисекунда

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает миллисекунду (число): часть даты в миллисекундах в виде числа

DATE_DAYOFYEAR()

DATE_DAYOFYEAR(date) → dayOfYear.

Возвращает день года даты.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает dayOfYear (число): номер дня года даты. Возвращаемые значения варьируются от 1 до 365, или 366 в високосном году соответственно.

DATE_ISOWEEK()

DATE_ISOWEEK(date) → weekDate

Возвращает дату недели date в соответствии с ISO 8601.

• date (number|string): числовая метка времени или строка времени даты по ISO 8601
• возвращает weekDate (число): дата недели по ISO для даты. Возвращаемые значения варьируются от 1 до 53. Первым днем недели считается понедельник. Дробных недель не существует, поэтому последние дни декабря могут относиться к первой неделе следующего года, а первые дни января могут быть частью последней недели предыдущего года.

DATE_LEAPYEAR()

DATE_LEAPYEAR(date) → leapYear.

Возвращает, находится ли дата в високосном году.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает leapYear (bool): true если дата находится в високосном году, false в противном случае.

DATE_QUARTER()

DATE_QUARTER(дата) → квартал

Возвращает, к какому кварталу относится дата.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает квартал (число): квартал данной даты (на основе 1):
  • 1 - январь, февраль, март
  • 2 - апрель, май, июнь
  • 3 - июль, август, сентябрь
  • 4 - октябрь, ноябрь, декабрь

DATE_DAYS_IN_MONTH()

Возвращает количество дней в месяце даты.

DATE_DAYS_IN_MONTH(date) → daysInMonth

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• возвращает daysInMonth (число): количество дней в месяце даты (28..31)

DATE_TRUNC()

DATE_TRUNC(date, unit) → isoDate.

Усекает заданную дату после единицы и возвращает измененную дату.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• unit (строка): одно из следующих значений для указания единицы времени (без учета регистра):
  • y, год, годы
  • m, месяц, месяцы
  • d, день, дни
  • h, час, часы
  • i, минута, минуты
  • s, секунда, секунды
  • f, миллисекунда, миллисекунды
• возвращает isoDate (строка): усеченную строку времени даты ISO 8601.

DATE_TRUNC('2017-02-03', 'month') // 2017-02-01T00:00:00.000Z
DATE_TRUNC('2017-02-03 04:05:06', 'hours') // 2017-02-03 04:00:00.000Z

DATE_ROUND()

DATE_ROUND(date, amount, unit) → isoDate.

Разбивает дату/время на множество равноудаленных друг от друга ведер, используемых для группировки.

• дата (строка|число): строка даты или метка времени.
• сумма (число): количество единиц. Должно быть целое положительное значение.
• единица (строка): одно из следующих значений для указания единицы времени (без учета регистра):
  • d, день, дни
  • h, час, часы
  • i, минута, минуты
  • s, секунда, секунды
  • f, миллисекунда, миллисекунды
• возвращает isoDate (строка): округленную по ISO 8601 строку времени даты

DATE_ROUND('2000-04-28T11:11:11.111Z', 1, 'day') // 2000-04-28T00:00:00.000Z
DATE_ROUND('2000-04-10T11:39:29Z', 15, 'minutes') // 2000-04-10T11:30:00.000Z

DATE_FORMAT()

DATE_FORMAT(date, format) → str

Форматирует дату в соответствии с заданной строкой формата.

• дата (строка|число): строка даты или метка времени.
• формат (строка): строка формата, см. ниже
• возвращает str (строка): отформатированную строку даты

format поддерживает следующие заполнители (нечувствительные к регистру):

• %t - временная метка, в миллисекундах с полуночи 1970-01-01.
• %z - дата ISO (0000-00-00T00:00:00.000Z)
• %w - день недели (0..6)
• %y - год (0..9999)
• %yy - год (00..99), сокращенно (последние две цифры)
• %yyyy - год (0000..9999), заполненный до длины 4
• %yyyyyy - год (-009999 ... +009999), с префиксом знака и заполнением до длины 6
• %m - месяц (1..12)
• %mm - месяц (01..12), заполненный до длины 2
• %d - день (1..31)
• %dd - день (01..31), заполненный до длины 2
• %h - час (0..23)
• %hh - час (00..23), заполненный до длины 2
• %i - минута (0..59)
• %ii - минута (00..59), заполненная до длины 2
• %s - секунда (0..59)
• %ss - секунда (00..59), заполненная до длины 2
• %f - миллисекунда (0..999)
• %fff - миллисекунда (000...999), заполненная до длины 3
• %x - день года (1..366)
• %xxx - день года (001..366), заполненный до длины 3
• %k - дата недели ISO (1..53)
• %kk - дата недели ISO (01..53), заполненная до длины 2
• %l - високосный год (0 или 1)
• %q - квартал (1..4)
• %a - дни в месяце (28..31)
• %mmm - сокращенное английское название месяца (янв...дек.)
• %mmmm - английское название месяца (январь...декабрь)
• %www - сокращенное английское название дня недели (Sun..Sat)
• %www - английское название дня недели (воскресенье... суббота)
• %& - специальная управляющая последовательность для редких случаев
• %% - буквальный %
• % - игнорируется

%yyy не обеспечивает длину 4 для годов до 0 и после 9999. Вместо этого будет использоваться тот же формат, что и для %yyyyy. %yyy сохраняет знак для отрицательных годов и может возвращать 3 символа в целом.

Одиночные символы % будут проигнорированы. Используйте %% для буквального %. Для разрешения неоднозначности, как в %mmonth (номер месяца без вставки + строка "месяц") между %mm + "onth" и %m + "month", используйте экранирующую последовательность %&: %m%&month.

Обратите внимание, что DATE_FORMAT() является довольно дорогостоящей операцией и может не подходить для больших наборов данных (например, более 1 миллиона дат). Если возможно, избегайте форматирования дат на стороне сервера и предоставьте это клиенту. Эта функция должна использоваться только для специальных сравнений дат или для хранения отформатированных дат в базе данных. Для повышения производительности используйте примитивные функции DATE_*() вместе с CONCAT(), если это возможно.

Примеры:

DATE_FORMAT(DATE_NOW(), "%q/%yyyy") // quarter and year (e.g. "3/2015")
DATE_FORMAT(DATE_NOW(), "%dd.%mm.%yyyy %hh:%ii:%ss,%fff") // e.g. "18.09.2015 15:30:49,374"
DATE_FORMAT("1969", "Summer of '%yy") // "Summer of '69"
DATE_FORMAT("2016", "%%l = %l") // "%l = 1" (2016 is a leap year)
DATE_FORMAT("2016-03-01", "%xxx%") // "063", trailing % ignored

Сравнение и вычисление

DATE_ADD()

DATE_ADD(дата, сумма, единица) → isoDate.

Добавляет сумму, указанную в единице, к дате и возвращает вычисленную дату.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• amount (number|string): количество единиц для сложения (положительное значение) или вычитания (отрицательное значение). Рекомендуется использовать только положительные значения, а для вычитания использовать DATE_SUBTRACT().
• unit (строка): одно из следующих значений для указания единицы времени для сложения или вычитания (нечувствительно к регистру):
  • y, год, годы
  • m, месяц, месяцы
  • w, неделя, недели
  • d, день, дни
  • h, час, часы
  • i, минута, минуты
  • s, секунда, секунды
  • f, миллисекунда, миллисекунды
• возвращает isoDate (строка): вычисленная по стандарту ISO 8601 строка времени даты

DATE_ADD(DATE_NOW(), -1, "day") // yesterday; also see DATE_SUBTRACT()
DATE_ADD(DATE_NOW(), 3, "months") // in three months
DATE_ADD(DATE_ADD("2015-04-01", 5, "years"), 1, "month") // May 1st 2020
DATE_ADD("2015-04-01", 12*5 + 1, "months") // also May 1st 2020
DATE_ADD(DATE_TIMESTAMP(DATE_YEAR(DATE_NOW()), 12, 24), -4, "years") // Christmas four years ago
DATE_ADD(DATE_ADD("2016-02", "month", 1), -1, "day") // last day of February (29th, because 2016 is a leap year!)

---

DATE_ADD(date, isoDuration) → isoDate

Вы также можете передать строку продолжительности ISO как сумму и опустить единицу.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• isoDuration (строка): строка длительности ISO 8601 для добавления к дате, см. ниже
• возвращает isoDate (строка): вычисленную строку времени даты ISO 8601.

Формат P_Y_M_W_DT_H_M_._S, где символы подчеркивания обозначают цифры, а буквы - временные интервалы, за исключением разделителей P (точка) и T (время). Значение остальных букв следующее:

• Y - годы
• М - месяцы (если до Т)
• W - недели
• Д - дни
• Ч - часы
• M - минуты (если после T)
• S - секунды (опционально с 3 десятичными знаками для миллисекунд).

Строка должна иметь префикс P. Разделитель T требуется только в том случае, если указаны H, M и/или S. Вам нужно указать только необходимые пары букв и цифр.

DATE_ADD(DATE_NOW(), "P1Y") // add 1 year
DATE_ADD(DATE_NOW(), "P3M2W") // add 3 months and 2 weeks
DATE_ADD(DATE_NOW(), "P5DT26H") // add 5 days and 26 hours (=6 days and 2 hours)
DATE_ADD("2000-01-01", "PT4H") // add 4 hours
DATE_ADD("2000-01-01", "PT30M44.4S") // add 30 minutes, 44 seconds and 400 ms
DATE_ADD("2000-01-01", "P1Y2M3W4DT5H6M7.89S") // add a bit of everything

DATE_SUBTRACT()

DATE_SUBTRACT(date, amount, unit) → isoDate

Вычитает сумму, заданную в единицах, из даты и возвращает вычисленную дату.

Работает так же, как DATE_ADD(), за исключением вычитания. Это эквивалентно вызову DATE_ADD() с отрицательной суммой, за исключением того, что DATE_SUBTRACT() может также вычитать длительности ISO. Обратите внимание, что отрицательные значения длительности ISO не поддерживаются (т.е. начинающиеся с -P, например -P1Y).

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601.
• сумма (число|строка): количество единиц для вычитания (положительное значение) или сложения (отрицательное значение). Рекомендуется использовать только положительные значения, а для прибавления использовать DATE_ADD().
• unit (строка): одно из следующих значений для указания единицы времени для сложения или вычитания (нечувствительно к регистру):
  • y, год, годы
  • m, месяц, месяцы
  • w, неделя, недели
  • d, день, дни
  • h, час, часы
  • i, минута, минуты
  • s, секунда, секунды
  • f, миллисекунда, миллисекунды
• возвращает isoDate (строка): вычисленная по стандарту ISO 8601 строка времени даты

---

DATE_SUBTRACT(date, isoDuration) → isoDate

Вы также можете передать строку продолжительности ISO как сумму и опустить единицу.

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• isoDuration (строка): строка длительности ISO 8601 для вычитания из даты, см. ниже
• возвращает isoDate (строка): вычисленную строку времени даты ISO 8601.

Формат: P_Y_M_W_DT_H_M_._S, где символы подчеркивания обозначают цифры, а буквы - временные интервалы, за исключением разделителей P (точка) и T (время). Значение остальных букв следующее:

• Y - годы
• М - месяцы (если до Т)
• W - недели
• Д - дни
• Ч - часы
• M - минуты (если после T)
• S - секунды (опционально с 3 десятичными знаками для миллисекунд).

Строка должна иметь префикс P. Разделитель T требуется только в том случае, если указаны H, M и/или S. Вам нужно указать только необходимые пары букв и цифр.

DATE_SUBTRACT(DATE_NOW(), 1, "day") // yesterday
DATE_SUBTRACT(DATE_TIMESTAMP(DATE_YEAR(DATE_NOW()), 12, 24), 4, "years") // Christmas four years ago
DATE_SUBTRACT(DATE_ADD("2016-02", "month", 1), 1, "day") // last day of February (29th, because 2016 is a leap year!)
DATE_SUBTRACT(DATE_NOW(), "P4D") // four days ago
DATE_SUBTRACT(DATE_NOW(), "PT1H3M") // 1 hour and 30 minutes ago

DATE_DIFF()

DATE_DIFF(date1, date2, unit, asFloat) → diff

Вычисляет разницу между двумя датами в заданной единице времени, опционально с десятичными знаками.

• date1 (number|string): числовая метка времени или строка времени даты ISO 8601.
• дата2 (число|строка): числовая метка времени или строка времени даты ISO 8601
• unit (строка): одно из следующих значений для указания единицы времени, в которой возвращается разница (нечувствительно к регистру):
  • y, год, годы
  • m, месяц, месяцы
  • w, неделя, недели
  • d, день, дни
  • h, час, часы
  • i, минута, минуты
  • s, секунда, секунды
  • f, миллисекунда, миллисекунды
• asFloat (boolean, optional): если установлено значение true, десятичные знаки будут сохранены в результате. По умолчанию false и возвращается целое число.
• возвращает diff (число): вычисленную разность как число в единицах. Значение будет отрицательным, если дата2 раньше даты1.

DATE_COMPARE()

DATE_COMPARE(date1, date2, unitRangeStart, unitRangeEnd) → bool

Проверяет, совпадают ли две частичные даты.

• date1 (число|строка): числовая метка времени или строка времени даты ISO 8601
• дата2 (число|строка): числовая метка времени или строка времени даты ISO 8601
• unitRangeStart (строка): единица измерения, с которой следует начинать, см. ниже
• unitRangeEnd (строка, опционально): единица, с которой следует заканчивать, опустите, чтобы сравнивать только компонент, указанный в unitRangeStart. Возникает ошибка, если unitRangeEnd является единицей перед unitRangeStart.
• возвращает bool (bool): true, если даты совпадают, false в противном случае.

Сравниваемые части определяются диапазоном единиц времени. Полный диапазон таков: годы, месяцы, дни, часы, минуты, секунды, миллисекунды (в таком порядке).

Сравниваться будут все компоненты дата1 и дата2, указанные в диапазоне. Вы можете ссылаться на единицы измерения как:

• y, год, годы
• m, месяц, месяцы
• d, день, дни
• h, час, часы
• i, минута, минуты
• s, секунда, секунды
• f, миллисекунда, миллисекунды

// Compare months and days, true on birthdays if you're born on 4th of April
DATE_COMPARE("1985-04-04", DATE_NOW(), "months", "days")

// Will only match on one day if the current year is a leap year!
// You may want to add or subtract one day from date1 to match every year.
DATE_COMPARE("1984-02-29", DATE_NOW(), "months", "days")

// compare years, months and days (true, because it's the same day)
DATE_COMPARE("2001-01-01T15:30:45.678Z", "2001-01-01T08:08:08.008Z", "years", "days")

Вы можете напрямую сравнивать строки даты ISO, если хотите найти даты до или после определенной даты, или между двумя датами (>=, >, <, <=). Специальная функция для работы с датами не требуется. Однако тесты равенства (== и !=) будут соответствовать только точно таким же дате и времени. Вы можете использовать SUBSTRING() для сравнения неполных строк дат, DATE_COMPARE() - это, по сути, удобная функция для этого. Однако ни то, ни другое не требуется, чтобы ограничить поиск определенным днем, как показано здесь:

FOR doc IN coll
    FILTER doc.date >= "2015-05-15" AND doc.date < "2015-05-16"
    RETURN doc

Каждая дата ISO в этот день больше или равна 2015-05-15 при строковом сравнении (например, 2015-05-15T11:30:00.000Z). Даты до 2015-05-15 меньше и поэтому отфильтровываются первым условием. Каждая дата после 2015-05-15 больше этой даты в строковом сравнении и поэтому отфильтровывается вторым условием. В результате компоненты времени в датах, с которыми производится сравнение, "игнорируются". Запрос вернет каждый документ с датой в диапазоне от 2015-05-15T00:00:00.000Z до 2015-05-15T23:99:99.999Z. Он также будет включать 2015-05-15T24:00:00.000Z, но эта дата на самом деле 2015-05-16T00:00:00.000Z и может возникнуть только при ручной вставке (вы можете захотеть передать даты через DATE_ISO8601(), чтобы обеспечить правильное представление даты).

Високосные дни в високосные годы (29 февраля) всегда должны обрабатываться вручную, если вам это необходимо (например, проверка дней рождения):

LET today = DATE_NOW()
LET noLeapYear = NOT DATE_LEAPYEAR(today)

FOR user IN users
    LET birthday = noLeapYear AND
                   DATE_MONTH(user.birthday) == 2 AND
                   DATE_DAY(user.birthday) == 29
                   ? DATE_SUBTRACT(user.birthday, 1, "day") /* treat like 28th in non-leap years */
                   : user.birthday
    FILTER DATE_COMPARE(today, birthday, "month", "day")
    /* includes leaplings on the 28th of February in non-leap years,
     * but excludes them in leap years which do have a 29th February.
     * Replace DATE_SUBTRACT() by DATE_ADD() to include them on the 1st of March
     * in non-leap years instead (depends on local jurisdiction).
     */
    RETURN user

DATE_UTCTOLOCAL()

Введена в: v3.8.0

Конвертирует дату, заданную в зулусском времени (UTC), в местное время.

Учитывает исторический переход на летнее время.

DATE_UTCTOLOCAL(date, timezone, zoneinfo) → date

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• временная зона (строка): имя часового пояса IANA, например, Америка/Нью_Йорк, Европа/Берлин или UTC. Используйте "America/Los_Angeles" для тихоокеанского времени (PST/PDT). Выбросит ошибку, если часовой пояс не известен ArangoDB
• zoneinfo (boolean, опционально): если установлено значение true, возвращается объект с информацией о часовом поясе. По умолчанию false и возвращается строка даты.
• возвращает дата (строка|объект): строку времени даты ISO 8601 в неквалифицированном местном времени или объект со следующими атрибутами:
  • local (string): строка времени даты ISO 8601 в неквалифицированном местном времени.
  • tzdb (строка): версия используемой базы данных часовых поясов (например, 2020f)
  • zoneInfo: (объект): информация о часовом поясе
    • name (string): аббревиатура часового пояса (GMT, PST, CET, ...)
    • begin (string|null): начало действия часового пояса как строки времени даты UTC
    • end (string|null): конец эффекта временной зоны как строка времени даты UTC
    • dst (boolean): true, когда летнее время (DST) активно, false в противном случае.
    • offset (число): смещение к UTC в секундах.

DATE_LOCALTOUTC()

Введено в: v3.8.0

Конвертирует дату, принятую в местном временном поясе, в зулусское время (UTC).

Учитывает исторический переход на летнее время.

DATE_LOCALTOUTC(date, timezone, zoneinfo) → date

• дата (число|строка): числовая метка времени или строка времени даты ISO 8601
• временная зона (строка): имя часового пояса IANA, например, Америка/Нью_Йорк, Европа/Берлин или UTC. Используйте "America/Los_Angeles" для тихоокеанского времени (PST/PDT). Выбросит ошибку, если часовой пояс не известен ArangoDB
• zoneinfo (boolean, опционально): если установлено значение true, возвращается объект с информацией о часовом поясе. По умолчанию false и возвращается строка даты.
• возвращает date (string|object): строку времени даты ISO 8601 в зулусском времени (UTC), или объект со следующими атрибутами:
  • utc (строка): строка времени даты ISO 8601 в зулусском времени (UTC).
  • tzdb (строка): версия используемой базы данных часовых поясов (например, 2020f)
  • zoneInfo: (объект): информация о часовом поясе
    • name (string): аббревиатура часового пояса (GMT, PST, CET, ...)
    • begin (string|null): начало влияния часового пояса как строки времени даты UTC
    • end (string|null): конец эффекта временной зоны как строка времени даты UTC
    • dst (boolean): true, когда летнее время (DST) активно, false в противном случае.
    • offset (число): смещение к UTC в секундах.

DATE_TIMEZONE()

Введено в: v3.8.0

Возвращает системный часовой пояс, в котором работает ArangoDB.

Для облачных серверов это, скорее всего, будет "Etc/UTC".

DATE_TIMEZONE() → timezone

• возвращает timezone (строка): имя часового пояса IANA часовой пояс сервера.

DATE_TIMEZONES()

Введено в: v3.8.0

Возвращает все допустимые имена часовых поясов.

DATE_TIMEZONES() → timezones

• возвращает timezones (массив): массив имен часовых поясов IANA

Работа с датами и индексами

Существует два рекомендуемых способа хранения временных меток в ArangoDB:

• строка: временная метка UTC с ISO 8601
• число: unix timestamp с точностью до миллисекунды.

Порядок сортировки обоих типов идентичен благодаря свойствам сортировки строк дат ISO. Однако вы не можете смешивать оба типа, числа и строки, в одном атрибуте.

Вы можете использовать persistent indexes с обоими типами дат. При выборе строковых представлений вы можете работать со строковыми сравнениями (меньше чем, больше чем и т.д.) для выражения временных диапазонов в ваших запросах, используя при этом постоянные индексы:

Первая и последняя временные метки в массиве исключаются из результата с помощью FILTER.

Ограничения

Обратите внимание, что даты до 1583 года не допускаются стандартом ISO 8601 по умолчанию, так как они лежат до официального введения григорианского календаря и поэтому могут быть неправильными или недействительными. Все функции даты AQL применяют одни и те же правила к каждой дате по григорианской календарной системе, даже если она не соответствует действительности. Это не представляет проблемы, если только вы не имеете дело с датами до 1583 года и особенно с годами до нашей эры. Стандарт допускает отрицательные годы, но требует особого отношения и к положительным годам, если используются отрицательные годы (например, +002015-05-15 и -000753-01-01). Однако это редко используется, и AQL не использует 7-символьную версию для лет от 0 до 9999 в строках ISO. Имейте в виду, что их нельзя корректно сравнивать с датами вне этого диапазона. Сортировка отрицательных дат не приводит к осмысленному порядку, при этом годы более давние оказываются последними, но месяцы, дни и компоненты времени располагаются в правильном порядке.

Високосные секунды игнорируются, как и в JavaScript согласно ECMAScript Language Specifications.

Комментарии