@react-querybuilder/core

Core non-React utilities for React Query Builder — types, query processing, validation, formatters, and parsers.

Installation

npm i @react-querybuilder/core
# OR yarn add / pnpm add / bun add

Note: react-querybuilder re-exports everything from this package, so projects already using the main package don't need to install @react-querybuilder/core separately.

Export

Full export documentation

Use formatQuery to convert a query object into any of the supported output formats:

import { formatQuery } from '@react-querybuilder/core';

const query = {
  combinator: 'and',
  rules: [
    { field: 'first_name', operator: 'beginsWith', value: 'Stev' },
    { field: 'last_name', operator: 'in', value: 'Vai, Vaughan' },
  ],
};

formatQuery(query, 'sql');
// "(first_name like 'Stev%' and last_name in ('Vai', 'Vaughan'))"

Supported export formats

| Format | formatQuery type string | Output type | Description | | ------------------------------------------------------------------------------- | ------------------------- | ----------------------- | ------------------------------------------- | | JSON (formatted) | "json" | string | 2-space indented JSON.stringify | | JSON (no IDs) | "json_without_ids" | string | Compact JSON without id/path properties | | SQL | "sql" | string | Standard WHERE clause | | SQL (parameterized) | "parameterized" | ParameterizedSQL | SQL with anonymous (?) bind variables | | SQL (named params) | "parameterized_named" | ParameterizedNamedSQL | SQL with named (:param) bind variables | | MongoDB | "mongodb_query" | Record<string, any> | MongoDB query object | | CEL | "cel" | string | Common Expression Language | | SpEL | "spel" | string | Spring Expression Language | | JsonLogic | "jsonlogic" | JsonLogic | JsonLogic object | | JSONata | "jsonata" | string | JSONata expression | | ElasticSearch | "elasticsearch" | Record<string, any> | ElasticSearch query DSL | | LDAP | "ldap" | string | LDAP filter string | | Cypher | "cypher" | string | Neo4j Cypher WHERE clause | | SPARQL | "sparql" | string | SPARQL FILTER clause | | Gremlin | "gremlin" | string | Apache TinkerPop Gremlin traversal | | Natural language | "natural_language" | string | Human-readable description | | Drizzle | "drizzle" | Drizzle SQL | Drizzle ORM where clause | | Prisma | "prisma" | Record<string, any> | Prisma where object | | Sequelize | "sequelize" | Record<string, any> | Sequelize where object |

See @react-querybuilder/datetime and @react-querybuilder/expr for additional, enhanced export capabilities.

Import

Full import documentation

Parser functions convert query strings or objects from various languages into React Query Builder query objects. Each parser must be imported from its own sub-path.

import { parseSQL } from '@react-querybuilder/core/parseSQL';

// Accepts a full SELECT statement or just a WHERE clause
const query = parseSQL(
  `SELECT * FROM my_table WHERE first_name LIKE 'Stev%' AND last_name IN ('Vai', 'Vaughan')`
);

Supported import formats

| Format | Import statement | | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | | SQL | import { parseSQL } from "@react-querybuilder/core/parseSQL" | | MongoDB | import { parseMongoDB } from "@react-querybuilder/core/parseMongoDB" | | JsonLogic | import { parseJsonLogic } from "@react-querybuilder/core/parseJsonLogic" | | JSONata | import { parseJSONata } from "@react-querybuilder/core/parseJSONata" | | CEL | import { parseCEL } from "@react-querybuilder/core/parseCEL" | | SpEL | import { parseSpEL } from "@react-querybuilder/core/parseSpEL" | | Cypher | import { parseCypher } from "@react-querybuilder/core/parseCypher" | | GQL | import { parseGQL } from "@react-querybuilder/core/parseCypher" | | SPARQL | import { parseSPARQL } from "@react-querybuilder/core/parseSPARQL" | | Gremlin | import { parseGremlin } from "@react-querybuilder/core/parseGremlin" |

Query manipulation

Full documentation

Programmatically modify query objects with the same functions used internally by the <QueryBuilder /> component:

import { add, remove, update, move } from '@react-querybuilder/core';

const updated = add(query, newRule, parentPath);
const removed = remove(query, rulePath);
const modified = update(query, 'value', 'newValue', rulePath);
// `update` can also set multiple properties at once, via a map or parallel arrays:
const multi = update(query, { valueSource: 'field', value: 'otherField' }, rulePath);
const moved = move(query, oldPath, newPath);

Available methods: add, remove, update, move, insert, group.

transformQuery

Full documentation

Recursively processes a query object, transforming rules, groups, operators, combinators, and property names:

import { transformQuery } from '@react-querybuilder/core';

const transformed = transformQuery(query, {
  operatorMap: { '=': '==', '!=': '<>' },
  combinatorMap: { and: '&&', or: '||' },
  propertyMap: { field: 'column' },
  ruleProcessor: rule => ({ ...rule, value: rule.value.trim() }),
});

TypeScript

The core package exports the complete type system used throughout React Query Builder, enabling strongly-typed query manipulation without a React dependency:

import type {
  RuleGroupType, // Standard query structure (combinators at group level)
  RuleGroupTypeIC, // Independent combinators structure
  RuleType, // Individual rule
  FullField, // Field definition with all options
  FullOperator, // Operator definition
  FullCombinator, // Combinator definition
  ExportFormat, // Union of all format strings
  DefaultRuleGroupType,
  DefaultRuleType,
} from '@react-querybuilder/core';

Further reading

• Full documentation
• API reference
• Demo