Docyrus Query Builder

Installation

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

pnpm add @react-querybuilder/core react-native-reanimated react-native-gesture-handler @shopify/flash-list tailwind-variants

DocyrusDataSourceQueryBuilder is the React Native port of the web component with the same name. It uses the same query model (ISelectQueryParams) and the same hook (useDocyrusQueryBuilder). Its section editors produce the same payload for the Docyrus items endpoint (/v1/apps/{app}/data-sources/{ds}/items), so a query written on a phone can be saved and run on the web without changes, and the other way round.

The layout is built for mobile:

• Primary tabs: Configure, Preview and JSON.
• Configure shows one row per section with a live summary, such as "Filters · 3 rules" or "Columns · 12 selected". Tapping a row opens that section in a full-height bottom sheet (presentation="sheet", the default) or inline with a back row ("stack"). You can also push your own screen from onSectionPress.
• Preview calls runQuery() and shows the returned rows in a horizontally scrolling read-only table, with the row count, the total and any error.
• JSON shows the cleaned payload read-only in a monospace font, in pretty or compact form. It has a Copy button when you pass onCopy. The component adds no clipboard dependency, so wire expo-clipboard or a similar library yourself.

Every section except Select Data Source stays disabled until a data source is selected.

Works without a client

When you pass dataSources, and optionally fields, but no client, every configure section still works offline. Only Run needs a client: without one, it reports that authentication is required. With a client, the builder:

• discovers data sources (/v1/apps/data-sources)
• loads the selected source's schema including enums (/v1/apps/{app}/data-sources/{ds}?expand=enums)
• loads user, team, role and org-unit filter options (/v1/users, /v1/teams, /v1/users/acl/roles, /v1/users/acl/hierarchy-units)
• loads relation filter pickers (…/items?columns=id,name)
• loads parent and child field groups (/v1/dev/data-sources/:id/fields?expand=parent,child)
• runs the query (/items)

Usage

import { useState } from 'react';

import * as Clipboard from 'expo-clipboard';

import { useDocyrusClient } from '@docyrus/signin/react-native';

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

export function QueryScreen() {
  const client = useDocyrusClient();
  const [value, setValue] = useState<Partial<ISelectQueryParams>>({});

  return (
    <DocyrusDataSourceQueryBuilder
      client={client}
      value={value}
      onChange={setValue}
      enableCalculations
      enableChildQueries
      onCopy={json => void Clipboard.setStringAsync(json)}
      className="flex-1" />
  );
}

Offline, with a fixed data source

<DocyrusDataSourceQueryBuilder
  value={{ dataSourceId: 'ds-contact', dataSourceFullSlug: 'crm.contact', limit: 25 }}
  onChange={setValue}
  dataSources={[contactDataSource]}
  lockDataSource
  presentation="stack" />

Pushing sections as screens

When onSectionPress returns true, the builder does not open the section itself. Render the matching section editor on your own screen inside a DSQBContext provider that holds the builder's hook result:

const dsqb = useDocyrusQueryBuilder({ value, onChange, client });

<DSQBContext value={dsqb}>
  <DSQBFiltersEditor />
</DSQBContext>

Sections

API Reference

DocyrusDataSourceQueryBuilderProps

DSQBFieldSelector

DSQBJsonPreview

DSQBFormulaBlock

The other section editors take no props. They read everything through useDSQB().

useDocyrusQueryBuilder(options)

It takes UseDocyrusQueryBuilderOptions: value, onChange, client, fields, dataSources, locale and size. It returns UseDocyrusQueryBuilderResult. The hook uses no React Query.

Context

DSQBContext and useDSQB() hold a DSQBContextValue: the hook result plus filterControlElements, renderFilterValueEditor and filterContext. useDSQB() throws when it is called outside the builder.

Components

Hooks, constants & utilities

Type Exports

Differences from web

• Removed: aiAssistantOpen, onAiAssistantOpenChange, renderAiAssistant, useApplyQuery, IQueryBuilderAiAssistantRenderContext and the Cody agent toggle.
• Added: presentation, onSectionPress, onCopy, renderFilterValueEditor.
• Changed: filterControlElements uses the native QBControlElements slot map. The web version uses react-querybuilder's ControlElementsProp. filterContext goes to renderFilterValueEditor, because the native builder has no context prop.
• Changed: defaultSection defaults to no open section. The web version always shows one section.
• Replaced interactions: Drag handles in Sort and Formulas become move up / move down buttons. Pivot date-range bounds are ISO text inputs instead of datetime-local.

Translations

All copy goes through useUiTranslation() under ui.docyrusQueryBuilder.*, with English fallbacks. The web component hard-codes English, so these keys are new: selectDataSource, columns, filters, sort, pagination, calculations, formulas, childQueries, pivot and their *Description keys, configure, preview, run, runQuery, running, searchFields, selectField, parentDataSources, allColumnsReturned, selected, keyword, filterRules, addSortRule, limit, offset, fullCount, addCalculation, advanced, distinct, addFormula, addInput, addWhen, addChildDataSource, addMatrixEntry, moveUp, moveDown, remove, copy, copied, pretty, compact, jsonOutput, noRows, runError, selectDataSourceFirst, the category* field-group labels and the empty or loading state messages.