Add some default macros (#45)

Author: andresmgot

README.md

@@ -17,3 +17,16 @@ if err := datasource.Manage("my-datasource", ds.NewDatasource, datasource.Manage
   os.Exit(1)
 }
 ```
+
+## Standardization
+
+### Macros
+
+The `sqlds` package defines a set of default macros:
+
+- `$__timeFilter(time_column)`: Filters by timestamp using the query period. Resolves to: `time >= '0001-01-01T00:00:00Z' AND time <= '0001-01-01T00:00:00Z'`
+- `$__timeFrom(time_column)`: Filters by timestamp using the start point of the query period. Resolves to `time >= '0001-01-01T00:00:00Z'`
+- `$__timeTo(time_column)`: Filters by timestamp using the end point of the query period. Resolves to `time <= '0001-01-01T00:00:00Z'`
+- `$__timeGroup(time_column, period)`: To group times based on a period. Resolves to (minute example): `"datepart(year, time), datepart(month, time)'"`
+- `$__table`: Returns the `table` configured in the query.
+- `$__column`: Returns the `column` configured in the query.

macros.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"regexp"
 	"strings"
+	"time"
 )
 
 var (
@@ -20,6 +21,103 @@ type MacroFunc func(*Query, []string) (string, error)
 // The "string" key is the name of the macro function. This name has to be regex friendly.
 type Macros map[string]MacroFunc
 
+// Default time filter for SQL based on the query time range.
+// It requires one argument, the time column to filter.
+// Example:
+//   $__timeFilter(time) => "time BETWEEN '2006-01-02T15:04:05Z07:00' AND '2006-01-02T15:04:05Z07:00'"
+func macroTimeFilter(query *Query, args []string) (string, error) {
+	if len(args) != 1 {
+		return "", fmt.Errorf("%w: expected 1 argument, received %d", ErrorBadArgumentCount, len(args))
+	}
+
+	var (
+		column = args[0]
+		from   = query.TimeRange.From.UTC().Format(time.RFC3339)
+		to     = query.TimeRange.To.UTC().Format(time.RFC3339)
+	)
+
+	return fmt.Sprintf("%s >= '%s' AND %s <= '%s'", column, from, column, to), nil
+}
+
+// Default time filter for SQL based on the starting query time range.
+// It requires one argument, the time column to filter.
+// Example:
+//   $__timeFrom(time) => "time > '2006-01-02T15:04:05Z07:00'"
+func macroTimeFrom(query *Query, args []string) (string, error) {
+	if len(args) != 1 {
+		return "", fmt.Errorf("%w: expected 1 argument, received %d", ErrorBadArgumentCount, len(args))
+	}
+
+	return fmt.Sprintf("%s >= '%s'", args[0], query.TimeRange.From.UTC().Format(time.RFC3339)), nil
+
+}
+
+// Default time filter for SQL based on the ending query time range.
+// It requires one argument, the time column to filter.
+// Example:
+//   $__timeTo(time) => "time < '2006-01-02T15:04:05Z07:00'"
+func macroTimeTo(query *Query, args []string) (string, error) {
+	if len(args) != 1 {
+		return "", fmt.Errorf("%w: expected 1 argument, received %d", ErrorBadArgumentCount, len(args))
+	}
+
+	return fmt.Sprintf("%s <= '%s'", args[0], query.TimeRange.To.UTC().Format(time.RFC3339)), nil
+}
+
+// Default time group for SQL based the given period.
+// This basic example is meant to be customized with more complex periods.
+// It requires two arguments, the column to filter and the period.
+// Example:
+//   $__timeTo(time, month) => "datepart(year, time), datepart(month, time)'"
+func macroTimeGroup(query *Query, args []string) (string, error) {
+	if len(args) != 2 {
+		return "", fmt.Errorf("%w: expected 1 argument, received %d", ErrorBadArgumentCount, len(args))
+	}
+
+	res := ""
+	switch args[1] {
+	case "minute":
+		res += fmt.Sprintf("datepart(minute, %s),", args[0])
+		fallthrough
+	case "hour":
+		res += fmt.Sprintf("datepart(hour, %s),", args[0])
+		fallthrough
+	case "day":
+		res += fmt.Sprintf("datepart(day, %s),", args[0])
+		fallthrough
+	case "month":
+		res += fmt.Sprintf("datepart(month, %s),", args[0])
+		fallthrough
+	case "year":
+		res += fmt.Sprintf("datepart(year, %s)", args[0])
+	}
+
+	return res, nil
+}
+
+// Default macro to return the query table name.
+// Example:
+//   $__table => "my_table"
+func macroTable(query *Query, args []string) (string, error) {
+	return query.Table, nil
+}
+
+// Default macro to return the query column name.
+// Example:
+//   $__column => "my_col"
+func macroColumn(query *Query, args []string) (string, error) {
+	return query.Column, nil
+}
+
+var DefaultMacros Macros = Macros{
+	"timeFilter": macroTimeFilter,
+	"timeFrom":   macroTimeFrom,
+	"timeGroup":  macroTimeGroup,
+	"timeTo":     macroTimeTo,
+	"table":      macroTable,
+	"column":     macroColumn,
+}
+
 func trimAll(s []string) []string {
 	r := make([]string, len(s))
 	for i, v := range s {
@@ -35,6 +133,12 @@ func getMacroRegex(name string) string {
 
 func interpolate(driver Driver, query *Query) (string, error) {
 	macros := driver.Macros()
+	for key, defaultMacro := range DefaultMacros {
+		if _, ok := macros[key]; !ok {
+			// If the driver doesn't define some macro, use the default one
+			macros[key] = defaultMacro
+		}
+	}
 	rawSQL := query.RawSQL
 	for key, macro := range macros {
 		rgx, err := regexp.Compile(getMacroRegex(key))

macros_test.go

@@ -25,6 +25,10 @@ func (h *MockDB) Macros() (macros Macros) {
 			}
 			return "bar", nil
 		},
+		// overwrite a default macro
+		"timeGroup": func(query *Query, args []string) (out string, err error) {
+			return "grouped!", nil
+		},
 	}
 }
 
@@ -33,6 +37,8 @@ func (h *MockDB) Timeout(backend.DataSourceInstanceSettings) time.Duration {
 }
 
 func TestInterpolate(t *testing.T) {
+	tableName := "my_table"
+	tableColumn := "my_col"
 	type test struct {
 		name   string
 		input  string
@@ -49,12 +55,19 @@ func TestInterpolate(t *testing.T) {
 		{input: "select * from $__params(hello) AND $__params(hello)", output: "select * from bar_hello AND bar_hello", name: "same macro multiple times with same param"},
 		{input: "select * from $__params(hello) AND $__params(world)", output: "select * from bar_hello AND bar_world", name: "same macro multiple times with different param"},
 		{input: "select * from $__params(world) AND $__foo() AND $__params(hello)", output: "select * from bar_world AND bar AND bar_hello", name: "different macros with different params"},
+		{input: "select * from foo where $__timeFilter(time)", output: "select * from foo where time >= '0001-01-01T00:00:00Z' AND time <= '0001-01-01T00:00:00Z'", name: "default timeFilter"},
+		{input: "select * from foo where $__timeTo(time)", output: "select * from foo where time <= '0001-01-01T00:00:00Z'", name: "default timeTo macro"},
+		{input: "select * from foo where $__timeFrom(time)", output: "select * from foo where time >= '0001-01-01T00:00:00Z'", name: "default timeFrom macro"},
+		{input: "select * from foo where $__timeGroup(time,minute)", output: "select * from foo where grouped!", name: "overriden timeGroup macro"},
+		{input: "select $__column from $__table", output: "select my_col from my_table", name: "table and column macros"},
 	}
 	for i, tc := range tests {
 		driver := MockDB{}
 		t.Run(fmt.Sprintf("[%d/%d] %s", i+1, len(tests), tc.name), func(t *testing.T) {
 			query := &Query{
 				RawSQL: tc.input,
+				Table:  tableName,
+				Column: tableColumn,
 			}
 			interpolatedQuery, err := interpolate(&driver, query)
 			require.Nil(t, err)