README

gojsonq-logo

Build Status Project status Go Report Card Coverage Status GoDoc License

A simple Go package to Query over JSON Data. It provides simple, elegant and fast ODM like API to access, query JSON document

Installation

Install the package using

$ go get github.com/thedevsaddam/gojsonq
// or
$ go get gopkg.in/thedevsaddam/gojsonq.v2

Usage

To use the package import it in your *.go code

import "github.com/thedevsaddam/gojsonq"
// or
import "gopkg.in/thedevsaddam/gojsonq.v2"

Let's see a quick example:

See in playground

package main

import "github.com/thedevsaddam/gojsonq"

func main() {
	const json = `{"name":{"first":"Tom","last":"Hanks"},"age":61}`
	name := gojsonq.New().JSONString(json).Find("name.first")
	println(name.(string)) // Tom
}

Another example:

See in playground

package main

import (
	"fmt"

	"github.com/thedevsaddam/gojsonq"
)

func main() {
	const json = `{"city":"dhaka","type":"weekly","temperatures":[30,39.9,35.4,33.5,31.6,33.2,30.7]}`
	avg := gojsonq.New().JSONString(json).From("temperatures").Avg()
	fmt.Printf("Average temperature: %.2f", avg) // 33.471428571428575
}

You can query your document using the various query methods such as Find, First, Nth, Pluck, Where, OrWhere, WhereIn, WhereStartsWith, WhereEndsWith, WhereContains, Sort, GroupBy, SortBy and so on. Also you can aggregate data after query using Avg, Count, Max, Min, Sum etc.

Find more query API in Wiki page

Bugs and Issues

If you encounter any bugs or issues, feel free to open an issue at github.

Also, you can shoot me an email to mailto:thedevsaddam@gmail.com for hugs or bugs.

Credit

Special thanks to Nahid Bin Azhar for the inspiration and guidance for the package. Thanks to Ahmed Shamim Hasan Shaon for his support from the very beginning.

Contributors

Contribution

If you are interested to make the package better please send pull requests or create an issue so that others can fix. Read the contribution guide here

License

The gojsonq is an open-source software licensed under the MIT License.

Documentation

Overview

Package gojsonq provides a simple, elegant and fast ODM like API to access/query JSON document.

JSON document can be read from file, string or io.Reader. Accessing the value of json property or querying document is simple as the example below:

 package main

 import "github.com/thedevsaddam/gojsonq"

 const json = `{"name":{"first":"Tom","last":"Hanks"},"age":61}`

 func main() {
	 name := gojsonq.New().JSONString(json).Find("name.first")
	 println(name.(string)) // Tom
 }

For more details, see the documentation and examples.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Decoder

type Decoder interface {
	Decode(data []byte, v interface{}) error
}

Decoder provide contract to decode JSON using custom decoder

type DefaultDecoder

type DefaultDecoder struct{}

DefaultDecoder use json.Unmarshal to decode JSON

func (*DefaultDecoder) Decode

func (u *DefaultDecoder) Decode(data []byte, v interface{}) error

Decode decodes using json.Unmarshal

type JSONQ

type JSONQ struct {
	// contains filtered or unexported fields
}

JSONQ describes a JSONQ type which contains all the state

func New

func New(options ...OptionFunc) *JSONQ

New returns a new instance of JSONQ

func (*JSONQ) Avg

func (j *JSONQ) Avg(property ...string) float64

Avg returns average of values from array or from map using property

func (*JSONQ) Copy

func (j *JSONQ) Copy() *JSONQ

Copy returns a new fresh instance of JSONQ with the original copy of data so that you can do concurrent operation on the same data without being decoded again

func (*JSONQ) Count

func (j *JSONQ) Count() int

Count returns the number of total items. This could be a length of list/array/map

func (*JSONQ) Distinct

func (j *JSONQ) Distinct(property string) *JSONQ

Distinct builds distinct value using provided attribute/column/property

func (*JSONQ) Error

func (j *JSONQ) Error() error

Error returns first occurred error

