Query

The query endpoint supports rich filtering, sorting, and pagination in a single POST request.

POST /api/{entity}/query
Content-Type: application/json

Request Body

{
  "paginationData": {
    "page": 0,
    "size": 10
  },
  "sort": ["name;asc", "price;desc"],
  "queryCriteriaList": [
    {
      "field": "status",
      "value": "IN_STOCK",
      "operator": "EQ"
    }
  ]
}

All fields are optional:

Field	Type	Description
paginationData	Object	Pagination config. If omitted, all matching records are returned without a size limit.
paginationData.page	int	Page index, 0-based (min: 0)
paginationData.size	int	Records per page (min: 1)
sort	string[]	Sort expressions in field;direction format (asc or desc). Multiple values apply in order.
queryCriteriaList	array	List of filter criteria. All criteria are combined with AND logic.

Sort format

Sort values use a semicolon separator: "name;asc", "price;desc".

Filter Criteria

Each entry in queryCriteriaList has:

Field	Required	Description
operator	Yes	The comparison operator (see table below)
field	Depends	The entity field to filter on. Required for all operators except GLOBAL.
value	Depends	The value to compare against. Not required for NULL, NOT_NULL, EMPTY, NOT_EMPTY.
columns	Only for GLOBAL	List of field names to search across (global full-text search).

Operators

Operator	Description	Value type
EQ	Equals	scalar
NE	Not equals	scalar
GT	Greater than	scalar
GE	Greater than or equal	scalar
LT	Less than	scalar
LE	Less than or equal	scalar
STARTS_WITH	String starts with	string
ENDS_WITH	String ends with	string
CONTAINS	String contains	string
NOT_CONTAINS	String does not contain	string
IN	Value is in list	array
NOT_IN	Value is not in list	array
CONTAINS_ANY	Collection contains any of	array
CONTAINS_ALL	Collection contains all of	array
CONTAINS_NONE	Collection contains none of	array
NULL	Field is null	—
NOT_NULL	Field is not null	—
EMPTY	Collection/string is empty	—
NOT_EMPTY	Collection/string is not empty	—
GLOBAL	Full-text search across multiple columns	string (use columns to specify fields)

Examples

Filter by status with pagination

{
  "paginationData": { "page": 0, "size": 20 },
  "sort": ["name;asc"],
  "queryCriteriaList": [
    { "field": "status", "value": "IN_STOCK", "operator": "EQ" }
  ]
}

Filter by price range

{
  "queryCriteriaList": [
    { "field": "price", "value": 50, "operator": "GE" },
    { "field": "price", "value": 200, "operator": "LE" }
  ]
}

Filter by a list of IDs

{
  "queryCriteriaList": [
    { "field": "reference", "value": ["AB-001", "AB-002", "AB-003"], "operator": "IN" }
  ]
}

Global search across multiple fields

{
  "paginationData": { "page": 0, "size": 10 },
  "queryCriteriaList": [
    {
      "operator": "GLOBAL",
      "value": "headphones",
      "columns": ["name", "description", "category.name"]
    }
  ]
}

Records with no category assigned

{
  "queryCriteriaList": [
    { "field": "category", "operator": "NULL" }
  ]
}

Response

200 OK — a Spring Page with matching records:

{
  "content": [
    {
      "reference": "AB-001",
      "name": "Headphones",
      "price": 199.99,
      "category": { "id": 1, "name": "Electronics" },
      "status": "IN_STOCK"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "size": 10,
  "number": 0
}

If paginationData is omitted, totalPages is 1, size equals totalElements, and all results are in content.

Access Control

Requires the read authority for the entity. See RBAC.