query

Query

Query is an adaptor of http query to expressions. Check adapters to convert it to sql or other expressions.

go get github.com/rakunlabs/query

Usage

Parse url and extract query parameters with RAW, give to query.Parse to convert it to expression.
Use an adapter to convert it to sql or other expressions.

urlStr := "http://example.com?name=foo,bar|nick=bar&age[lt]=1&_sort=-age&_limit=10&_offset=5&_fields=id,name"
parsedURL, err := url.Parse(urlStr)
// ...
query, err := query.Parse(parsedURL.RawQuery)
// ...
sql, params, err := adaptergoqu.Select(query, goqu.From("test")).ToSQL()
// ...

// Output:
// SQL: SELECT "id", "name" FROM "test" WHERE ((("name" IN (?, ?)) OR ("nick" = ?)) AND ("age" < ?)) ORDER BY "age" DESC LIMIT ? OFFSET ?
// Params: [foo bar bar 1 10 5]

If some value separated by , it will be converted to IN operator.
There are a list of [ ] operators that can be used in the query string:
eq, ne, gt, lt, gte, lte, like, ilike, nlike, nilike, in, nin, is, not, kv, jin, njin

_limit and _offset are used to limit the number of rows returned. 0 limit means no limit.
_fields is used to select the fields to be returned, comma separated.
_sort is used to sort the result set, can be prefixed with - to indicate descending order and comma separated to indicate multiple fields.
[] empty operator means in operator.
Paranteses () can be used to group expressions, | is used for OR operation and & is used for AND operation.

Parse Options

Options can be passed to query.Parse to customize parsing behavior:

WithKeyOperator

Sets the default operator for a specific key when no bracket operator is specified. This allows you to write cleaner query strings without explicit [op] brackets.

// Without WithKeyOperator: name=foo → name[eq]=foo (default)
// With WithKeyOperator:    name=foo → name[like]=foo
q, err := query.Parse("name=foo", query.WithKeyOperator("name", query.OperatorLike))

// Useful for JSONB array columns:
// tags=admin,editor → tags ?| array['admin','editor']
q, err := query.Parse("tags=admin,editor", query.WithKeyOperator("tags", query.OperatorJIn))

Explicit bracket operators always take priority over WithKeyOperator. If the query contains name[eq]=foo, the eq operator is used regardless of the WithKeyOperator setting.

WithKeyValueTransform

Sets a value transform function for a specific key. The function is applied to the raw value string before parsing, regardless of whether a bracket operator is present.

// Wrap value with % for LIKE queries
q, err := query.Parse("name=foo",
    query.WithKeyOperator("name", query.OperatorLike),
    query.WithKeyValueTransform("name", func(v string) string {
        return "%" + v + "%"
    }),
)
// Result: name[like]=%foo%
// SQL:    name LIKE '%foo%'

This also works with explicit bracket operators:

// name[ilike]=foo → name[ilike]=%foo%
q, err := query.Parse("name[ilike]=foo",
    query.WithKeyValueTransform("name", func(v string) string {
        return "%" + v + "%"
    }),
)

Validation

query.WithField is used to validate the field names.

• WithNotIn is used to validate the field names that are not allowed.
• WithIn is used to validate the field names that are allowed.
• WithNotAllowed is used to validate the field names totally not allowed.

query.WithValues is used to validate the values of the fields.

• WithNotIn is used to validate the values that are not allowed.
• WithIn is used to validate the values that are allowed.
• WithNotAllowed is used to validate the values totally not allowed.

query.WithValue is used to validate the values of the fields.

• WithRequired is used to validate the values that are required.
• WithNotEmpty is used to validate the values that are not empty.
• WithNotIn is used to validate the values that are not allowed.
• WithIn is used to validate the values that are allowed.
• WithNotAllowed is used to validate the value that are not allowed.
• WithOperator is used to validate the operator that is allowed.
• WithNotOperator is used to validate the operator that is not allowed.
• WithMax is used to validate the maximum of value, value must be a number.
• WithMin is used to validate the minimum of value, value must be a number.

query.WithOffset is used to validate the offset value.

• WithMax is used to validate the maximum of offset, value must be a number.
• WithMin is used to validate the minimum of offset, value must be a number.
• WithNotAllowed is used to validate the offset value that are not allowed.

query.WithLimit is used to validate the limit value.

• WithMax is used to validate the maximum of limit, value must be a number.
• WithMin is used to validate the minimum of limit, value must be a number.
• WithNotAllowed is used to validate the limit value that are not allowed.

query.WithSort is used to validate the sort value.

• WithNotIn is used to validate the sort value that are not allowed.
• WithIn is used to validate the sort value that are allowed.
• WithNotAllowed is used to validate the sort value that are not allowed.

Example of validation:

validator := query.NewValidator(
    WithValue("member", query.WithRequired(), query.WithNotIn("O", "P", "S")),
    WithValues(query.WithIn("age", "test", "member")),
    WithValue("age", query.WithOperator(OperatorEq), query.WithNotOperator(OperatorIn)),
    WithField(query.WithNotAllowed()),
)

// after that use it to validate
err := validator.Validate(query)
if err != nil {
    // handle error
}

// or pass with when parsing
query, err := query.Parse(rawQuery, query.WithValidator(validator))
// ...