Docyrus Query Builder

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-docyrus-query-builder

pnpm add react-querybuilder

npx shadcn@latest add badge button checkbox collapsible command input label popover radio-group scroll-area select switch table tabs toggle-group tooltip

Usage

'use client';

import { useState } from 'react';

import {
  DocyrusQueryBuilder,
  type ISelectQueryParams
} from '@docyrus/ui/components/docyrus-query-builder';

export function MyQueryBuilder() {
  const [query, setQuery] = useState<Partial<ISelectQueryParams>>({});

  return (
    <DocyrusQueryBuilder
      value={query}
      onChange={setQuery}
    />
  );
}

With a Docyrus API client

Pass an authenticated RestApiClient from @docyrus/api-client (or any object that implements the DocyrusQueryBuilderClient shape) to enable data-source discovery and query previews.

import { useDocyrusClient } from '@docyrus/signin';

export function MyAuthedQueryBuilder() {
  const client = useDocyrusClient();
  const [query, setQuery] = useState<Partial<ISelectQueryParams>>({});

  return (
    <DocyrusQueryBuilder
      client={client}
      value={query}
      onChange={setQuery}
    />
  );
}

Without a client (offline / preset data)

Skip the client and supply dataSources and fields yourself for offline editing and form-driven workflows.

<DocyrusQueryBuilder
  value={query}
  onChange={setQuery}
  dataSources={myDataSources}
  fields={myFields}
/>

EditorAgent integration

Pair useApplyQuery with renderAiAssistant to let an LLM author Docyrus query specs. The hook owns the controlled value and ships an applyQuery tool that the agent calls to commit a new query spec — the tool guards against primitives / arrays / null so a malformed payload cannot crash the builder.

import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import {
  DocyrusDataSourceQueryBuilder,
  useApplyQuery
} from '@docyrus/ui/components/docyrus-query-builder';

export function QueryBuilderPlayground({ client, user, agentId }) {
  const query = useApplyQuery();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <DocyrusDataSourceQueryBuilder
      client={client}
      value={query.query}
      onChange={query.setQuery}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose, selectedDataSource }) => (
        <EditorAgent
          agentId={agentId}
          client={client}
          user={user}
          open={open}
          onClose={onClose}
          dataSourceId={selectedDataSource?.id ?? null}
          clientTools={query.tools}
        />
      )}
    />
  );
}

The matching backend agent must register a tool named applyQuery whose input schema mirrors { value: object (required), explanation?: string }.

Columns — current + parent data sources

The Columns section is a single grouped, multi-select tree (no separate "selected columns" pane). In both the current and parent groups, user fields (field-userSelect / field-userMultiSelect) and enum fields (field-select, field-radioGroup, field-enum, field-status, field-multiSelect, field-tagSelect) are expandable into a fixed sub-field catalog — user → id, firstname, lastname, email, photo; enum → id, autonumber_id, name, slug, icon, color. A checked sub-field nests at the correct depth, e.g. status(id, name) or company(owner(firstname, email)) (parent).

The header carries a Parent Data Sources switch (its state lives in the hook, so it survives switching to Run & Preview / JSON and back). It pulls fields from the data sources referenced by the current data source's field-relation columns and nests a checked field under its relation column, e.g. company(title, industry). It requires a client; fields come from GET /v1/dev/data-sources/:id/fields?expand=parent (the parent expansion returns each parent's full field list keyed by data source id). The same wiring is exposed on the hook as fetchRelatedFields(['parent', 'child']) for custom UIs.

Child Queries

The Child Queries panel (enabled via enableChildQueries) fetches related records as nested arrays, one per child data source. It uses the child expansion of the same endpoint (GET /v1/dev/data-sources/:id/fields?expand=child) to discover the data sources whose own field-relation points back to the current one:

1. Pick a child data source from the Add child data source dropdown — this creates an entry whose From and Using are auto-filled and read-only (from = the child data source as a {appSlug}_{slug} reference, e.g. base_callcenter_call; using = its back-reference relation field slug).
2. Select the columns to return via a multi-select tree-view of the child data source's own fields (with the same user / enum sub-field expansion as the Columns section).
3. Optionally set Order By (a field dropdown + asc/desc direction) and Limit.

value.childQueries is an array of { alias, from, using, columns, orderBy?, limit? }. The alias (the result key the child rows are returned under) defaults to the child data source slug, and the editor automatically keeps it listed in the parent value.columns — the items endpoint drops the child block unless its alias is also a parent column (so the emitted request is ?columns=…,alias&childQueries=[{ alias, from, using, … }]). Removing an entry strips its alias from the columns again. Child data sources load when the panel opens (it flips relatedExpand.child); the fetch is de-duped per (dataSource, expand) signature.

Custom filter controls

The Filters section renders a QueryBuilderDocyrus. filterControlElements hands that builder a set of react-querybuilder control elements (merged over the Docyrus defaults) and filterContext travels alongside as react-querybuilder's context, so a host can replace the rule value editor without teaching this component anything about its domain — an automation editor offering Fixed value / Field / Expression modes that write #FIELD= / #FORMULA= markers, for example. Wrap QBValueEditor for the plain-value case so relation pickers, async options and between inputs keep working, and keep the object reference stable (module constant or useMemo) — a fresh object per render re-renders every rule.

import { QBValueEditor, type ValueEditorProps } from '@/components/docyrus/query-builder';

function RuntimeValueEditor(props: ValueEditorProps) {
  const { inputSchema } = props.context as { inputSchema: JsonSchema };

  return isMarker(props.value)
    ? <MarkerEditor {...props} schema={inputSchema} />
    : <QBValueEditor {...props} />;
}

const FILTER_CONTROLS = { valueEditor: RuntimeValueEditor };

<DocyrusDataSourceQueryBuilder
  value={query}
  onChange={setQuery}
  filterControlElements={FILTER_CONTROLS}
  filterContext={{ inputSchema }} />

Both props are no-ops when omitted.

API Reference

Components

Type Exports

Helpers