mgx

README

mgx

Extension for Golang MongoDB driver.

It allows you to work with quries and pipelines in form of JSON, because it is easier to read and you can copy and paste it between Mongo Atlas/Compass/MongoSH.

Usage

filter := mgx.MustParseQuery(`{
        "id" : "$1",
        "start": { "$lte": "$2" },
        "$or": [
            { "end": { "$exists": false } },
            { "end": null },
            { "end": { "$gte": "$2" } }
        ]}`,
    "$1", id,
    "$2", date,
)

or

var someQuery = mgx.MustParseQuery(`{
        "id" : "$1",
        "start": { "$lte": "$2" },
        "$or": [
            { "end": { "$exists": false } },
            { "end": null },
            { "end": { "$gte": "$2" } }
        ]}`)

func QueryData(id string, date time.Time) {
    filter, err := mgx.MarshalQuery(someQuery, "$1", id, "$2", date)
    ...
}

Install

go get github.com/hummerd/mgx@latest

Mongo Text Query Language

The query package allows you to write mongo filters in human friendly form.

The query package is very-very experimental - use it on you own risk (or better do not)!

var someQuery = query.MustPrepare(`start >= "$startDate"`)

func QueryData(ctx context.Context, date time.Time) {
    filter, err := someQuery.Compile(someQuery, "$startDate",  date)
    defer filter.Discard()
    ...

    cur, err := collection.Find(ctx, filter)
}

Examples:

// simple example.
// comparison operators: =, !=, <, >, <=, >=.
// logical operators: `and`, `or`.  
var someQuery = query.MustCompile(`
       name = "some" AND
       age >= 30
    `)

func QueryStaticFilter(ctx context.Context) {
    cur, err := collection.Find(ctx, someQuery)
}

// same field may be used multiple times (unlike in JSON).
var someQuery = query.MustCompile(`
       age >= 30 AND
       age <= 40
    `)

func QueryStaticFilter(ctx context.Context) {
    cur, err := collection.Find(ctx, someQuery)
}

// brackets with `and` and `or` operators.
var someQuery = query.MustCompile(`
       (name = "Dima" OR name = "John") AND
       age > 25
    `)

func QueryStaticFilter(ctx context.Context) {
    cur, err := collection.Find(ctx, someQuery)
}

// regexp and date type.
var someQuery = query.MustCompile(`
       name $regex /a.*/i AND
       birth = ISODate('2022-01-01T00:00:00Z')
    `)

func QueryStaticFilter(ctx context.Context) {
    cur, err := collection.Find(ctx, someQuery)
}

// $in operator.
var someQuery = query.MustCompile(`
       age $in [18,27,33]
    `)

func QueryStaticFilter(ctx context.Context) {
    cur, err := collection.Find(ctx, someQuery)
}

// nested fields and $exists clause.
var someQuery = query.MustCompile(`
       address.street $exists true
    `)

func QueryStaticFilter(ctx context.Context) {
    cur, err := collection.Find(ctx, someQuery)
}

Documentation

Index

• func MustParseQuery(query string, keyValues ...interface{}) interface{}
• func ParseQuery(query string, keyValues ...interface{}) (interface{}, error)
• type MarshalledQuery
  • func MarshalQuery(query interface{}, params ...interface{}) (MarshalledQuery, error)
  • func NewMarshalledQuery(bsonData *bytes.Buffer) MarshalledQuery
  • func (q MarshalledQuery) Close() error
  • func (q MarshalledQuery) MarshalBSON() ([]byte, error)
  • func (q MarshalledQuery) MarshalBSONValue() (bsontype.Type, []byte, error)
• type QueryEncoder
  • func NewQueryEncoder(params map[string]interface{}) QueryEncoder
  • func (enc QueryEncoder) EncodePipeline(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error
  • func (enc QueryEncoder) EncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error

Functions

func MustParseQuery

func MustParseQuery(query string, keyValues ...interface{}) interface{}

MustParseQuery creates bson request from specified JSON and parameters. Same as ParseQuery but panics if there was an error during parsing JSON..

func ParseQuery

func ParseQuery(query string, keyValues ...interface{}) (interface{}, error)

ParseQuery creates bson document from specified JSON and specified parameters.ParseQuery uses internal cache so query will be decoded only once, and then cached values will be used.

Types

type MarshalledQuery

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

func MarshalQuery

func MarshalQuery(query interface{}, params ...interface{}) (MarshalledQuery, error)

MarshalQuery creates serialized representation of query or pipeline.

func NewMarshalledQuery

func NewMarshalledQuery(bsonData *bytes.Buffer) MarshalledQuery

func (MarshalledQuery) Close

func (q MarshalledQuery) Close() error

Close returns marshal buffer to internal pool and returns nil.

func (MarshalledQuery) MarshalBSON

func (q MarshalledQuery) MarshalBSON() ([]byte, error)

MarshalBSON just returns marshalled bson document.

func (MarshalledQuery) MarshalBSONValue

func (q MarshalledQuery) MarshalBSONValue() (bsontype.Type, []byte, error)

MarshalBSONValue returns marshalled bson document as bson value. We use bson array here because it is the only type that can be used as pipeline.

type QueryEncoder

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

func NewQueryEncoder

func NewQueryEncoder(params map[string]interface{}) QueryEncoder

func (QueryEncoder) EncodePipeline

func (enc QueryEncoder) EncodePipeline(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error

func (QueryEncoder) EncodeValue

func (enc QueryEncoder) EncodeValue(ec bsoncodec.EncodeContext, vw bsonrw.ValueWriter, val reflect.Value) error