func (*JSONQ) Errors

func (j *JSONQ) Errors() []error

Errors returns list of all errors

func (*JSONQ) File

func (j *JSONQ) File(filename string) *JSONQ

File read the json content from physical file

func (*JSONQ) Find

func (j *JSONQ) Find(path string) interface{}

Find returns the result of a exact matching path

func (*JSONQ) FindR

func (j *JSONQ) FindR(path string) (*Result, error)

FindR returns the result as Result instance from the exact matching path

func (*JSONQ) First

func (j *JSONQ) First() interface{}

First returns the first element of a list

func (*JSONQ) FirstR

func (j *JSONQ) FirstR() (*Result, error)

FirstR returns the first element of a list as Result instance

func (*JSONQ) From

func (j *JSONQ) From(node string) *JSONQ

From seeks the json content to provided node. e.g: "users.[0]" or "users.[0].name"

func (*JSONQ) FromString

func (j *JSONQ) FromString(str string) *JSONQ

FromString reads the content from valid json/xml/csv/yml string

func (*JSONQ) Get

func (j *JSONQ) Get() interface{}

Get return the result

func (*JSONQ) GetR

func (j *JSONQ) GetR() (*Result, error)

GetR return the query results as Result instance

func (*JSONQ) GroupBy

func (j *JSONQ) GroupBy(property string) *JSONQ

GroupBy builds a chunk of exact matched data in a group list using provided attribute/column/property

func (*JSONQ) JSONString

func (j *JSONQ) JSONString(json string) *JSONQ

JSONString reads the json content from valid json string // Deprecated: this method will remove in next major release

func (*JSONQ) Last

func (j *JSONQ) Last() interface{}

Last returns the last element of a list

func (*JSONQ) LastR

func (j *JSONQ) LastR() (*Result, error)

LastR returns the last element of a list as Result instance

func (*JSONQ) Limit

func (j *JSONQ) Limit(limit int) *JSONQ

Limit limits the number of records in result

func (*JSONQ) Macro

func (j *JSONQ) Macro(operator string, fn QueryFunc) *JSONQ

Macro adds a new query func to the JSONQ

func (*JSONQ) Max

func (j *JSONQ) Max(property ...string) float64

Max returns maximum value from array or from map using property

func (*JSONQ) Min

func (j *JSONQ) Min(property ...string) float64

Min returns minimum value from array or from map using property

func (*JSONQ) More

func (j *JSONQ) More() *JSONQ

More provides the functionalities to query over the resultant data. See https://github.com/thedevsaddam/gojsonq/wiki/Queries#More

func (*JSONQ) Nth

func (j *JSONQ) Nth(index int) interface{}

Nth returns the nth element of a list

func (*JSONQ) NthR

func (j *JSONQ) NthR(index int) (*Result, error)

NthR returns the nth element of a list as Result instance

func (*JSONQ) Offset

func (j *JSONQ) Offset(offset int) *JSONQ

Offset skips the number of records in result

func (*JSONQ) Only

func (j *JSONQ) Only(properties ...string) interface{}

Only collects the properties from a list of object

func (*JSONQ) OnlyR

func (j *JSONQ) OnlyR(properties ...string) (*Result, error)

OnlyR collects the properties from a list of object and return as Result instance

func (*JSONQ) OrWhere

func (j *JSONQ) OrWhere(key, cond string, val interface{}) *JSONQ

OrWhere builds an OrWhere clause, basically it's a group of AND clauses

func (*JSONQ) Out

func (j *JSONQ) Out(v interface{})

Out write the queried data to defined custom type

func (*JSONQ) Pluck

func (j *JSONQ) Pluck(property string) interface{}

Pluck build an array of vlaues form a property of a list of objects

func (*JSONQ) PluckR

func (j *JSONQ) PluckR(property string) (*Result, error)

PluckR build an array of vlaues form a property of a list of objects and return as Result instance

func (*JSONQ) Reader

func (j *JSONQ) Reader(r io.Reader) *JSONQ

Reader reads the json content from io reader

