'use strict'; // timezones can be defined either by an numeric offset in seconds or by // a valid (case-insensitive) tz/PG name; // they include abbreviations defined by PG (which have precedence and // are fixed offsets, not handling DST) or general names that can handle DST. function timezone (tz) { if (isFinite(tz)) { return `INTERVAL '${tz} seconds'`; } return `'${tz}'`; } // We assume t is a TIMESTAMP WITH TIME ZONE. // If this was to be used with a t which is a TIMESTAMP or TIME (no time zone) // it should be converted with `timezone('utc',t)` to a type with time zone. // Note that by default CARTO uses timestamp with time zone columns for dates // and VectorMapConfigAdapter converts them to epoch numbers. // So, for using this with aggregations, relying on dates & times // converted to UTC UNIX epoch numbers, apply `to_timestamp` to the // (converted) column. function timeExpression (t, tz) { if (tz !== undefined) { return `timezone(${timezone(tz)}, ${t})`; } return t; } function epochWithDefaults (epoch) { /* jshint maxcomplexity:9 */ // goddammit linter, I like this as is!! const format = /^(\d\d\d\d)(?:\-?(\d\d)(?:\-?(\d\d)(?:[T\s]?(\d\d)(?:(\d\d)(?:\:(\d\d))?)?)?)?)?$/; // eslint-disable-line no-useless-escape const match = (epoch || '').match(format) || []; const year = match[1] || '0001'; const month = match[2] || '01'; const day = match[3] || '01'; const hour = match[4] || '00'; const minute = match[5] || '00'; const second = match[6] || '00'; return `${year}-${month}-${day}T${hour}:${minute}:${second}`; } // Epoch should be an ISO timestamp literal without time zone // (it is interpreted as in the defined timzezone for the input time) // It can be partial, e.g. 'YYYY', 'YYYY-MM', 'YYYY-MM-DDTHH', etc. // Defaults are applied: YYYY=0001, MM=01, DD=01, HH=00, MM=00, S=00 // It returns a timestamp without time zone function epochExpression (epoch) { return `TIMESTAMP '${epoch}'`; } const YEARSPAN = "(date_part('year', $t)-date_part('year', $epoch))"; // Note that SECONDSPAN is not a UTC epoch, but an epoch in the specified TZ, // so we can use it to compute any multiple of seconds with it without using date_part or date_trunc const SECONDSPAN = "(date_part('epoch', $t) - date_part('epoch', $epoch))"; const serialParts = { second: { sql: `FLOOR(${SECONDSPAN})`, zeroBased: true }, minute: { sql: `FLOOR(${SECONDSPAN}/60)`, zeroBased: true }, hour: { sql: `FLOOR(${SECONDSPAN}/3600)`, zeroBased: true }, day: { sql: `1 + FLOOR(${SECONDSPAN}/86400)`, zeroBased: false }, week: { sql: `1 + FLOOR(${SECONDSPAN}/(7*86400))`, zeroBased: false }, month: { sql: `1 + date_part('month', $t) - date_part('month', $epoch) + 12*${YEARSPAN}`, zeroBased: false }, quarter: { sql: `1 + date_part('quarter', $t) - date_part('quarter', $epoch) + 4*${YEARSPAN}`, zeroBased: false }, semester: { sql: `1 + FLOOR((date_part('month', $t) - date_part('month', $epoch))/6) + 2*${YEARSPAN}`, zeroBased: false }, trimester: { sql: `1 + FLOOR((date_part('month', $t) - date_part('month', $epoch))/4) + 3*${YEARSPAN}`, zeroBased: false }, year: { // for the default epoch this coincides with date_part('year', $t) sql: `1 + ${YEARSPAN}`, zeroBased: false }, decade: { // for the default epoch this coincides with date_part('decade', $t) sql: `FLOOR((${YEARSPAN} + 1)/10)`, zeroBased: true }, century: { // for the default epoch this coincides with date_part('century', $t) sql: `1 + FLOOR(${YEARSPAN}/100)`, zeroBased: false }, millennium: { // for the default epoch this coincides with date_part('millennium', $t) sql: `1 + FLOOR(${YEARSPAN}/1000)`, zeroBased: false } }; function serialSqlExpr (params) { const { sql, zeroBased } = serialParts[params.units]; const column = timeExpression(params.time, params.timezone); const epoch = epochExpression(params.starting); const serial = sql.replace(/\$t/g, column).replace(/\$epoch/g, epoch); let expr = serial; if (params.count !== 1) { if (zeroBased) { expr = `FLOOR((${expr})/(${params.count}::double precision))::int`; } else { expr = `CEIL((${expr})/(${params.count}::double precision))::int`; } } else { expr = `(${expr})::int`; } return expr; } const isoParts = { second: 'to_char($t, \'YYYY-MM-DD"T"HH24:MI:SS\')', minute: 'to_char($t, \'YYYY-MM-DD"T"HH24:MI\')', hour: 'to_char($t, \'YYYY-MM-DD"T"HH24\')', day: 'to_char($t, \'YYYY-MM-DD\')', month: 'to_char($t, \'YYYY-MM\')', year: 'to_char($t, \'YYYY\')', week: 'to_char($t, \'IYYY-"W"IW\')', quarter: 'to_char($t, \'YYYY-"Q"Q\')', semester: 'to_char($t, \'YYYY"S"\') || to_char(CEIL(date_part(\'month\', $t)/6), \'9\')', trimester: 'to_char($t, \'YYYY"t"\') || to_char(CEIL(date_part(\'month\', $t)/4), \'9\')', decade: 'to_char(date_part(\'decade\', $t), \'"D"999\')', century: 'to_char($t, \'"C"CC\')', millennium: 'to_char(date_part(\'millennium\', $t), \'"M"999\')' }; function isoSqlExpr (params) { const column = timeExpression(params.time, params.timezone); if (params.count > 1) { // TODO: it would be sensible to return the ISO of the first unit in the period throw new Error('Multiple time units not supported for ISO format'); } return isoParts[params.units].replace(/\$t/g, column); } const cyclicParts = { dayOfWeek: 'date_part(\'isodow\', $t)', // 1 = monday to 7 = sunday; dayOfMonth: 'date_part(\'day\', $t)', // 1 to 31 dayOfYear: 'date_part(\'doy\', $t)', // 1 to 366 hourOfDay: 'date_part(\'hour\', $t)', // 0 to 23 monthOfYear: 'date_part(\'month\', $t)', // 1 to 12 quarterOfYear: 'date_part(\'quarter\', $t)', // 1 to 4 semesterOfYear: 'FLOOR((date_part(\'month\', $t)-1)/6.0) + 1', // 1 to 2 trimesterOfYear: 'FLOOR((date_part(\'month\', $t)-1)/4.0) + 1', // 1 to 3 weekOfYear: 'date_part(\'week\', $t)', // 1 to 53 minuteOfHour: 'date_part(\'minute\', $t)' // 0 to 59 }; function cyclicSqlExpr (params) { const column = timeExpression(params.time, params.timezone); return cyclicParts[params.units].replace(/\$t/g, column); } const ACCEPTED_PARAMETERS = ['time', 'units', 'timezone', 'count', 'starting', 'format']; const REQUIRED_PARAMETERS = ['time', 'units']; function validateParameters (params, checker) { const errors = []; const presentParams = Object.keys(params); const invalidParams = presentParams.filter(param => !ACCEPTED_PARAMETERS.includes(param)); if (invalidParams.length) { errors.push(`Invalid parameters: ${invalidParams.join(', ')}`); } const missingParams = REQUIRED_PARAMETERS.filter(param => !presentParams.includes(param)); if (missingParams.length) { errors.push(`Missing parameters: ${missingParams.join(', ')}`); } const paramsErrors = checker(params); errors.push(...paramsErrors.errors); if (errors.length) { throw new Error(`Invalid time dimension:\n${errors.join('\n')}`); } return paramsErrors.params; } const VALID_CYCLIC_UNITS = Object.keys(cyclicParts); const VALID_SERIAL_UNITS = Object.keys(serialParts); const VALID_ISO_UNITS = Object.keys(isoParts); function cyclicCheckParams (params) { const errors = []; if (!VALID_CYCLIC_UNITS.includes(params.units)) { errors.push(`Invalid units "${params.units}"`); } if (params.count && params.count > 1) { errors.push(`Count ${params.count} not supported for cyclic ${params.units}`); } return { errors: errors, params: params }; } function serialCheckParams (params) { const errors = []; if (!VALID_SERIAL_UNITS.includes(params.units)) { errors.push(`Invalid grouping units "${params.units}"`); } return { errors: errors, params: Object.assign({}, params, { starting: epochWithDefaults(params.starting) }) }; } function isoCheckParams (params) { const errors = []; if (!VALID_ISO_UNITS.includes(params.units)) { errors.push(`Invalid units "${params.units}"`); } if (params.starting) { errors.push("Parameter 'starting' not supported for ISO format"); } return { errors: errors, params: params }; } const CLASSIFIERS = { cyclic: { sqlExpr: cyclicSqlExpr, checkParams: cyclicCheckParams }, iso: { sqlExpr: isoSqlExpr, checkParams: isoCheckParams }, serial: { sqlExpr: serialSqlExpr, checkParams: serialCheckParams } }; function isCyclic (units) { return VALID_CYCLIC_UNITS.includes(units); } function classifierFor (params) { let classifier = 'serial'; if (params.units && isCyclic(params.units)) { classifier = 'cyclic'; } else if (params.format === 'iso') { classifier = 'iso'; } return CLASSIFIERS[classifier]; } function classificationSql (params) { const classifier = classifierFor(params); params = validateParameters(params, classifier.checkParams); return { sql: classifier.sqlExpr(params), effectiveParams: params }; } module.exports = classificationSql;