Build queries with QueryParams

Pikbase uses one query model across Entity Service, the CLI, MCP tools, and serverless functions. TypeScript callers use the fluent QueryParams builder; JSON callers send the fields produced by that builder.

Fluent TypeScript

import {
  IncludeQuery,
  QueryFunction,
  QueryParams,
  QuerySortType,
} from "@gsb-core/core";

const query = new QueryParams<Order>("Order")
  .filter("status", "open", QueryFunction.Equals)
  .include(new IncludeQuery<Customer>("customer").select(["id", "name"]))
  .self.sortBy("createDate", QuerySortType.Descending)
  .skip(0)
  .take(25)
  .select(["id", "status", "total", "createDate"])
  .returnCount();

const result = await entityService.query(query);

Every method returns the query. After include(), use .inc to configure the included query or .self to continue configuring the root.

CLI and MCP

Methods are not executable JSON. Send their serialized fields:

gsb call query --input '{
  "queryParams": {
    "entDefName": "Order",
    "filters": [{
      "col": { "name": "status" },
      "val": { "value": "open" },
      "function": 0
    }],
    "selectCols": [{ "name": "id" }, { "name": "status" }],
    "startIndex": 0,
    "count": 25,
    "calcTotalCount": true
  }
}' --raw

The CLI accepts the older tenant code-library fields query, propVal, and colName for compatibility, but normalizes them before calling Entity Service. Use filters, col/val, and name in all new code.

Keep queries bounded

• Select only fields the caller uses.
• Always set skip() and take() for lists.
• Request returnCount() only when the interface needs a total.
• Use include() instead of issuing N+1 queries.
• Prefer getById when the identifier is already known.

Continue with Advanced and extreme queries for correlated subqueries, aggregate comparisons, set membership, grouped analytics, and nested boolean logic. See the query operation reference for every field, function enum, and response shape.