func (*JSONQ) Reset

func (j *JSONQ) Reset() *JSONQ

Reset resets the current state of JSON instance and make a fresh object with the original json content

func (*JSONQ) Select

func (j *JSONQ) Select(properties ...string) *JSONQ

Select use for selection of the properties from query result

func (*JSONQ) Sort

func (j *JSONQ) Sort(order ...string) *JSONQ

Sort sorts an array default ascending order, pass "desc" for descending order

func (*JSONQ) SortBy

func (j *JSONQ) SortBy(order ...string) *JSONQ

SortBy sorts an array default ascending order, pass "desc" for descending order

func (*JSONQ) String

func (j *JSONQ) String() string

String satisfies stringer interface

func (*JSONQ) Sum

func (j *JSONQ) Sum(property ...string) float64

Sum returns sum of values from array or from map using property

func (*JSONQ) Where

func (j *JSONQ) Where(key, cond string, val interface{}) *JSONQ

Where builds a where clause. e.g: Where("name", "contains", "doe")

func (*JSONQ) WhereContains

func (j *JSONQ) WhereContains(key string, val interface{}) *JSONQ

WhereContains satisfies Where clause which contains provided value(string)

func (*JSONQ) WhereEndsWith

func (j *JSONQ) WhereEndsWith(key string, val interface{}) *JSONQ

WhereEndsWith satisfies Where clause which ends with provided value(string)

func (*JSONQ) WhereEqual

func (j *JSONQ) WhereEqual(key string, val interface{}) *JSONQ

WhereEqual is an alias of Where("key", "=", val)

func (*JSONQ) WhereIn

func (j *JSONQ) WhereIn(key string, val interface{}) *JSONQ

WhereIn is an alias for where("key", "in", []string{"a", "b"})

func (*JSONQ) WhereLenEqual

func (j *JSONQ) WhereLenEqual(key string, val interface{}) *JSONQ

WhereLenEqual is an alias of Where("key", "leneq", val)

func (*JSONQ) WhereLenNotEqual

func (j *JSONQ) WhereLenNotEqual(key string, val interface{}) *JSONQ

WhereLenNotEqual is an alias of Where("key", "lenneq", val)

func (*JSONQ) WhereNil

func (j *JSONQ) WhereNil(key string) *JSONQ

WhereNil is an alias of Where("key", "=", nil)

func (*JSONQ) WhereNotEqual

func (j *JSONQ) WhereNotEqual(key string, val interface{}) *JSONQ

WhereNotEqual is an alias of Where("key", "!=", val)

func (*JSONQ) WhereNotIn

func (j *JSONQ) WhereNotIn(key string, val interface{}) *JSONQ

WhereNotIn is an alias for where("key", "notIn", []string{"a", "b"})

func (*JSONQ) WhereNotNil

func (j *JSONQ) WhereNotNil(key string) *JSONQ

WhereNotNil is an alias of Where("key", "!=", nil)

func (*JSONQ) WhereStartsWith

func (j *JSONQ) WhereStartsWith(key string, val interface{}) *JSONQ

WhereStartsWith satisfies Where clause which starts with provided value(string)

func (*JSONQ) WhereStrictContains

func (j *JSONQ) WhereStrictContains(key string, val interface{}) *JSONQ

WhereStrictContains satisfies Where clause which contains provided value(string). This is case sensitive

func (*JSONQ) Writer

func (j *JSONQ) Writer(w io.Writer)

Writer write the queried data to a io.Writer

type OptionFunc

type OptionFunc func(*JSONQ) error

OptionFunc represents a contract for option func, it basically set options to jsonq instance options

func SetDecoder

func SetDecoder(u Decoder) OptionFunc

SetDecoder take a custom decoder to decode JSON

func SetSeparator

func SetSeparator(s string) OptionFunc

SetSeparator set custom separator for traversing child node, default separator is DOT (.)

type QueryFunc

type QueryFunc func(x, y interface{}) (bool, error)

QueryFunc describes a conditional function which perform comparison

type Result

