document and test cases for granularity

builder/granularity/duration.go

@@ -4,23 +4,29 @@ import (
 	"time"
 )
 
+// Duration granularity is specified as an exact duration in milliseconds and timestamps are returned as UTC.
+// Duration granularity values are in millis.
+// https://druid.apache.org/docs/latest/querying/granularities.html#duration-granularities
 type Duration struct {
 	Base
 	Duration time.Duration `json:"duration,omitempty"`
 	Origin   time.Time     `json:"origin,omitempty"`
 }
 
+// NewDuration creates new Duration.
 func NewDuration() *Duration {
 	d := &Duration{}
 	d.SetType("duration")
 	return d
 }
 
+// SetDuration sets duration.
 func (d *Duration) SetDuration(duration time.Duration) *Duration {
 	d.Duration = duration
 	return d
 }
 
+// SetOrigin sets the origin
 func (d *Duration) SetOrigin(origin time.Time) *Duration {
 	d.Origin = origin
 	return d

builder/granularity/duration_test.go

@@ -0,0 +1,21 @@
+package granularity
+
+import (
+	"github.com/grafadruid/go-druid/builder/testutil"
+	"github.com/stretchr/testify/assert"
+	"testing"
+	"time"
+)
+
+func TestNewDuration(t *testing.T) {
+	d := NewDuration()
+	d.SetDuration(time.Minute)
+	d.SetOrigin(time.Unix(1613779200, 0))
+
+	expected := []byte(`{"type":"duration","duration":60000000000,"origin":"2021-02-19T16:00:00-08:00"}`)
+
+	built, err := Load(expected)
+	assert.Nil(t, err)
+
+	testutil.Compare(t, expected, d, built)
+}

builder/granularity/granularity.go

@@ -8,19 +8,23 @@ import (
 	"github.com/grafadruid/go-druid/builder"
 )
 
+// Base is the base for granularity.
 type Base struct {
 	Typ string `json:"type,omitempty"`
 }
 
+// SetType sets type.
 func (b *Base) SetType(typ string) *Base {
 	b.Typ = typ
 	return b
 }
 
+// Type returns the type.
 func (b *Base) Type() builder.ComponentType {
 	return b.Typ
 }
 
+// Load converts the druid native query to builder.Granularity
 func Load(data []byte) (builder.Granularity, error) {
 	var g builder.Granularity
 	var t struct {

builder/granularity/granularity_test.go

@@ -9,7 +9,7 @@ import (
 func TestLoadUnsupportedType(t *testing.T) {
 	assert := assert.New(t)
 
-	f, err := Load([]byte("{\"type\": \"blahblahType\"}"))
+	f, err := Load([]byte(`{"type": "_not_such_Type"}`))
 
 	assert.Nil(f, "filter should be nil")
 	assert.NotNil(err, "error should not be nil")

builder/granularity/period.go

@@ -6,29 +6,36 @@ import (
 	"github.com/grafadruid/go-druid/builder/types"
 )
 
+// Period granularity is specified as arbitrary period combinations of years, months, weeks, hours, minutes and seconds
+// (e.g. P2W, P3M, PT1H30M, PT0.750S) in ISO8601 format.
+// https://druid.apache.org/docs/latest/querying/granularities.html#period-granularities
 type Period struct {
 	Base
 	Period   time.Duration      `json:"period,omitempty"`
 	Origin   time.Time          `json:"origin,omitempty"`
 	TimeZone types.DateTimeZone `json:"timeZone,omitempty"`
 }
 
+// NewPeriod creates a Period type.
 func NewPeriod() *Period {
 	p := &Period{}
 	p.SetType("period")
 	return p
 }
 
+// SetPeriod sets period.
 func (p *Period) SetPeriod(period time.Duration) *Period {
 	p.Period = period
 	return p
 }
 
+// SetOrigin sets origin.
 func (p *Period) SetOrigin(origin time.Time) *Period {
 	p.Origin = origin
 	return p
 }
 
+// SetTimeZone sets timezone.
 func (p *Period) SetTimeZone(timeZone types.DateTimeZone) *Period {
 	p.TimeZone = timeZone
 	return p

builder/granularity/period_test.go

@@ -0,0 +1,22 @@
+package granularity
+
+import (
+	"github.com/grafadruid/go-druid/builder/testutil"
+	"github.com/stretchr/testify/assert"
+	"testing"
+	"time"
+)
+
+func TestNewPeriod(t *testing.T) {
+	p := NewPeriod()
+	p.SetOrigin(time.Unix(1613779200, 0))
+	p.SetTimeZone(`America/Chicago`)
+	p.SetPeriod(time.Minute)
+
+	expected := []byte(`{"type":"period","period":60000000000,"origin":"2021-02-19T16:00:00-08:00","timeZone":"America/Chicago"}`)
+
+	built, err := Load(expected)
+	assert.Nil(t, err)
+
+	testutil.Compare(t, expected, p, built)
+}

builder/granularity/simple.go

@@ -2,6 +2,8 @@ package granularity
 
 import "github.com/grafadruid/go-druid/builder"
 
+// Simple granularities are specified as a string and bucket timestamps by their UTC time.
+// https://druid.apache.org/docs/latest/querying/granularities.html#simple-granularities
 type Simple string
 
 const (
@@ -19,15 +21,18 @@ const (
 	Year                 = "year"
 )
 
+// Type sets the type to Simple
 func (s *Simple) Type() builder.ComponentType {
 	return "simple"
 }
 
+// SetGranularity sets granularity.
 func (s *Simple) SetGranularity(g Simple) *Simple {
 	*s = g
 	return s
 }
 
+// NewSimple creates a Simple type.
 func NewSimple() *Simple {
 	var s Simple
 	return &s

builder/granularity/simple_test.go

@@ -0,0 +1,18 @@
+package granularity
+
+import (
+	"github.com/grafadruid/go-druid/builder/testutil"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+func TestNewSimple(t *testing.T) {
+	expected := []byte(`"all"`)
+	s := NewSimple()
+	s.SetGranularity("all")
+
+	built, err := Load(expected)
+	assert.Nil(t, err)
+
+	testutil.Compare(t, expected, s, built)
+}

builder/testutil/validate.go

@@ -0,0 +1,25 @@
+package testutil
+
+import (
+	"encoding/json"
+	"github.com/stretchr/testify/assert"
+	"testing"
+)
+
+// Compare compares the builder type b to expected and also built to expected.
+// json(b) == json(built) == expected
+func Compare(t *testing.T, expected []byte, b interface{}, built interface{}) {
+	// convert builder b to JSON so we can compare the JSON of builder to expected JSON.
+	js, err := json.Marshal(b)
+	assert.Nil(t, err)
+
+	assert.Equal(t, js, expected)
+
+	assert.Equal(t, b, built)
+
+	// convert built (which is generated from expected JSON) to JSON so it can also
+	// be compared with expected.
+	jbuilt, err := json.Marshal(built)
+	assert.Nil(t, err)
+	assert.Equal(t, jbuilt, expected)
+}