rql

The RQL JSON API allows frontend developers to construct complex queries using a subset of MongoDB syntax. The top-level JSON object accepts the following optional fields:

• offset: Integer $\ge 0$. Defaults to 0.
• limit: Integer $> 0$ and $\le$ LimitMaxValue. Defaults to DefaultLimit.
• sort: An array of strings ([]string). Use + for ascending (default) and - for descending. Example: ["name", "-age"].
• select: An array of strings ([]string) representing columns to include in the result.
• filter: An object defining the WHERE clause conditions.

Filters are translated into SQL WHERE clauses. RQL uses logical AND for object properties and logical OR for array elements (via the $or key).

Equality and Predicates

• Simple Equality: {"field": value} $\rightarrow$ field = ?
• Predicate Objects: {"field": {"$predicate": value}} $\rightarrow$ field <operator> ?. Multiple predicates in one object are joined by AND.

Supported Predicates

• $eq, $neq: All types.
• $gt, $lt, $gte, $lte: Numbers, strings, and timestamps.
• $like: Strings only.

Logical OR

Use the $or key with an array of condition objects to create disjunctions.

Example Input:

{
  "$or": [
    { "city": "TLV" },
    { "zip": { "$gte": 49800, "$lte": 57080 } }
  ]
}

Resulting SQL Logic: city = ? OR (zip >= ? AND zip <= ?)

{
  "age": {
    "$gt": 20,
    "$lt": 30
  }
}

The rql.Param object is designed to be passed directly into popular Go ORMs and database drivers. Use params.FilterExp as the query expression and params.FilterArgs... as the arguments.

GORM

err = db.Where(p.FilterExp, p.FilterArgs).Offset(p.Offset).Limit(p.Limit).Order(p.Sort).Find(&users).Error

Entgo.io

users, err = client.User.Query().Where(func(s *sql.Selector) {
    s.Where(sql.ExprP(p.FilterExp, p.FilterArgs...))
}).Limit(p.Limit).Offset(p.Offset).All(ctx)

XORM

err = engine.Where(p.FilterExp, p.FilterArgs...).Limit(p.Limit, p.Offset).OrderBy(p.Sort).Find(&users)

Go-PG/PG

err = db.Model(&users).Where(p.FilterExp, p.FilterArgs).Offset(p.Offset).Limit(p.Limit).Order(p.Sort).Select()

To enable dynamic querying for a resource, add rql struct tags to your model definition. Use the filter tag to allow a field to be used in WHERE clauses and the sort tag to allow it to be used in ORDER BY clauses.

You can also specify a custom time layout for time.Time fields using the layout option within the tag.

type User struct {
	ID          uint      `gorm:"primary_key" rql:"filter,sort"` 
	Admin       bool      `rql:"filter"` 
	Name        string    `rql:"filter"` 
	AddressName string    `rql:"filter"` 
	CreatedAt   time.Time `rql:"filter,sort"` 
	// Custom time layout
	T1          time.Time `rql:"filter,layout=UnixDate"` 
	T2          time.Time `rql:"filter,layout=2006-01-02 15:04"` 
}

To use RQL, you must first create a parser using rql.MustNewParser. You provide an rql.Config which defines the model being queried, the field separator (e.g., . for nested fields), and the maximum allowed value for the limit parameter to prevent resource exhaustion.

Fields in your Go structs must be decorated with rql tags to indicate which fields are allowed for filter and sort operations.

var QueryParser = rql.MustNewParser(rql.Config{
	Model:    	User{},
	FieldSep: 	".",
	LimitMaxValue: 	25,
})

type User struct {
	ID          uint      `gorm:"primary_key" rql:"filter,sort"`
	Admin       bool      `rql:"filter"`
	Name        string    `rql:"filter"`
	Address     string    `rql:"filter"`
	CreatedAt   time.Time `rql:"filter,sort"`
}

RQL can parse query data from either a URL query string or the request body. If using a URL query string, the data is typically expected to be a Base64 encoded JSON blob. The Parse method returns an rql.Params object containing the parsed FilterExp, FilterArgs, Sort, Limit, and Offset which can be passed directly to a database driver like GORM.

func getDBQuery(r *http.Request) (*rql.Params, error) {
	var (
		b   []byte
		err error
	)
	if v := r.URL.Query().Get("query"); v != "" {
		b, err = base64.StdEncoding.DecodeString(v)
	} else {
		b, err = ioutil.ReadAll(io.LimitReader(r.Body, 1<<12))
	}
	if err != nil {
		return nil, err
	}
	return QueryParser.Parse(b)
}

RQL uses two primary data structures to represent the lifecycle of a query:

1. Query: The raw, decoded representation of the user's JSON input. It uses high-level types like []string for Select and map[string]interface{} for Filter.
2. Params: The processed, database-ready output. It flattens the Filter map into a single FilterExp string and a slice of FilterArgs for safe parameter binding.

To parse RQL queries, you must first create a Parser instance using a Config object. The Config defines the model (struct) being queried, limits, and field mapping rules.

• NewParser(c Config): Returns a *Parser and an error. Use this for standard error handling.
• MustNewParser(c Config): Returns a *Parser but panics if the configuration is invalid. This is useful for initializing global parser instances during application startup.

// Example initialization
config := rql.Config{
    Model: User{}, // Your data model
    LimitMaxValue: 100,
}

parser, err := rql.NewParser(config)
if err != nil {
    log.Fatal(err)
}

To use RQL, you must create a parser using rql.New(rql.Config) or rql.MustNew(rql.Config).

• rql.New returns an error if the configuration is invalid.
• rql.MustNew panics if the configuration is invalid (useful for global variable initialization).

Key configuration options in rql.Config:

• Model: The struct representing the resource being queried.
• ColumnFn: A function to map struct field names to database column names (e.g., gorm.ToDBName).
• Log: A logger function used during the build stage.
• DefaultLimit: The fallback limit if the user doesn't provide one.
• LimitMaxValue: The maximum allowed value for the limit parameter to prevent resource exhaustion.

var Parser = rql.MustNew(rql.Config{
	Model:         User{},
	ColumnFn:      gorm.ToDBName,
	Log:           logrus.Printf,
	DefaultLimit:  100,
	LimitMaxValue: 200,
})

When parsing fails due to invalid JSON or schema violations (e.g., filtering on a non-filterable field), the parser returns a *ParseError.

ParseError is a custom error type that wraps the underlying cause. You can check for it to distinguish between transport errors and query validation errors.