Query URL Parameters

Query URL Parameters #

The query URL parameters can be used in many places (e.g., HTTP API endpoints, internal service calls, debug consoles). We use them to unify how queries are received and processed across different components of the system. This provides a powerful, composable, and human-readable way to construct both full-text search and structured filters, while also supporting advanced features like fuzziness, field selection, and pagination.

πŸ”§ Query URL Parameters #

These URL parameters are used to construct a rich and dynamic search query.

NameTypeDescriptionExample
querystringThe main query string. Supports field boosting (field^boost:value).query=title^2:search engine
filterstring[]One or more filter clauses. Can be negated with - or !. Supports:filter=status:active, filter=-exists(deleted_at)
- field=value, field!=value, field>=x, field<yfilter=age>=18, filter=tag!=archived
- exists(field)filter=exists(status)
sortstringSort rules separated by comma. Each rule is field[:asc|desc].sort=published_at:desc,_score
fromintPagination offset.from=20
sizeintNumber of results to return.size=10
fuzzinessintFuzziness level for the query (0–5).fuzziness=3
default_operatorstringOperator between terms if not specified (AND or OR).default_operator=AND
default_fieldsstringComma-separated list of fields used as fallback for both query and filter.default_fields=title,description
default_query_fieldsstringComma-separated list of fields used only for full-text search.default_query_fields=title,body
default_filter_fieldsstringComma-separated list of fields used only for filters.default_filter_fields=status,tag
_source_includesstringComma-separated fields to include in _source._source_includes=title,author
_source_excludesstringComma-separated fields to exclude from _source._source_excludes=internal_notes,raw_data

🧠 Filter Syntax Summary #

SyntaxMeaningExample
field=valueTerm querystatus=active
field!=valueNegated termstatus!=deleted
field>=valueRange query (greater than or equal)views>=1000
field<valueRange query (less than)age<30
any(field)Terms filter (any term can be match)any(tag1,tag2,tag3)
exists(field)Field existence checkexists(tags)
-filterExpr / !filterExprNegate any filter expression!exists(deleted_at)

πŸš€ Example #

GET /search?query=go+language&default_fields=title,description

Filtered and Sorted #

GET /search?query=distributed+search&filter=status=active&sort=_score:desc,created_at:desc

Advanced with Fuzziness and Range #

GET /search?query=search&fuzziness=3&filter=age>=18&filter=!exists(deleted_at)&size=20

🧩 Notes #

  • Filters are ANDed together by default.
  • Negated filters use either - or ! prefix.
  • If query is not provided, only filters will be applied.
  • Supports combining query string logic and JSON body input (BuildQueryDSLOnTopOfDSL handles merging).
  • Values in filters are auto-casted to int, bool, or string.

Example usage:

	q := orm.NewQuery().Must(
		orm.ShouldQuery(
			orm.MatchQuery("lang", "en"),
			orm.MatchQuery("lang", "zh"),
		),
		orm.MustNotQuery(
			orm.TermQuery("deleted", true),
		),
	).Size(10).SortBy(
		orm.Sort{Field: "score", SortType: orm.DESC},
	)
Edit Edit this page