type Result struct {
	// contains filtered or unexported fields
}

Result represent custom type

func NewResult

func NewResult(v interface{}) *Result

NewResult return an instance of Result

func (*Result) Bool

func (r *Result) Bool() (bool, error)

Bool assert the result to boolean value

func (*Result) BoolSlice

func (r *Result) BoolSlice() ([]bool, error)

BoolSlice assert the result to []bool

func (*Result) Duration

func (r *Result) Duration() (time.Duration, error)

Duration assert the result to time.Duration

func (*Result) DurationSlice

func (r *Result) DurationSlice() ([]time.Duration, error)

DurationSlice assert the result to []time.Duration

func (*Result) Float32

func (r *Result) Float32() (float32, error)

Float32 assert the result to float32

func (*Result) Float32Slice

func (r *Result) Float32Slice() ([]float32, error)

Float32Slice assert the result to []float32

func (*Result) Float64

func (r *Result) Float64() (float64, error)

Float64 assert the result to 64

func (*Result) Float64Slice

func (r *Result) Float64Slice() ([]float64, error)

Float64Slice assert the result to []float64

func (*Result) Int

func (r *Result) Int() (int, error)

Int assert the result to int

func (*Result) Int16

func (r *Result) Int16() (int16, error)

Int16 assert the result to int16

func (*Result) Int16Slice

func (r *Result) Int16Slice() ([]int16, error)

Int16Slice assert the result to []int16

func (*Result) Int32

func (r *Result) Int32() (int32, error)

Int32 assert the result to int32

func (*Result) Int32Slice

func (r *Result) Int32Slice() ([]int32, error)

Int32Slice assert the result to []int32

func (*Result) Int64

func (r *Result) Int64() (int64, error)

Int64 assert the result to int64

func (*Result) Int64Slice

func (r *Result) Int64Slice() ([]int64, error)

Int64Slice assert the result to []int64

func (*Result) Int8

func (r *Result) Int8() (int8, error)

Int8 assert the result to int8

func (*Result) Int8Slice

func (r *Result) Int8Slice() ([]int8, error)

Int8Slice assert the result to []int8

func (*Result) IntSlice

func (r *Result) IntSlice() ([]int, error)

IntSlice assert the result to []int

func (*Result) Nil

func (r *Result) Nil() bool

Nil check the query has result or not

func (*Result) String

func (r *Result) String() (string, error)

String assert the result to String

func (*Result) StringSlice

func (r *Result) StringSlice() ([]string, error)

StringSlice assert the result to []string

func (*Result) Time

func (r *Result) Time(layout string) (time.Time, error)

Time assert the result to time.Time

func (*Result) TimeSlice

func (r *Result) TimeSlice(layout string) ([]time.Time, error)

TimeSlice assert the result to []time.Time

func (*Result) Uint

func (r *Result) Uint() (uint, error)

Uint assert the result to uint

func (*Result) Uint16

func (r *Result) Uint16() (uint16, error)

Uint16 assert the result to uint16

func (*Result) Uint16Slice

func (r *Result) Uint16Slice() ([]uint16, error)

Uint16Slice assert the result to []uint16

func (*Result) Uint32

func (r *Result) Uint32() (uint32, error)

Uint32 assert the result to uint32

func (*Result) Uint32Slice

func (r *Result) Uint32Slice() ([]uint32, error)

Uint32Slice assert the result to []uint32

func (*Result) Uint64

func (r *Result) Uint64() (uint64, error)

Uint64 assert the result to uint64

func (*Result) Uint64Slice

func (r *Result) Uint64Slice() ([]uint64, error)

Uint64Slice assert the result to []uint64

func (*Result) Uint8

func (r *Result) Uint8() (uint8, error)

Uint8 assert the result to uint8

func (*Result) Uint8Slice

func (r *Result) Uint8Slice() ([]uint8, error)

Uint8Slice assert the result to []uint8

func (*Result) UintSlice

func (r *Result) UintSlice() ([]uint, error)

UintSlice assert the result to []uint