Query

The query module owns query input concerns for Tulip data surfaces.

Use it to define URL-backed filters, typed sorting, offset pagination, API input schemas, and portable compiler input that can be consumed by database, local, provider-specific, and table layers.

Responsibilities

• define filter descriptors and convert them into portable condition trees
• define sort options and convert them into portable sort arrays
• own pagination state, URL search params, API schemas, and response DTOs
• expose client hooks for resolved query input
• keep data-table strategies focused on table state instead of query construction

Entry Points

Use the server-safe entrypoint for definitions, schemas, parsers, DTOs, and converters:

import {
  defineFilters,
  defineSorting,
  offsetPaginationResponse,
  offsetPaginationSchema,
  resolveFiltersSchema,
  resolveSortingSchema,
  stringFilter,
} from "@tulip-systems/query";

Use the client entrypoint for hooks and interactive filter UI:

import {
  FilterCombobox,
  FilterSearch,
  useFilters,
  usePagination,
  useSorting,
} from "@tulip-systems/query/client";

The server entrypoint mirrors the server-safe exports:

import { defineFilters, offsetPaginationResponse } from "@tulip-systems/query/server";

Query Input Shape

Most server-backed tables and collections use the same shape:

const input = useDeferredValue({
  pagination: pagination.input,
  filters: filtering.input,
  sorts: sorting.input,
});

pagination.input, filtering.input, and sorting.input are already resolved with defaults and constraints. Pass those values to queries instead of rebuilding search-param state in the table layer.

Module Boundaries

Query owns query state and query input. Data tables consume the resolved controllers.

const pagination = usePagination(offsetPagination);
const filtering = useFilters(projectFilters);
const sorting = useSorting(projectSorting);

const strategy = usePaginationStrategy({ pagination });

const config = createTableConfig({
  queryData: data,
  columns,
  strategy,
  pagination,
  filtering,
  sorting,
});

Import query APIs from @tulip-systems/query or @tulip-systems/query/client. Do not import filters, sorting, or pagination definitions from data-tables.

Related Pages